🏗️ Arquitectura

┌──────────────────────────────────────────────────────────┐
│  $ pentest ask --query "scan for SQLi and XSS" \         │
│                --target http://localhost:3000 --consent  │
└──────────────────┬───────────────────────────────────────┘
                   │ Direct Python execution
                   ▼
┌──────────────────────────────────────────────────────────┐
│            GEMINI-POWERED AGENT (Python)                 │
│                                                          │
│  Phase 1: PLAN    → LLM selects tools from query        │
│  Phase 2: EXECUTE → Runs tools, collects findings       │
│  Phase 3: REPORT  → LLM generates professional report   │
│                                                          │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────┐  │
│  │   Session    │  │  Scan Mode   │  │   Tool         │  │
│  │   Manager    │  │  Orchestrator│  │   Registry     │  │
│  └─────────────┘  └──────┬───────┘  └────────────────┘  │
│                          │                               │
│         ┌────────────────┼────────────────┐              │
│         ▼                ▼                ▼              │
│  ┌────────────┐  ┌────────────┐  ┌────────────────┐     │
│  │   nmap     │  │   sqlmap   │  │   ffuf         │     │
│  │   nuclei   │  │   dalfox   │  │   nikto        │     │
│  │   sslyze   │  │   commix   │  │   gobuster     │     │
│  │   wafw00f  │  │   arjun    │  │   subfinder    │     │
│  │   ... 30+  │  │   ...      │  │   ...          │     │
│  └────────────┘  └────────────┘  └────────────────┘     │
│                          │                               │
│                          ▼                               │
│              ┌──────────────────────┐                    │
│              │    GEMINI API        │                    │
│              │  (Flash Lite)       │                    │
│              │  Triage · Analysis  │                    │
│              │  CVSS · Reporting   │                    │
│              └──────────────────────┘                    │
└──────────────────────────────────────────────────────────┘

✨ Características

Característica	Descripción
Interfaz de lenguaje natural	Haz preguntas de seguridad en inglés sencillo: la IA selecciona y ejecuta las herramientas adecuadas
3 modos de escaneo	Rápido (5-10 min), Medio (15-30 min), Extenso (45+ min), cada uno con distinta profundidad y análisis de IA
Más de 30 herramientas de seguridad	nmap, sqlmap, nuclei, ffuf, dalfox, nikto, wafw00f, subfinder, sslyze y más
Análisis impulsado por IA	Gemini AI (Flash Lite) realiza el triaje de vulnerabilidades, puntuación CVSS y genera informes ejecutivos
Selección automatizada de herramientas	Comando `pentest ask` para la planificación y ejecución de herramientas impulsada por LLM
Gestión de sesiones	Rastrea, pausa y reanuda evaluaciones de seguridad en múltiples objetivos
Cobertura OWASP Top 10	Escaneo sistemático mapeado a las categorías OWASP 2021
Alternativas inteligentes	Si una herramienta profesional no está instalada, las implementaciones nativas de Python cubren el vacío

📋 Tabla de contenidos

🚀 Inicio rápido

Requisitos previos

Python 3.11+
uv (gestor de paquetes de Python)
Clave de API de Gemini (nivel gratuito disponible)

1. Clonar e instalar

git clone https://github.com/yourusername/pentest-ai-cli
cd pentest-ai-cli

# Install dependencies
uv sync

2. Configurar el entorno

cp .env.example .env

Edita .env y añade tu clave de API de Gemini:

GEMINI_API_KEY=your_gemini_api_key_here

3. Instalar herramientas de seguridad (opcional)

El servidor funciona con alternativas nativas de Python, pero para un escaneo de nivel profesional, instala las herramientas externas:

# macOS (Homebrew)
brew install nmap sqlmap

# Install ffuf (Go-based fuzzer)
go install github.com/ffuf/ffuf/v2@latest

# Install nuclei (vulnerability scanner)
go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest

# Install subfinder (subdomain discovery)
go install github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest

Consejo: Ejecuta session_init para ver qué herramientas se detectan en tu sistema.

4. ¡Comienza a escanear!

pentest ask \
  --query "run a quick security scan" \
  --target https://example.com \
  --consent

🎯 Modos de escaneo

Modo rápido (5-10 minutos)

Triaje rápido para una evaluación de riesgos inmediata.

Prueba	Herramienta
Detección de WAF	wafw00f / personalizado
Enumeración de DNS	dnsrecon / personalizado
Escaneo de puertos (top 20)	nmap / personalizado
Análisis de cabeceras	personalizado
Auditoría TLS/SSL	sslyze / personalizado
Huella digital tecnológica	whatweb / personalizado
Descubrimiento de archivos sensibles	ffuf / personalizado

