Agente Autonomo di Penetration Testing basato su IA

AIRecon è un agente autonomo di penetration testing che combina un LLM Ollama self-hosted con una sandbox Docker Kali Linux, l'integrazione nativa del proxy Caido, una pipeline strutturata RECON → ANALYSIS → EXPLOIT → REPORT e una TUI Textual in tempo reale — completamente offline, senza bisogno di chiavi API.

Perché AIRecon?

I modelli commerciali basati su API (OpenAI GPT-4, Claude, Gemini) diventano proibitivamente costosi per flussi di lavoro di ricognizione autonomi e ricorsivi che possono richiedere migliaia di chiamate LLM per sessione.

AIRecon è costruito al 100% per un funzionamento locale e privato.

• Privacy First — Le informazioni sul target, l'output degli strumenti e i report non lasciano mai la tua macchina.
• Caido nativo — 5 strumenti integrati: list, replay, automate (§FUZZ§), findings, scope.
• Full Stack — Sandbox Kali + automazione browser + fuzzer personalizzato + fuzzing API Schemathesis + Semgrep SAST.
• Knowledge Base delle Skill — 57 file di skill integrati, 289 mappature automatiche parola chiave → skill. Estesa da airecon-skills — una libreria di skill della community con 57 playbook aggiuntivi basati su CLI per CTF, bug bounty e pentesting.
• Knowledge Base di Sicurezza Locale — Il componente opzionale airecon-dataset indicizza ~1,09M di record di sicurezza (CVE, tecniche red team, writeup CTF, template nuclei, payload bug bounty) in SQLite FTS5 locale. L'LLM chiama dataset_search in autonomia prima di tentare tecniche sconosciute — basando le sue decisioni su dati reali indicizzati.

Pipeline

RECON → ANALYSIS → EXPLOIT → REPORT

Ogni fase ha obiettivi specifici, strumenti consigliati e criteri di transizione automatica. L'applicazione delle fasi è soft — l'agente viene guidato ma mai bloccato. I checkpoint vengono eseguiti ogni 5 (valutazione fase), 10 (auto-valutazione) e 15 (compressione del contesto) iterazioni.

Memoria e Apprendimento (Cosa Fa Davvero)

AIRecon non esegue il fine-tuning dell'LLM. Il suo "apprendimento" è una telemetria strutturata e locale che guida la scelta degli strumenti ed evita di ripetere percorsi falliti.

Persistenza locale (tutto su disco, niente cloud):

• Database di memoria SQLite in ~/.airecon/memory/airecon.db che memorizza sessioni, risultati, pattern, intelligence sul target, utilizzo degli strumenti, prestazioni del modello, utilizzo delle skill e scoperte di catene d'attacco.
• Stato di apprendimento adattivo in ~/.airecon/learning/global_learning.json (statistiche sulle prestazioni degli strumenti, pattern strategici, registro delle osservazioni, intuizioni distillate).
• File di memoria per target in ~/.airecon/memory/by_target/ quando la persistenza è attiva, contenenti endpoint, vulnerabilità, bypass WAF, parametri sensibili ed endpoint di autenticazione.
• Snapshot della memoria dei payload possono essere salvati in workspace/<target>/payload_memory.json quando viene eseguita la persistenza della sessione.

Come influisce sul comportamento:

• All'avvio della sessione, il contesto di memoria viene iniettato (intelligence sul target, risultati simili, pattern appresi, affidabilità degli strumenti).
• Ogni 8 iterazioni, i pattern appresi e i risultati simili possono essere re-iniettati in base alla tecnologia rilevata.
• La classifica adattiva degli strumenti usa i successi/fallimenti storici per ordinare gli strumenti e suggerire strategie.
• La memoria dei payload (se abilitata) salta i payload che hanno fallito ripetutamente per lo stesso target/parametro.

Requisiti del Modello

AIRecon richiede un modello con ragionamento esteso (blocchi <think>) e capacità di tool-calling affidabile. Le capacità vengono rilevate automaticamente tramite i metadati di ollama show.

⚠️ Il supporto al tool calling è OBBLIGATORIO. Il modello deve supportare il function/tool calling nativo. I modelli senza questa capacità non saranno in grado di eseguire alcuno strumento (http_observe, execute, azioni del browser, ecc.), rendendo AIRecon completamente non funzionante.

Minimo consigliato: 8B-9B parametri. I modelli sotto gli 8B sono tecnicamente utilizzabili ma fortemente sconsigliati — spesso allucinano l'output degli strumenti, inventano CVE, ignorano le regole di scope e producono tool call inaffidabili.

Guida alla dimensione del modello:

• ≥32B: Affidabile per pipeline di ricognizione complete, buona precisione nel tool calling
• 8B-14B: Utilizzabile per attività semplici, aspettati errori di tool call e allucinazioni nel 20-40% dei casi
• <8B: Tecnicamente funziona ma produce risultati inaffidabili — non consigliato per test seri

