Agente autónomo de pruebas de penetración impulsado por IA

AIRecon es un agente autónomo de pruebas de penetración que combina un LLM de Ollama autoalojado con un sandbox Docker de Kali Linux, integración nativa con el proxy Caido, un pipeline estructurado RECON → ANALYSIS → EXPLOIT → REPORT y una TUI Textual en tiempo real — completamente offline, sin necesidad de claves API.

¿Por qué AIRecon?

Los modelos comerciales basados en API (OpenAI GPT-4, Claude, Gemini) resultan prohibitivamente caros para flujos de trabajo de reconocimiento autónomos y recursivos que pueden requerir miles de llamadas al LLM por sesión.

AIRecon está construido 100 % para operación local y privada.

• Privacidad primero — La inteligencia sobre el objetivo, las salidas de las herramientas y los informes nunca salen de tu máquina.
• Caido nativo — 5 herramientas integradas: list, replay, automate (§FUZZ§), findings, scope.
• Stack completo — Sandbox de Kali + automatización de navegador + fuzzer personalizado + fuzzing de API con Schemathesis + SAST con Semgrep.
• Base de conocimiento de skills — 57 archivos de skills integrados, 289 asignaciones automáticas keyword → skill. Ampliada por airecon-skills — una biblioteca comunitaria de skills con 57 playbooks adicionales basados en CLI para CTF, bug bounty y pentesting.
• Base de conocimiento de seguridad local — El opcional airecon-dataset indexa ~1.09M de registros de seguridad (CVEs, técnicas de red team, writeups de CTF, plantillas de nuclei, payloads de bug bounty) en SQLite FTS5 local. El LLM llama a dataset_search de forma autónoma antes de intentar técnicas desconocidas, lo que fundamenta sus decisiones en datos reales indexados.

Pipeline

RECON → ANALYSIS → EXPLOIT → REPORT

Cada fase tiene objetivos específicos, herramientas recomendadas y criterios automáticos de transición. La aplicación de las fases es flexible — el agente es guiado pero nunca bloqueado. Los checkpoints se ejecutan cada 5 (evaluación de fase), 10 (autoevaluación) y 15 (compresión de contexto) iteraciones.

Memoria y aprendizaje (lo que realmente hace)

AIRecon no realiza fine-tuning del LLM. Su «aprendizaje» es telemetría local y estructurada que guía la elección de herramientas y evita repetir rutas fallidas.

Persistencia local (todo en disco, sin nube):

• Base de datos de memoria SQLite en ~/.airecon/memory/airecon.db que almacena sesiones, hallazgos, patrones, inteligencia del objetivo, uso de herramientas, rendimiento del modelo, uso de skills y descubrimientos de cadenas de ataque.
• Estado de aprendizaje adaptativo en ~/.airecon/learning/global_learning.json (estadísticas de rendimiento de herramientas, patrones de estrategia, registro de observaciones, insights destilados).
• Archivos de memoria por objetivo en ~/.airecon/memory/by_target/ cuando se persisten, que contienen endpoints, vulnerabilidades, bypasses de WAF, parámetros sensibles y endpoints de autenticación.
• Las instantáneas de memoria de payloads se pueden guardar en workspace/<target>/payload_memory.json cuando se ejecuta la persistencia de sesión.

Cómo afecta al comportamiento:

• Al iniciar la sesión se inyecta el contexto de memoria (inteligencia del objetivo, hallazgos similares, patrones aprendidos, fiabilidad de herramientas).
• Cada 8 iteraciones, los patrones aprendidos y los hallazgos similares pueden reinyectarse en función de la tecnología detectada.
• La clasificación adaptativa de herramientas utiliza el historial de éxitos/fallos para ordenar las herramientas y sugerir estrategias.
• La memoria de payloads (cuando está habilitada) omite los payloads que fallaron repetidamente para el mismo objetivo/parámetro.

Requisitos del modelo

AIRecon requiere un modelo con pensamiento extendido (bloques <think>) y capacidades fiables de tool calling. Las capacidades se detectan automáticamente mediante los metadatos de ollama show.

