Sistema de revisión y merge automático de Pull Requests con análisis de seguridad integrado.
Cero intervención humana. Reglas estrictas. Decisiones trazables.
AutoPR Lab es un sistema de revisión automática de Pull Requests construido sobre GitHub Actions y Python. Analiza cada PR en tiempo real, ejecuta detectores de seguridad modulares, y toma una de tres decisiones sin intervención humana:
| Decisión | Condición | Acción |
|---|---|---|
| ✅ MERGE | Sin problemas | Aprueba + merge automático |
| Solo advertencias | Aprueba + merge + comentario | |
| ❌ REJECT | Errores críticos | Comenta problemas + cierra PR |
AutoPR-Lab/
│
├── .github/
│ └── workflows/
│ └── auto-pr.yml # Workflow principal de GitHub Actions
│
├── core/
│ ├── __init__.py
│ └── scanner.py # Motor principal de análisis
│
├── detectors/
│ ├── __init__.py # Auto-descubrimiento de detectores
│ ├── base_detector.py # Clase base abstracta (contrato)
│ ├── api_keys_detector.py # Detecta API keys y tokens
│ ├── passwords_detector.py # Detecta passwords hardcodeados
│ ├── sensitive_files_detector.py # Detecta archivos sensibles
│ └── detector_validator.py # Valida estructura de detectores nuevos
│
├── utils/
│ ├── __init__.py
│ ├── github_api.py # Cliente de la GitHub REST API
│ ├── comment_templates.py # Templates para comentarios del bot
│ └── logger.py # Sistema de logging con colores
│
├── scripts/
│ └── decision_engine.py # Entry point: orquesta todo el flujo
│
├── tests/
│ ├── test_detectors.py # Tests unitarios de detectores
│ └── test_scanner.py # Tests de integración del scanner
│
├── docs/
│ ├── how-to-add-detector.md # Guía para contributors
│ └── example-outputs.md # Ejemplos de outputs del sistema
│
├── examples/
│ ├── valid-pr/ # Ejemplos de PRs que serán aceptados
│ └── invalid-pr/ # Ejemplos de PRs que serán rechazados
│
└── requirements.txt # Dependencias (solo stdlib de Python)
Los detectores son módulos independientes que analizan el código y devuelven resultados estandarizados:
@dataclass
class DetectorResult:
status: DetectorStatus # OK | WARNING | ERROR
detector_name: str
message: str
details: List[str]
file_path: Optional[str]
line_number: Optional[int]| Detector | Qué detecta | Severidad |
|---|---|---|
APIKeysDetector |
GitHub tokens, OpenAI keys, AWS secrets, claves RSA, URLs con credenciales | 🔴 Critical |
PasswordsDetector |
Passwords hardcodeados, contraseñas triviales, tokens de autenticación | 🔴 Critical |
SensitiveFilesDetector |
.env, .pem, .key, credentials.json, archivos de BD |
🔴 Critical |
DetectorFormatValidator |
Estructura, imports prohibidos, eval/exec, herencia correcta |
🔴 Critical |
El sistema solo permite merge automático cuando se cumplen TODAS estas condiciones:
detectors/ ← Nuevos detectores
tests/ ← Tests
docs/ ← Documentación
examples/ ← Ejemplos
README.md ← Readme principal
core/ ← Motor principal (requiere revisión manual)
.github/workflows/ ← Workflows de CI/CD (crítico)
scripts/ ← Scripts de decisión
requirements.txt ← Dependencias
pyproject.toml ← Configuración del proyecto
Makefile ← Automatización
- Máximo 10 archivos por PR
- Máximo 500 líneas cambiadas
PR Abierto/Actualizado
│
▼
┌─────────────────────────────────┐
│ GitHub Actions Trigger │
│ on: pull_request │
└─────────────┬───────────────────┘
│
▼
┌─────────────────────────────────┐
│ decision_engine.py │
│ - Lee variables de entorno │
│ - Obtiene archivos del PR │
└─────────────┬───────────────────┘
│
▼
┌─────────────────────────────────┐
│ SecurityRules.validate_paths │
│ - ¿Rutas permitidas? │
│ - ¿Tamaño dentro de límites? │
└─────────────┬───────────────────┘
│
▼
┌─────────────────────────────────┐
│ Scanner.scan_pr │
│ - Ejecuta TODOS los │
│ detectores sobre cada │
│ archivo del PR │
└─────────────┬───────────────────┘
│
┌─────────┼──────────┐
▼ ▼ ▼
ERROR WARNING OK
│ │ │
▼ ▼ ▼
REJECT WARN_MERGE MERGE
│ │ │
▼ ▼ ▼
Comentar Aprobar Aprobar
+ Cerrar + Merge + Merge
+ Comentar
git clone https://github.com/devsebastian44/AutoPR-Lab.git
cd AutoPR-LabEl workflow en .github/workflows/auto-pr.yml se activa automáticamente en cada PR.
No necesitas configurar nada adicional — usa el GITHUB_TOKEN que GitHub provee automáticamente.
En Settings → Actions → General:
- Marcar "Read and write permissions" para el GITHUB_TOKEN
- Marcar "Allow GitHub Actions to create and approve pull requests"
# Instalar dependencias (solo para desarrollo)
pip install -r requirements.txt
# Ejecutar tests
python -m pytest tests/ -v
# Dry run (sin ejecutar acciones reales en GitHub)
export GITHUB_TOKEN="tu_token"
export GITHUB_REPOSITORY="owner/repo"
export PR_NUMBER="123"
export DRY_RUN="true"
python scripts/decision_engine.py- Crea
/detectors/mi_detector.pyheredando deBaseDetector - Crea
/tests/test_mi_detector.pycon tests unitarios - Abre un PR — AutoPR Lab lo revisará y mergeará automáticamente si está bien formado
# detectors/mi_detector.py
from detectors.base_detector import BaseDetector, DetectorResult, DetectorStatus
from typing import List
class MiDetector(BaseDetector):
@property
def name(self) -> str:
return "MiDetector"
@property
def description(self) -> str:
return "Detecta X en el código"
@property
def severity(self) -> str:
return "high" # critical | high | medium | low
def analyze(self, file_path: str, content: str) -> List[DetectorResult]:
results = []
# Tu lógica aquí...
return resultsVer guía completa: docs/how-to-add-detector.md
❌ [ERROR] APIKeysDetector: Posible OpenAI API Key detectado
- Patrón detectado: sk-ab****ijk (detectors/bad.py, línea 5)
❌ [ERROR] PasswordsDetector: Password hardcodeado en 'DATABASE_PASSWORD'
- Variable: DATABASE_PASSWORD (config.py, línea 12)
DECISIÓN: REJECT
→ PR comentado y cerrado automáticamente
✅ [OK] DetectorFormatValidator: Estructura del detector válida
✅ [OK] APIKeysDetector: Sin credenciales detectadas
✅ [OK] PasswordsDetector: Sin passwords hardcodeados
✅ [OK] SensitiveFilesDetector: Sin archivos sensibles
DECISIÓN: MERGE
→ PR aprobado y mergeado automáticamente en 89ms
Ver más ejemplos: docs/example-outputs.md
- Validación de paths: Solo archivos en rutas explícitamente permitidas
- Análisis estático de AST: Los detectores nuevos son analizados con
ast.parse()antes de ser aceptados - Imports prohibidos:
subprocess,socket,requests,eval,execson bloqueados automáticamente - Límites de tamaño: PRs grandes requieren revisión manual
- Sin ejecución de código: Los detectores NUNCA ejecutan el código que analizan, solo lo leen como texto
Cualquier cambio en estas áreas nunca se auto-mergea:
- El motor de decisión (
src/core/,scripts/) - Los workflows de GitHub Actions
- Las dependencias del proyecto
Para mantener los estándares más altos de seguridad profesional, AutoPR-Lab utiliza una arquitectura de repositorio dual.
- GitLab (Laboratorio Privado): Actúa como el Source of Truth. Contiene todo el código núcleo (
src/core), tests exhaustivos de vulnerabilidades, pipelines de Integración Continua (.gitlab-ci.yml) y scripts de publicación de automatización privada. Aquí es donde se realiza todo el desarrollo y de donde se extraen las métricas. - GitHub (Portafolio Público): Es un entorno estrictamente sanitizado. Sirve como muestra pública, portafolio y demostración de arquitectura. Las partes críticas de análisis, tests ofensivos/defensivos y flujos de automatización privada son extraídas sistemáticamente.
El script ./scripts/publish_public.ps1 garantiza que nunca se filtren componentes sensibles del laboratorio al portafolio.
Ejecuta el siguiente pipeline seguro:
- Validar el estado limpio de la rama
mainy sincronizar contra GitLab. - Crear un entorno en una rama de publicación aislada temporal.
- Ejecutar
git rmestructurado para borrar toda la ruta de tests, configuraciones, infraestructura de despliegue interno y lógica pesada. - Efectuar un un force-push de la versión higienizada a GitHub origin.
- Devolver al desarrollador intacto al entorno del Laboratorio Privado.
Puedes consultar el diagrama detallado del flujo en diagrams/architecture.md.