Problemi noti: DeepSeek R1 produce chiamate di funzione incomplete. I modelli < 8B non dispongono di un supporto affidabile al tool calling.

Eseguire Ollama su Google Colab (Hardware Limitato)

Se non hai una GPU o la tua VRAM locale è al di sotto del minimo, puoi eseguire Ollama su una GPU T4 gratuita di Google Colab e collegare AIRecon ad essa tramite un tunnel pubblico.

Apri il notebook:

Come funziona:

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

Passaggi:

1. Apri il link di Colab qui sopra e seleziona Runtime → Change runtime type → T4 GPU
2. Esegui tutte le celle dall'alto verso il basso (la prima volta richiede ~5–10 minuti)
3. Copia lo snippet di configurazione stampato nella Cella 6 in ~/.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. Avvia AIRecon normalmente: airecon start

GPU Colab → disponibilità del modello:

Limitazioni:

• Le sessioni Colab durano al massimo 12 ore (gratuito) / 24 ore (Pro) — l'URL del tunnel cambia alla riconnessione
• T4 con qwen3.5:9b è la configurazione minima utilizzabile — aspettati risposte più lente e più errori di tool call rispetto a un modello locale 35B+
• Non adatto a sessioni autonome lunghe (la ricognizione profonda può superare i limiti di sessione)
• Il notebook Colab si trova in scripts/airecon_colab.ipynb se vuoi gestirlo in autonomia o modificarlo

Installazione

Prerequisiti: Python 3.12+, Docker 20.10+, Ollama (in esecuzione), git, curl

Installazione con una riga di comando (consigliata)

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

Lo script rileva automaticamente la modalità remota o locale, installa Poetry se mancante (tramite l'installer ufficiale — nessun conflitto con i pacchetti di sistema), compila la wheel e installa in ~/.local/bin.

Installazione manuale (da sorgente)

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

Configurazione

File di configurazione: ~/.airecon/config.yaml (generato automaticamente al primo avvio). AIRecon creerà ~/.airecon/ se non esiste, anche quando viene utilizzato un percorso ~ personalizzato.

# ======================================
# 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 (server LAN o tunnel 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

Integrazione MCP

AIRecon può connettersi a server MCP esterni ed esporre i loro strumenti dinamicamente come strumenti mcp_<server>.

File di configurazione: ~/.airecon/mcp.json

Configurazione di esempio:

{
  "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"
      }
    }
  }
}   

Usare gli strumenti MCP nella chat:

• Formato del nome dello strumento: mcp_<server>
• Azioni: list_tools, search_tools, call_tool

Esempio:

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

Knowledge Base (airecon-dataset)

airecon-dataset è un componente opzionale che scarica dataset di sicurezza da HuggingFace e li indicizza localmente in database SQLite FTS5. Una volta installato, l'LLM li interroga autonomamente tramite lo strumento dataset_search.

Come funziona: dataset_search è uno strumento standard dell'agente in tools.json. L'LLM decide quando chiamarlo — AIRecon non lo attiva automaticamente. Il system prompt istruisce l'agente a interrogare la knowledge base prima di tentare tecniche sconosciute.

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

Dataset inclusi (~1,09M di record in totale, 100% offline):

Esempi di query dell'agente (chiamate autonomamente dall'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"}

I risultati sono limitati a 500 caratteri ciascuno. I caratteri speciali negli ID CVE (trattini, parentesi) vengono sanitizzati automaticamente.

Utilizzo

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

Esempi di prompt:

# 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)

Le sessioni vengono salvate in ~/.airecon/sessions/<session_id>.json — sottodomini, porte, tecnologie, URL, vulnerabilità (deduplicazione Jaccard), token di autenticazione e fasi completate.

Risoluzione dei problemi

OOM di Ollama / pagina di errore HTML — Più comune nelle sessioni lunghe o con modelli di grandi dimensioni vicini ai limiti di VRAM.

sudo systemctl restart ollama

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

Loop/blocchi dell'agente — Di solito un errore di ragionamento. Prova un modello più grande o riduci ollama_temperature a < 0.2.

La sandbox Docker non si avvia:

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

Connessione a Caido rifiutata — Caido deve essere in esecuzione prima di AIRecon. Predefinito: 127.0.0.1:48080.

PATH non trovato dopo l'installazione:

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

Cronologia delle stelle

Contributi

Issue e PR sono benvenuti. Se segnali un bug, includi log, configurazione e i passaggi minimi per riprodurlo.

Uso Responsabile

AIRecon è destinato esclusivamente a test di sicurezza autorizzati. Ottieni sempre il permesso esplicito e rispetta le leggi applicabili e lo scope del programma.

Licenza

Vedi LICENSE.