⚠️ El soporte de tool calling es OBLIGATORIO. El modelo debe soportar llamadas nativas a funciones/herramientas. Los modelos sin esta capacidad no podrán ejecutar ninguna herramienta (http_observe, execute, acciones de navegador, etc.), lo que dejaría AIRecon completamente inoperativo.

Mínimo recomendado: 8B-9B parámetros. Los modelos por debajo de 8B son técnicamente utilizables, pero muy desaconsejados — alucinan con frecuencia la salida de las herramientas, inventan CVEs, se saltan las reglas de alcance y producen llamadas a herramientas poco fiables.

Guía del tamaño del modelo:

• ≥32B: Fiable para pipelines completos de reconocimiento, buena precisión en tool calling
• 8B-14B: Utilizable para tareas sencillas, espera un 20-40 % de errores de tool calling y alucinaciones
• <8B: Técnicamente funciona, pero produce resultados poco fiables — no recomendado para pruebas serias

Problemas conocidos: DeepSeek R1 produce llamadas a funciones incompletas. Los modelos < 8B carecen de soporte fiable de tool calling.

Ejecutar Ollama en Google Colab (hardware limitado)

Si no tienes una GPU o tu VRAM local está por debajo del mínimo, puedes ejecutar Ollama en una GPU T4 gratuita de Google Colab y conectar AIRecon a ella mediante un túnel público.

Abre el notebook:

Cómo funciona:

Google Colab GPU                     Your Local Machine
┌─────────────────────────┐          ┌──────────────────────────┐
│  Ollama (qwen3.5:9b)    │◄────────►│  AIRecon TUI             │
│  cloudflared tunnel     │  HTTPS   │  ollama_url: tunnel URL  │
└─────────────────────────┘          └──────────────────────────┘

Pasos:

1. Abre el enlace de Colab indicado arriba y selecciona Runtime → Change runtime type → T4 GPU
2. Ejecuta todas las celdas de arriba a abajo (tarda ~5–10 minutos la primera vez)
3. Copia el fragmento de configuración que se imprime en la celda 6 en ~/.airecon/config.yaml:

ollama_url: "https://xxxx.trycloudflare.com"   # printed by Cell 6
ollama_model: "qwen3.5:9b"
ollama_timeout: 300.0
ollama_chunk_timeout: 300.0
ollama_num_ctx: 32768
ollama_num_ctx_small: 16384

4. Inicia AIRecon normalmente: airecon start

GPU de Colab → disponibilidad de modelos:

Limitaciones:

• Las sesiones de Colab duran como máximo 12 horas (gratuito) / 24 horas (Pro) — la URL del túnel cambia al reconectar
• T4 con qwen3.5:9b es la configuración mínima viable — espera respuestas más lentas y más errores de tool calling que con un modelo local de 35B+
• No es adecuado para sesiones autónomas largas (el reconocimiento profundo puede superar los límites de la sesión)
• El notebook de Colab se encuentra en scripts/airecon_colab.ipynb si quieres autoalojarlo o modificarlo

Instalación

Requisitos previos: Python 3.12+, Docker 20.10+, Ollama (en ejecución), git, curl

Instalación en una línea (recomendada)

curl -fsSL https://raw.githubusercontent.com/pikpikcu/airecon/refs/heads/main/scripts/install.sh | bash

El script detecta automáticamente el modo remoto frente al local, instala Poetry si no está presente (mediante el instalador oficial, sin conflictos con paquetes del sistema), compila la wheel e instala en ~/.local/bin.

Instalación manual (desde el código fuente)

git clone https://github.com/pikpikcu/airecon.git
cd airecon
./install.sh

# Add to ~/.bashrc or ~/.zshrc if needed
export PATH="$HOME/.local/bin:$PATH"

airecon --version

Configuración

Archivo de configuración: ~/.airecon/config.yaml (se genera automáticamente en la primera ejecución). AIRecon creará ~/.airecon/ si no existe, incluso cuando se utiliza una ruta ~ personalizada.