Modo medio (15-30 minutos)

Prueba de penetración estándar que cubre el OWASP Top 10.

Prueba	Herramienta
Todo lo del modo rápido	—
Escaneo de puertos (top 100)	nmap
Escaneo XSS	dalfox / personalizado
Inyección SQL	sqlmap
Descubrimiento de directorios	ffuf / gobuster
Mala configuración de CORS	corscanner / personalizado
Path Traversal	personalizado
Redirección abierta	personalizado
Comprobaciones CSRF	personalizado

Modo extenso (45+ minutos)

Evaluación de seguridad integral a nivel directivo.

Prueba	Herramienta
Todo lo del modo medio	—
Escaneo de puertos (top 1000)	nmap / masscan
Enumeración de subdominios	subfinder / amass
Fuzzing avanzado	wfuzz / ffuf
Sondeo SSRF	personalizado
Escaneo de secretos	trufflehog
Exposición Git	git-dumper
Análisis JWT	jwt_tool
Seguridad GraphQL	graphql-cop
Inyección de comandos	commix

🔧 Herramientas compatibles

El servidor integra más de 30 herramientas de seguridad con detección automática. Si una herramienta no está instalada, las alternativas nativas de Python aseguran que el escaneo continúe.

Herramienta	Categoría	Requerido
nmap	Escaneo de puertos	Opcional (tiene alternativa)
sqlmap	Inyección SQL	Opcional
ffuf	Fuzzing / descubrimiento de archivos	Opcional (tiene alternativa)
nuclei	Escaneo de vulnerabilidades	Opcional
dalfox	Escaneo XSS	Opcional
subfinder	Descubrimiento de subdominios	Opcional
wafw00f	Detección de WAF	Opcional (tiene alternativa)
sslyze	Auditoría TLS/SSL	Opcional (tiene alternativa)
nikto	Escaneo de servidor web	Opcional
gobuster	Fuerza bruta de directorios	Opcional
whatweb	Huella digital tecnológica	Opcional (tiene alternativa)
wfuzz	Fuzzing avanzado	Opcional
arjun	Descubrimiento de parámetros ocultos	Opcional
testssl	Pruebas SSL/TLS	Opcional
masscan	Escaneo rápido de puertos	Opcional
amass	OSINT / enumeración de subdominios	Opcional
dnsrecon	Enumeración DNS	Opcional (tiene alternativa)
theHarvester	OSINT de correo/dominio	Opcional
retire.js	Escaneo CVE de librerías JS	Opcional
trufflehog	Detección de secretos	Opcional
git-dumper	Exposición de repositorios Git	Opcional
commix	Inyección de comandos	Opcional
corscanner	Mala configuración CORS	Opcional (tiene alternativa)
jwt_tool	Análisis JWT	Opcional
graphql-cop	Seguridad GraphQL	Opcional
xsstrike	XSS avanzado	Opcional
hydra	Fuerza bruta	Opcional
shodan	Inteligencia de Internet	Opcional
enum4linux-ng	Enumeración SMB	Opcional

💬 Ejemplos de uso

El comando pentest ask utiliza Gemini AI para planificar y ejecutar automáticamente escaneos de seguridad basados en consultas en lenguaje natural.

Escaneo rápido de vulnerabilidades

pentest ask \
  --query "scan for SQL injection and XSS vulnerabilities" \
  --target http://localhost:3000 \
  --consent

Auditoría completa OWASP Top 10

pentest ask \
  --query "perform a comprehensive OWASP Top 10 security audit" \
  --target https://example.com \
  --consent

Solo reconocimiento

pentest ask \
  --query "enumerate subdomains and check for exposed sensitive files" \
  --target example.com \
  --consent

Ruta de informe personalizada

pentest ask \
  --query "check security headers and TLS configuration" \
  --target https://example.com \
  --consent \
  --output security-audit-2024.md

📖 Documentación completa: Consulta CLI_USAGE_GUIDE.md para obtener una guía de uso detallada, ejemplos y solución de problemas.

📁 Estructura del proyecto

