danoszz/penthera

Escáner de Seguridad Penthera

Escáner de seguridad ligero para URLs, repositorios locales y auditorías de máquina (macOS). Siempre ejecute la puerta de autorización antes de cualquier escaneo.

Crítico: Puerta de autorización

No ejecute Penthera hasta que se confirme la autorización.

Antes del primer escaneo en una sesión, pida al usuario que confirme UNA de las siguientes opciones:

1. Es dueño del objetivo (aplicación, servidor, proyecto).
2. Tiene autorización por escrito del propietario del sistema.
3. El objetivo es localhost o un laboratorio privado que controla.

Si el usuario solicita escanear un dominio de terceros (p. ej., google.com, example.com) sin reclamar propiedad o autorización, deténgase y rechace. Ante la duda, no escanee.

Para conocer la política completa, consulte referencias/autorizacion.md.

Verificación previa

Ejecute antes del primer escaneo:

bash skills/penthera/scripts/preflight.sh [URL]

Desde la raíz del repositorio. Pase la URL objetivo para advertir sobre objetivos que no sean localhost. Corrija cualquier error antes de continuar.

Resolución del comando CLI

Use el que esté disponible:

penthera --version          # después de npm link
node bin/penthera.js --version   # desde la raíz del repo

Todos los ejemplos siguientes usan penthera; sustituya con node bin/penthera.js cuando sea necesario.

Árbol de decisión

Intención del usuario	Patrón de comando
Primer uso / sin certeza	penthera (asistente interactivo — TTY) o penthera-scan
Escanear una URL en vivo	penthera <url> --profile standard -o reports/scan.json
Escanear solo repositorio (secretos, rutas)	penthera --repo . -o reports/repo-scan.json
URL + fuente combinados	penthera <url> --repo . -o reports/scan.json --sarif reports/scan.sarif
Comparar con escaneo anterior	penthera <url> -o reports/scan.json --baseline reports/previous.json
Endpoints autenticados	Agregue --auth-cookie o --auth-bearer / variable de entorno PENTHERA_*
Auditoría de máquina macOS	penthera --machine

Comportamiento seguro por defecto

• Siempre use --profile standard a menos que el usuario solicite explícitamente pruebas más profundas.
• Escriba los informes en reports/ (ignorado por git), nunca dentro de skills/penthera/.
• Después del escaneo, lea el informe .md adjunto y resuma los hallazgos por severidad con recomendaciones de corrección.

Puerta de modo destructivo

Estas banderas envían cargas de ataque. Requieren confirmación explícita del usuario antes de usarse:

• --deep — sondas SQLi, SSTI, SSRF, XSS, CMDi
• --fuzz — fuzzing de API basado en propiedades
• --all — habilita recon + deep + fuzz
• --profile deep — cobertura máxima

Si el usuario solicita "pruebas de penetración completas" o "escaneo profundo", confirme que es dueño del objetivo y que acepta pruebas basadas en cargas.

Flujo de trabajo 1: Auditoría previa al lanzamiento

Desencadenantes: "escanear mi aplicación de staging", "auditoría de seguridad antes del despliegue", "revisar mi aplicación en busca de vulnerabilidades"

1. Confirme la autorización (vea la puerta más arriba).
2. Ejecute la verificación previa.
3. Ejecute:

mkdir -p reports
penthera https://staging.example.com --profile standard -o reports/scan.json

4. Lea reports/scan.md — resuma los hallazgos críticos/altos/medios.
5. Recomiende correcciones concretas por cada hallazgo.
6. Nota sobre el código de salida: 0 = sin críticos/altos; 1 = críticos/altos encontrados; 2 = escaneo fallido.

Flujo de trabajo 2: Repositorio + en vivo combinados

Desencadenantes: "escanear mi aplicación Next.js y staging", "escaneo de caja negra y caja blanca"

1. Confirme la autorización para la URL.
2. Ejecute la verificación previa con la URL.
3. Ejecute:

mkdir -p reports
penthera https://staging.example.com --repo . --profile standard \
  -o reports/scan.json --sarif reports/scan.sarif

4. Resuma los hallazgos de la URL (encabezados, TLS, CORS, autenticación) y del repositorio (secretos, rutas de API, límites de confianza).
5. Ofrezca cargar SARIF mediante GitHub Actions (consulte referencias/salida-y-ci.md).

Flujo de trabajo 3: CI / regresión con línea base

Desencadenantes: "comparar con el último escaneo", "solo hallazgos nuevos", "verificación de regresión"

1. Confirme la autorización y que reports/previous.json exista (o pida al usuario la ruta de la línea base).
2. Ejecute:

mkdir -p reports
penthera https://staging.example.com --profile standard \
  -o reports/scan.json --baseline reports/previous.json

3. Informe: cantidad de hallazgos nuevos, resueltos y sin cambios (impresos en stderr durante el escaneo).
4. Resuma solo los hallazgos nuevos.

Escaneos autenticados

Solo después de que pase la puerta de autorización:

# Token Bearer
PENTHERA_BEARER=eyJ... penthera https://myapp.com --profile standard -o reports/scan.json

# Cookie de sesión
penthera https://myapp.com --auth-cookie "session=abc123" -o reports/scan.json

# Banderas explícitas
penthera https://myapp.com --auth-bearer "eyJ..." -o reports/scan.json

Variables de entorno: PENTHERA_BEARER, PENTHERA_COOKIE.

Escaneo de secretos solo en repositorio

Desencadenantes: "encontrar secretos hardcodeados", "escanear este repositorio en busca de claves"

No se necesita autorización de URL para el análisis local del repositorio:

penthera --repo . -o reports/repo-scan.json

Resuma los hallazgos de secretos; recuerde al usuario que rote cualquier credencial expuesta.

Ejemplos

Ejemplo 1: Verificación rápida en localhost

Usuario: "Escanear mi aplicación localhost en el puerto 3000"

Acciones:

1. Confirme localhost — autorización satisfecha.
2. bash skills/penthera/scripts/preflight.sh http://localhost:3000
3. penthera http://localhost:3000 --profile quick -o reports/scan.json
4. Resuma reports/scan.md.

Ejemplo 2: Staging antes del despliegue

Usuario: "Auditar staging.myapp.com antes de enviar"

Acciones:

1. Pregunte: "¿Eres dueño o tienes autorización por escrito para staging.myapp.com?"
2. Tras la confirmación, ejecute un escaneo con perfil estándar y salida JSON + markdown.
3. Enumere los elementos críticos/altos primero, con pasos de corrección.

Ejemplo 3: Objetivo no autorizado (debe rechazarse)

Usuario: "Escanear google.com en busca de vulnerabilidades"

Acciones:

1. No ejecute Penthera.
2. Explique que no está permitido escanear sistemas de terceros sin autorización.
3. Ofrezca escanear su propia aplicación o localhost en su lugar.

No use esta habilidad para

• Ayuda general de codificación, clima o tareas no relacionadas
• Escanear sistemas que el usuario no posee o no tiene permiso para probar
• Explotación maliciosa o exfiltración de datos

Recursos adicionales

• Perfiles y banderas: referencias/perfiles-y-banderas.md
• Formatos de salida y CI: referencias/salida-y-ci.md
• Solución de problemas: referencias/solucion-de-problemas.md
• Política de autorización: referencias/autorizacion.md