# ======================================
# Ollama Connection
# ======================================
# Ollama API endpoint. REQUIRED — must be set. For local: http://127.0.0.1:11434. For remote: http://IP:11434
ollama_url: "http://127.0.0.1:11434"
# Model to use. 122B for best reasoning (requires 60GB+ VRAM). For 12GB VRAM: use qwen2.5:7b or smaller. For 8GB VRAM: use qwen2.5:1.8b.
ollama_model: "qwen3.5:122b"
# Total request timeout (seconds). 180s = 3 min. Stable for most models. Increase to 300s for slow remote servers or 122B models.
ollama_timeout: 180.0

# ======================================
# Ollama Model Settings
# ======================================
# Context window size. 65536 = 64K (stable for 12GB VRAM with 8B models). 131072 = 128K requires 30GB+ VRAM. Set -1 for server default.
ollama_num_ctx: 65536
# Context for CTF/summary mode. 32768 = 32K (stable for 12GB VRAM). Reduced from 64K for stability with 8B+ models.
ollama_num_ctx_small: 32768
# LLM output randomness. 0.0=deterministic, 0.15=recommended (strict), 0.3=creative. Does NOT affect thinking mode — controls output diversity only.
ollama_temperature: 0.15
# Max tokens to generate. 16384 = 16K (stable for 12GB VRAM). 32K requires more VRAM.
ollama_num_predict: 16384
# Enable extended thinking mode (for Qwen3.5+/Qwen2.5+). When enabled, model generates <think> reasoning blocks before answering.
ollama_enable_thinking: true
# Thinking intensity: low|medium|high|adaptive. For 12GB VRAM: use 'low' or 'medium'. 'high' may cause OOM with 8B models. Low=only deep tools, Medium=ANALYSIS+deep tools, High=most iterations (high VRAM only).
ollama_thinking_mode: low
# Protect first N tokens from KV eviction. 4096 = 4K (reduced for 12GB VRAM stability). 8K for larger VRAM.
ollama_num_keep: 4096

# ======================================
# Proxy Server
# ======================================
# Host to bind proxy server. 127.0.0.1 = localhost only.
proxy_host: 127.0.0.1
# Port for proxy server. Default 3000.
proxy_port: 3000

# ======================================
# Timeouts
# ======================================
# Docker command timeout (seconds). 900s = 15 min for long scans (nmap, nuclei).
command_timeout: 900.0

# ======================================
# Docker Sandbox
# ======================================
# Container memory limit. '16g' = 16GB (stable for 32GB+ RAM host, 18GB image + Chromium). Prevents OOM kills. Set to '12g' for 32GB RAM, '8g' for 16GB systems, '4g' for 8GB systems.
docker_memory_limit: 16g

# ======================================
# Deep Recon
# ======================================
# Auto-start deep recon on session start.
deep_recon_autostart: true
# Recon execution mode: standard|full. standard=respect user scope, full=auto-expand simple target prompts into comprehensive recon.
agent_recon_mode: standard

# ======================================
# Safety
# ======================================
# Allow destructive tests (e.g., DELETE requests). Default: False for safety.
allow_destructive_testing: false

Ollama remoto (servidor LAN o túnel de Google Colab):

ollama_url: "http://192.168.1.100:11434"   # LAN server
ollama_model: "qwen3.5:35b"

# or via Colab tunnel (see "Running Ollama on Google Colab" section above):
ollama_url: "https://xxxx.trycloudflare.com"
ollama_model: "qwen3.5:9b"
ollama_timeout: 300.0
ollama_chunk_timeout: 300.0

Integración MCP

AIRecon puede conectarse a servidores MCP externos y exponer sus herramientas dinámicamente como herramientas mcp_<server>.

Archivo de configuración: ~/.airecon/mcp.json

Ejemplo de configuración:

{
  "mcpServers": {
    "hexstrike": {
      "command": "python3",
      "args": [
        "/path/hexstrike-ai/hexstrike_mcp.py",
        "--server",
        "http://127.0.0.1:8888"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      },
      "enabled": true
    },
    "xssgen": {
      "command": "python3",
      "args": [
        "/path/xssgen/xss_client.py",
        "--server",
        "http://127.0.0.1:8000"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      },
      "enabled": true
    },
    "recon": {
      "transport": "sse",
      "url": "https://example.com/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer xxxxx"
      }
    }
  }
}   