pentest-ai/
├── pentest_mcp/
│   ├── scan_modes.py          # Quick/Medium/Extensive scan orchestration
│   ├── agent.py               # Standalone CLI orchestrator
│   ├── session.py             # Session state management
│   ├── models.py              # Pydantic data models
│   ├── config.py              # Environment & settings
│   ├── cli.py                 # CLI interface (includes "ask" command)
│   ├── cli_ui.py              # Beautiful CLI UI components
│   ├── tools/
│   │   ├── __init__.py        # Python-native security tools
│   │   ├── professional.py    # External tool wrappers (nmap, sqlmap, etc.)
│   │   └── tool_registry.py   # Tool execution and result processing
│   └── utils/
│       └── sanitizer.py       # Input validation & sanitization
├── tests/
│   └── test_system.py         # System tests
├── wordlists/                 # Fuzzing wordlists for ffuf/gobuster
├── reports/                   # Generated scan reports (Markdown)
├── CLI_USAGE_GUIDE.md         # Example prompts and detailed usage guide
├── pyproject.toml             # Project dependencies & metadata
├── Makefile                   # Development shortcuts
├── install_tools.sh           # Security tool installer script
└── .env.example               # Environment variable template

⚙️ Configuración

Variables de entorno

Variable	Descripción	Predeterminado
`GEMINI_API_KEY`	Tu clave de API de Gemini	Requerido
`GEMINI_MODEL`	Modelo LLM para análisis	`gemini-flash-lite-latest`
`GEMINI_MAX_TOKENS`	Tokens máximos de respuesta	`8192`
`GEMINI_TEMPERATURE`	Temperatura del LLM	`0.2`
`SESSION_DIR`	Ruta de almacenamiento de sesiones	`~/.pentest-ai/sessions`
`LOG_LEVEL`	Verbosidad del registro	`INFO`
`AGENT_MAX_TOOLS`	Herramientas máximas por ejecución de `pentest ask`	`10`

Pipeline de análisis de IA

Cada modo de escaneo utiliza prompts de Gemini AI distintos calibrados según la profundidad del escaneo:

Rápido: Triaje conciso: se centra solo en hallazgos de gravedad crítica/alta
Medio: Análisis OWASP Top 10 con evaluación de riesgos equilibrada y remediación
Extenso: Resumen ejecutivo a nivel directivo con hallazgos exhaustivos puntuados por CVSS, mapeo de cumplimiento y recomendaciones estratégicas

🔍 Solución de problemas

Error `Read-only file system`

Los informes se guardan en <project_root>/reports/. Asegúrate de que el directorio del proyecto tenga permisos de escritura.

Errores de la API de Gemini

Verifica tu clave de API: echo $GEMINI_API_KEY
Comprueba los límites de tasa en aistudio.google.com
El servidor continúa escaneando incluso si Gemini no está disponible: se devuelve la salida sin procesar de la herramienta

Herramientas no detectadas

Instala las herramientas faltantes a través de Homebrew o tu gestor de paquetes. Las alternativas de Python cubren la funcionalidad principal incluso sin herramientas externas.

⚠️ Aviso de seguridad

Esta herramienta es solo para pruebas de seguridad autorizadas.
Obtén siempre permiso explícito por escrito antes de escanear cualquier objetivo
Las pruebas no autorizadas violan la Ley de Fraude y Abuso Informático (CFAA), la Ley de TI 2000/2008 y leyes similares en todo el mundo
El parámetro consent_confirmed existe como salvaguarda ética: nunca lo omitas
Nunca subas claves de API al control de versiones

📝 Licencia

Consulta LICENSE para más detalles.

PenTest MCP Server

🏗️ Arquitectura

✨ Características

📋 Tabla de contenidos

🚀 Inicio rápido

Requisitos previos

1. Clonar e instalar

2. Configurar el entorno

3. Instalar herramientas de seguridad (opcional)

4. ¡Comienza a escanear!

🎯 Modos de escaneo

Modo rápido (5-10 minutos)

Modo medio (15-30 minutos)

Modo extenso (45+ minutos)

🔧 Herramientas compatibles

💬 Ejemplos de uso

📁 Estructura del proyecto

⚙️ Configuración

Variables de entorno

Pipeline de análisis de IA

🔍 Solución de problemas

Error `Read-only file system`

Errores de la API de Gemini

Herramientas no detectadas

⚠️ Aviso de seguridad

📝 Licencia

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

🏗️ Arquitectura

✨ Características

📋 Tabla de contenidos

🚀 Inicio rápido

Requisitos previos

1. Clonar e instalar

2. Configurar el entorno

3. Instalar herramientas de seguridad (opcional)

4. ¡Comienza a escanear!

🎯 Modos de escaneo

Modo rápido (5-10 minutos)

Modo medio (15-30 minutos)

Modo extenso (45+ minutos)

🔧 Herramientas compatibles

💬 Ejemplos de uso

📁 Estructura del proyecto

⚙️ Configuración

Variables de entorno

Pipeline de análisis de IA

🔍 Solución de problemas

Error Read-only file system

Errores de la API de Gemini

Herramientas no detectadas

⚠️ Aviso de seguridad

📝 Licencia

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

Error `Read-only file system`