KI-gestützter autonomer Penetrationstest-Agent

AIRecon ist ein autonomer Penetrationstest-Agent, der ein selbst gehostetes Ollama-LLM mit einer Kali-Linux-Docker-Sandbox, nativer Caido-Proxy-Integration, einer strukturierten RECON → ANALYSIS → EXPLOIT → REPORT-Pipeline und einer Echtzeit-Textual-TUI kombiniert — komplett offline, keine API-Schlüssel erforderlich.

Warum AIRecon?

Kommerzielle API-basierte Modelle (OpenAI GPT-4, Claude, Gemini) werden für rekursive, autonome Recon-Workflows, die pro Sitzung Tausende von LLM-Aufrufen erfordern können, unerschwinglich teuer.

AIRecon ist zu 100 % für den lokalen, privaten Betrieb konzipiert.

• Datenschutz zuerst — Zielinformationen, Tool-Ausgaben und Berichte verlassen niemals deinen Rechner.
• Caido-nativ — 5 integrierte Tools: list, replay, automate (§FUZZ§), findings, scope.
• Kompletter Stack — Kali-Sandbox + Browser-Automatisierung + eigener Fuzzer + Schemathesis-API-Fuzzing + Semgrep-SAST.
• Skills-Wissensdatenbank — 57 integrierte Skill-Dateien, 289 automatische Keyword→Skill-Zuordnungen. Erweiterbar durch airecon-skills — eine Community-Skill-Bibliothek mit 57 zusätzlichen CLI-basierten Playbooks für CTF, Bug Bounty und Pentesting.
• Lokale Sicherheits-Wissensdatenbank — Das optionale airecon-dataset indiziert ~1,09 Mio. Sicherheitsdatensätze (CVEs, Red-Team-Techniken, CTF-Writeups, Nuclei-Templates, Bug-Bounty-Payloads) in lokale SQLite-FTS5-Datenbanken. Das LLM ruft dataset_search autonom auf, bevor es unbekannte Techniken ausprobiert — und verankert seine Entscheidungen so in realen indizierten Daten.

Pipeline

RECON → ANALYSIS → EXPLOIT → REPORT

Jede Phase hat spezifische Ziele, empfohlene Tools und automatische Übergangskriterien. Die Durchsetzung der Phasen ist soft — der Agent wird geleitet, aber niemals blockiert. Checkpoints laufen alle 5 (Phasenbewertung), 10 (Selbstbewertung) und 15 (Kontextkomprimierung) Iterationen.

Speicher & Lernen (Was es tatsächlich tut)

AIRecon nimmt kein Fine-Tuning des LLM vor. Sein „Lernen“ ist eine lokale, strukturierte Telemetrie, die die Tool-Auswahl leitet und das Wiederholen fehlgeschlagener Wege vermeidet.

Lokale Persistenz (alles auf der Festplatte, keine Cloud):

• SQLite-Speicherdatenbank unter ~/.airecon/memory/airecon.db, die Sitzungen, Erkenntnisse, Muster, Zielinformationen, Tool-Nutzung, Modellleistung, Skill-Nutzung und entdeckte Angriffsketten speichert.
• Adaptiver Lernzustand unter ~/.airecon/learning/global_learning.json (Tool-Leistungsstatistiken, Strategiemuster, Beobachtungsprotokoll, destillierte Erkenntnisse).
• Pro Ziel separate Speicherdateien unter ~/.airecon/memory/by_target/, sofern persistiert, mit Endpunkten, Schwachstellen, WAF-Bypasses, sensiblen Parametern und Auth-Endpunkten.
• Payload-Speicher-Snapshots können bei laufender Sitzungspersistenz unter workspace/<target>/payload_memory.json gespeichert werden.

Wie es das Verhalten beeinflusst:

• Beim Sitzungsstart wird Speicherkontext injiziert (Zielinformationen, ähnliche Erkenntnisse, gelernte Muster, Tool-Zuverlässigkeit).
• Alle 8 Iterationen können gelernte Muster und ähnliche Erkenntnisse basierend auf der erkannten Technologie erneut injiziert werden.
• Adaptives Tool-Ranking nutzt historische Erfolge/Fehlschläge, um Tools zu ordnen und Strategien vorzuschlagen.
• Der Payload-Speicher (sofern aktiviert) überspringt Payloads, die für dasselbe Ziel/denselben Parameter wiederholt fehlgeschlagen sind.

Modellanforderungen

AIRecon erfordert ein Modell mit erweitertem Denken (<think>-Blöcke) und zuverlässigen Tool-Calling-Fähigkeiten. Die Fähigkeiten werden automatisch über die ollama show-Metadaten erkannt.

⚠️ Tool-Calling-Unterstützung ist ERFORDERLICH. Das Modell muss natives Funktions-/Tool-Calling unterstützen. Modelle ohne diese Fähigkeit können keine Tools ausführen (http_observe, execute, Browser-Aktionen usw.), was AIRecon völlig funktionsunfähig macht.

Empfohlenes Minimum: 8B-9B Parameter. Modelle unter 8B sind technisch nutzbar, aber stark abgeraten — sie halluzinieren häufig Tool-Ausgaben, erfinden CVEs, ignorieren Scope-Regeln und erzeugen unzuverlässige Tool-Aufrufe.

Orientierung zur Modellgröße:

• ≥32B: Zuverlässig für vollständige Recon-Pipelines, gute Tool-Calling-Genauigkeit
• 8B-14B: Für einfache Aufgaben nutzbar, mit 20–40 % Tool-Call-Fehlern und Halluzinationen rechnen
• <8B: Funktioniert technisch, erzeugt aber unzuverlässige Ergebnisse — für ernsthafte Tests nicht empfohlen

Bekannte Probleme: DeepSeek R1 erzeugt unvollständige Funktionsaufrufe. Modelle < 8B haben keine zuverlässige Tool-Calling-Unterstützung.

Ollama auf Google Colab ausführen (Begrenzte Hardware)

Wenn du keine GPU hast oder dein lokaler VRAM unter dem Minimum liegt, kannst du Ollama auf einer kostenlosen Google-Colab-T4-GPU ausführen und AIRecon über einen öffentlichen Tunnel damit verbinden.

Notebook öffnen:

So funktioniert es:

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

Schritte:

1. Öffne den Colab-Link oben und wähle Laufzeit → Laufzeittyp ändern → T4 GPU
2. Führe alle Zellen von oben nach unten aus (dauert beim ersten Mal ~5–10 Minuten)
3. Kopiere den in Zelle 6 ausgegebenen Konfigurationsausschnitt 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. Starte AIRecon normal: airecon start

Colab-GPU → Modellverfügbarkeit:

Einschränkungen:

• Colab-Sitzungen dauern maximal 12 Stunden (kostenlos) / 24 Stunden (Pro) — die Tunnel-URL ändert sich bei erneuter Verbindung
• T4 mit qwen3.5:9b ist das Minimum, das funktioniert — rechne mit langsameren Antworten und mehr Tool-Call-Fehlern als bei einem lokalen 35B+-Modell
• Nicht für lange autonome Sitzungen geeignet (Deep Recon kann die Sitzungslimits überschreiten)
• Das Colab-Notebook befindet sich unter scripts/airecon_colab.ipynb, falls du es selbst hosten oder modifizieren möchtest

Installation

Voraussetzungen: Python 3.12+, Docker 20.10+, Ollama (läuft), git, curl

Einzeilige Installation (empfohlen)

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

Das Skript erkennt automatisch, ob Remote- oder lokaler Modus vorliegt, installiert Poetry, falls es fehlt (über den offiziellen Installer — keine Systempaket-Konflikte), baut das Wheel und installiert nach ~/.local/bin.

Manuelle Installation (aus dem Quellcode)

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

Konfiguration

Konfigurationsdatei: ~/.airecon/config.yaml (wird beim ersten Start automatisch erzeugt). AIRecon erstellt ~/.airecon/, falls es nicht existiert — auch wenn ein benutzerdefinierter ~-Pfad verwendet wird.

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

Remote-Ollama (LAN-Server oder Google-Colab-Tunnel):

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

MCP-Integration

AIRecon kann sich mit externen MCP-Servern verbinden und deren Tools dynamisch als mcp_<server>-Tools bereitstellen.

Konfigurationsdatei: ~/.airecon/mcp.json

Beispielkonfiguration:

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

MCP-Tools im Chat verwenden:

• Tool-Name-Format: mcp_<server>
• Aktionen: list_tools, search_tools, call_tool

Beispiel:

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

Wissensdatenbank (airecon-dataset)

airecon-dataset ist ein optionaler Begleiter, der Sicherheitsdatensätze von HuggingFace herunterlädt und sie lokal in SQLite-FTS5-Datenbanken indiziert. Nach der Installation fragt das LLM sie autonom über das dataset_search-Tool ab.

So funktioniert es: dataset_search ist ein Standard-Agent-Tool in tools.json. Das LLM entscheidet selbst, wann es aufgerufen wird — AIRecon löst es nicht automatisch aus. Der System-Prompt weist den Agenten an, die Wissensdatenbank abzufragen, bevor er unbekannte Techniken ausprobiert.

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

Enthaltene Datensätze (~1,09 Mio. Einträge insgesamt, 100 % offline):

Beispiel-Agent-Abfragen (autonom vom LLM aufgerufen):

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

Ergebnisse sind jeweils auf 500 Zeichen begrenzt. Sonderzeichen in CVE-IDs (Bindestriche, Klammern) werden automatisch bereinigt.

Verwendung

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

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

Sitzungen werden unter ~/.airecon/sessions/<session_id>.json gespeichert — Subdomains, Ports, Technologien, URLs, Schwachstellen (Jaccard-Deduplizierung), Auth-Tokens und abgeschlossene Phasen.

Fehlerbehebung

Ollama OOM / HTML-Fehlerseite — Am häufigsten bei langen Sitzungen oder großen Modellen nahe der VRAM-Grenzen.

sudo systemctl restart ollama

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

Agent schleift/hängt — Meist ein Reasoning-Fehler. Versuche ein größeres Modell oder reduziere ollama_temperature auf < 0.2.

Docker-Sandbox startet nicht:

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

Caido-Verbindung abgelehnt — Caido muss vor AIRecon gestartet werden. Standard: 127.0.0.1:48080.

PATH nach der Installation nicht gefunden:

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

Stern-Historie

Mitwirken

Issues und Pull-Requests sind willkommen. Wenn du einen Fehler meldest, füge Protokolle, Konfiguration und minimale Schritte zur Reproduktion bei.

Verantwortungsvolle Nutzung

AIRecon ist ausschließlich für autorisierte Sicherheitstests gedacht. Hol immer eine ausdrückliche Genehmigung ein und befolge die geltenden Gesetze sowie den Scope des Programms.

Lizenz

Siehe LICENSE.