Uso de las herramientas MCP en el chat:

• Formato del nombre de herramienta: mcp_<server>
• Acciones: list_tools, search_tools, call_tool

Ejemplo:

{"name": "mcp_acme", "arguments": {"action": "list_tools"}}

Base de conocimiento (airecon-dataset)

airecon-dataset es un complemento opcional que descarga conjuntos de datos de seguridad de HuggingFace y los indexa localmente en bases de datos SQLite FTS5. Una vez instalado, el LLM los consulta de forma autónoma mediante la herramienta dataset_search.

Cómo funciona: dataset_search es una herramienta estándar del agente en tools.json. El LLM decide cuándo llamarla — AIRecon no la activa automáticamente. El prompt del sistema indica al agente que consulte la base de conocimiento antes de intentar técnicas desconocidas.

git clone https://github.com/pikpikcu/airecon-dataset.git
cd airecon-dataset && python install.py

Conjuntos de datos incluidos (~1.09M de registros en total, 100 % offline):

Ejemplos de consultas del agente (realizadas de forma autónoma por el LLM):

dataset_search: {"query": "log4j RCE exploitation chain"}
dataset_search: {"query": "SSRF bypass cloud metadata", "category": "bug-bounty"}
dataset_search: {"query": "nuclei template XSS detection"}
dataset_search: {"query": "CVE 2021 44228", "category": "vulnerability"}

Los resultados se limitan a 500 caracteres cada uno. Los caracteres especiales en los ID de CVE (guiones, corchetes) se sanean automáticamente.

Uso

airecon start                          # start TUI
airecon start --session <session_id>  # resume session

Ejemplos de prompts:

# Full pipeline
full recon on example.com
pentest https://api.example.com

# Specific tasks
find subdomains of example.com
scan ports on 10.0.0.1
check for XSS on https://example.com/search
test SQL injection on https://example.com/api/login parameter: username
run schemathesis on https://example.com/openapi.json

# Authenticated testing
login to https://example.com/login with [email protected] / password123 then test for IDOR
test https://app.example.com with TOTP: JBSWY3DPEHPK3PXP

# Multi-agent
spawn an XSS specialist on https://example.com/search
run parallel recon on: example.com, sub.example.com, api.example.com

# Caido
replay request #1234 with a modified Authorization header
use Caido to fuzz the username parameter in request #45 with §FUZZ§ markers

Workspace

workspace/<target>/
      ├── command/         # system-managed logs
      ├── output/          # Raw tool outputs (nmap, httpx, nuclei, subfinder, ...)
      ├── tools/           # AI-generated exploit scripts (.py, .sh)
      └── vulnerabilities/ # Verified vulnerability reports (.md)

Las sesiones se persisten en ~/.airecon/sessions/<session_id>.json — subdominios, puertos, tecnologías, URLs, vulnerabilidades (deduplicación Jaccard), tokens de autenticación y fases completadas.

Solución de problemas

OOM de Ollama / página de error HTML — Más común en sesiones largas o con modelos grandes cerca de los límites de VRAM.

sudo systemctl restart ollama

{ "ollama_num_ctx": 32768, "ollama_num_ctx_small": 16384, "ollama_num_predict": 8192 }

Bucles/estancamientos del agente — Normalmente es un fallo de razonamiento. Prueba con un modelo más grande o reduce ollama_temperature a < 0.2.

El sandbox Docker no se inicia:

docker build -t airecon-sandbox airecon/containers/kali/

Conexión rechazada con Caido — Caido debe estar en ejecución antes que AIRecon. Valor por defecto: 127.0.0.1:48080.

PATH no encontrado después de la instalación:

export PATH="$HOME/.local/bin:$PATH" && source ~/.zshrc

Historial de estrellas

Contribuciones

Las issues y las PRs son bienvenidas. Si reportas un error, incluye logs, configuración y los pasos mínimos para reproducirlo.

Uso responsable

AIRecon es solo para pruebas de seguridad autorizadas. Obtén siempre permiso explícito y cumple las leyes aplicables y el alcance del programa.

Licencia

Consulta LICENSE.