AIRecon : agent autonome de pentest avec Ollama et un bac à sable Kali (zéro API key)

Extrait :

AIRecon est un agent de test d’intrusion autonome, entièrement local
et sans clé API : il combine un LLM hébergé via Ollama (avec extended
thinking et tool calling), un bac à sable Kali Linux sous Docker et une
interface TUI Textual. Il enchaîne un pipeline structuré RECON →
ANALYSIS → EXPLOIT → REPORT, s’intègre nativement à Caido, gère le
fuzzing, l’authentification navigateur (TOTP, CAPTCHA, OAuth) et peut
s’appuyer sur une base de connaissances locale de ~1,09 million
d’enregistrements. Cet article détaille son fonctionnement, son
installation, sa configuration et ses points forts pour le bug bounty et
le pentest.

TL;DR

• AIRecon est un agent de pentest autonome et
  100 % local : aucun appel à OpenAI/Claude/Gemini, aucune clé
  API, aucune donnée envoyée dans le cloud.
• Il associe un LLM auto-hébergé via Ollama (modèles
  Qwen3.5 de 9B à 122B recommandés) à un bac à sable Kali Linux
  sous Docker dans lequel tous les outils (nmap, nuclei, sqlmap,
  ffuf, katana…) s’exécutent.
• Son cœur est un pipeline en 4 phases
  RECON → ANALYSIS → EXPLOIT → REPORT, avec des checkpoints
  automatiques (évaluation de phase, auto-évaluation, compression du
  contexte).
• Il embarque l’intégration native de Caido (replay,
  fuzzing §FUZZ§, findings), un moteur de fuzzing intégré, un
  fuzzing API via Schemathesis, une base de connaissances
  locale (airecon-dataset) et le support des serveurs
  MCP.
• L’installation se fait en une ligne (curl … | bash) ou
  via ./install.sh, avec un prérequis : un modèle
  Ollama avec tool calling fiable (≥ 8B).

AIRecon, c’est quoi exactement
?

Le README du dépôt
décrit AIRecon comme un AI-Powered Autonomous Penetration Testing
Agent :

AIRecon is an autonomous penetration testing agent that combines a
self-hosted Ollama LLM with a Kali Linux Docker
sandbox, native Caido proxy integration, a
structured RECON → ANALYSIS → EXPLOIT → REPORT
pipeline, and a real-time Textual TUI —
completely offline, no API keys required.

Autrement dit, au lieu de « demander » à un LLM cloud de raisonner
sur une capture d’écran, AIRecon orchestre lui-même des outils de
sécurité réels. Le LLM local décide des commandes, les exécute dans un
conteneur Kali isolé, observe les résultats, enchaîne les attaques et
produit un rapport de vulnérabilité vérifié — le tout sans que
les données de la cible quittent la machine.

Quelques chiffres factuels issus du dépôt (README et
docs/features.md) :

• ~850 étoiles / 141 forks au moment de la rédaction ;
• 57 fichiers de skills intégrés, 289
  mappings mot-clé → skill automatiques, extensibles par la
  librairie communautaire airecon-skills
  ;
• base de connaissances locale optionnelle de ~1,09 M
  d’enregistrements (13 jeux de données, SQLite FTS5) via airecon-dataset
  ;
• 1 608 tests unitaires au changelog
  v0.1.7-beta.

Le vrai problème qu’AIRecon
résout

La raison d’être du projet est simple et bien explicitée dans le
README (section Why AIRecon?) : les modèles API commerciaux
(OpenAI GPT-4, Claude, Gemini) deviennent prohibitifs en
coût pour des workflows de recon récursifs qui peuvent
nécessiter des milliers d’appels LLM par session.

En plus du coût, se posent des questions de
confidentialité : en envoyant la cible, les sorties
d’outils et les rapports vers un LLM cloud, on expose potentiellement
des données sensibles d’un client de pentest. AIRecon choisit donc une
approche radicalement opposée :

Comment ça marche :
l’architecture

Le dépôt présente une architecture en quatre briques principales.
C’est le modèle mental minimal à retenir :

                    ┌─────────────────────────────────────┐
   Utilisateur      │           AIRecon (TUI Textual)     │
      │             │                                     │
      ▼             │   Agent loop  ──►  tool selection   │
  Prompt en langage │        │                            │
  naturel           │        ▼                            │
                    │   ┌──────────────┐   ┌───────────┐  │
                    │   │ execute tool │──►│ Ollama LLM│  │
                    │   └──────┬───────┘   │  (local)  │  │
                    │          │           └───────────┘  │
                    └──────────┼──────────────────────────┘
                               ▼
                    ┌──────────────────────┐
                    │ Kali Docker sandbox  │  nmap, nuclei, sqlmap,
                    │  (airecon-sandbox)   │  ffuf, katana, subfinder…
                    └──────────┬───────────┘
                               ▼
                    Caido proxy  ·  navigateur Playwright  ·  fuzzer

1. Le LLM local (Ollama)

Toutes les décisions de l’agent passent par un LLM
auto-hébergé via Ollama, endpoint par défaut
http://127.0.0.1:11434. Le README insiste sur deux
prérequis de modèle :

• extended thinking (blocs
  <think>) ;
• native tool/function calling — indispensable : «
  Models without this capability will be unable to execute any tools
  ».

Tableau des modèles recommandés (README, section Model
Requirements) :

⚠️ Le README avertit : les modèles < 8B produisent des résultats
peu fiables (hallucinations d’outils, CVE inventées, non-respect du
scope). DeepSeek R1 est signalé comme produisant des appels de fonction
incomplets.

2. Le bac à sable Kali Linux
(Docker)

Toutes les commandes shell passent par l’outil execute,
qui fait un
docker exec airecon-sandbox bash -c "<command>".
L’image airecon-sandbox (décrite dans
docs/features.md et docs/installation.md)
embarque plusieurs dizaines d’outils :

• Recon sous-domaines : subfinder,
  amass, assetfinder, dnsx,
  shuffledns, massdns,
  sublist3r…
• Scan de ports : nmap,
  naabu, masscan, netcat
• Crawling web : katana,
  gospider, gau, waybackurls,
  httpx, meg, waymore
• Fingerprinting : whatweb,
  wafw00f, wappalyzer, tlsx,
  wpscan, joomscan
• Fuzzing : ffuf,
  feroxbuster, dirsearch, arjun,
  x8, dalfox, wfuzz
• Scan de vulnérabilités : nuclei,
  nikto, wapiti, sqlmap,
  ghauri, semgrep, trivy
• Secrets / mots de passe : gitleaks,
  trufflehog, hydra, hashcat,
  john
• Wordlists : SecLists complet dans
  /usr/share/seclists/, FuzzDB, rockyou

Le conteneur tourne avec l’utilisateur pentester (sudo
sans mot de passe) et une limite mémoire définie par
docker_memory_limit (16g par défaut).

3. Le pipeline
RECON → ANALYSIS → EXPLOIT → REPORT

C’est un state machine à 4 phases, dont la
transition est déclenchée par des résultats réels
d’outils (et non par un simple compteur d’itérations). La doc
features.md détaille les objectifs et outils typiques de
chaque phase :

• RECON : énumérer la surface d’attaque (subfinder,
  httpx, nmap, katana, ffuf, web_search, browser_action) ;
• ANALYSIS : identifier points d’injection, mauvaises
  configs, stack technique (semgrep, browser_action, read_file) ;
• EXPLOIT : tester et confirmer les vulnérabilités
  (quick_fuzz, advanced_fuzz, schemathesis_fuzz, caido_*, spawn_agent,
  create_vulnerability_report) ;
• REPORT : documenter les findings confirmés
  (create_vulnerability_report, create_file).

La contrainte de phase est souple : l’agent est
guidé mais jamais bloqué. Des checkpoints automatiques tournent toutes
les 5 (évaluation de phase), 10
(auto-évaluation) et 15 (compression de contexte)
itérations.

4. L’interface TUI (Textual)

airecon start lance une interface terminal
Textual avec écran d’accueil, panneau de statut,
historique, et autocomplétion des commandes slash (/) —
décrite dans le changelog v0.1.7 (Rich markup, couleurs teal
#00d4aa, suivi des tokens cumulés, panneau vulns).

Notions et concepts à
connaître

• Tool calling : capacité du LLM à déclencher des
  fonctions (ici execute, browser_action,
  quick_fuzz…). C’est le prérequis n°1 d’AIRecon.
• Extended thinking : le modèle raisonne dans des
  blocs <think> avant de répondre. AIRecon garde ce
  flux séparé du résultat final (auditabilité dans la TUI).
• Corrélation / anti-hallucination : l’agent valide
  que chaque outil existe, vérifie ses arguments, exige des preuves
  (paires HTTP request/response, script PoC, vecteur CVSS) et détecte des
  patterns d’hallucination dans ses propres réponses
  (i have found, the scan shows…).
• Confidence scoring : chaque finding est noté 0→1 ;
  ≥ 0,65 = confirmé, 0,4–0,65 = probable, < 0,4 = spéculatif (revue
  manuelle).
• Jaccard dedup : les vulnérabilités sont
  dédupliquées par similarité Jaccard (seuil 0,7 par défaut) sur titre +
  endpoint + description.
• Skills : fichiers Markdown chargés à la demande
  dans le contexte (pas de bloat du system prompt). 57 skills intégrés,
  extensibles.

Installation et premier
setup

Le guide d’installation complet est dans docs/installation.md.
Les prérequis : Python 3.12+, Docker 20.10+, Ollama en cours
d’exécution, git, curl, ~40 Go d’espace libre.

Installation en
une ligne (méthode recommandée)

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

Le script détecte le mode local/remote, installe Poetry si absent,
build le wheel et installe le binaire dans
~/.local/bin.

Installation manuelle

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

# Ajouter ~/.local/bin au PATH si nécessaire
export PATH="$HOME/.local/bin:$PATH"
airecon --version

Préparer Ollama et le
sandbox

# 1. Modèle (ajustez selon votre VRAM)
ollama pull qwen3.5:9b        # ou 35b / 122b
ollama list

# 2. Image Kali sandbox (5-15 min au premier build)
docker build -t airecon-sandbox airecon/containers/

Première exécution

cd ~/pentest-projects/
airecon start

Au premier run : création de ~/.airecon/config.yaml, du
dossier workspace/, et démarrage du conteneur sandbox.
Pensez à régler ollama_model dans la
config pour qu’il corresponde exactement au modèle téléchargé
(ollama list).

Vérification

airecon --version
docker images | grep airecon-sandbox
cat ~/.airecon/config.yaml 2>/dev/null || echo "sera créé au premier run"

Configuration clé
(~/.airecon/config.yaml)

Le README et docs/configuration.md
documentent les options. Les plus importantes :

# Connexion Ollama
ollama_url: "http://127.0.0.1:11434"     # local ou IP d'un serveur distant
ollama_model: "qwen3.5:35b"              # doit matcher ollama list

# Réglages modèle
ollama_num_ctx: 65536                     # fenêtre de contexte (32768 si VRAM limitée)
ollama_num_ctx_small: 32768
ollama_temperature: 0.15                  # garder 0.1-0.2, sinon hallucinations
ollama_num_predict: 16384
ollama_enable_thinking: true              # extended thinking
ollama_thinking_mode: low                 # low|medium|high|adaptive

# Sandbox
docker_memory_limit: 16g                  # adapter à la RAM (8g/12g/4g)

# Sécurité
allow_destructive_testing: false          # bloque DELETE etc. par défaut
command_timeout: 900.0
deep_recon_autostart: true                # un domaine nu s'étend en recon complète

Config
« safe » pour 16–20 Go de VRAM (recommandée dans la doc
troubleshooting)

ollama_model: "qwen3.5:35b"
ollama_num_ctx: 32768
ollama_num_ctx_small: 16384
ollama_num_predict: 8192
ollama_keep_alive: "10m"

Ollama distant (GPU server /
Colab)

ollama_url: "http://<server-ip>:11434"
ollama_model: "qwen3.5:35b"

Le README détaille aussi le mode Google Colab
(notebook scripts/airecon_colab.ipynb) pour les machines
sans GPU : tunnel cloudflared + T4 gratuit (qwen3.5:9b), avec les
limites associées (session 12 h max, tunnel recréé à chaque
reconnexion).

Usage : exemples de prompts

Depuis la TUI, tout se pilote en langage naturel (exemples du README)
:

# Pipeline complet
full recon on example.com
pentest https://api.example.com

# Tâches spécifiques (scope restreint)
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

# Tests authentifiés
login to https://example.com/login with admin@example.com / password123 then test for IDOR
test https://app.example.com with TOTP: JBSWY3DPEHPK3PXP

# Multi-agents
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

Gestion de session

airecon start                          # nouvelle session
airecon start --session <session_id>   # reprendre une session

Toutes les données vivent dans
~/.airecon/sessions/<session_id>.json (sous-domaines,
ports, technologies, URLs, vulnérabilités, tokens d’auth) et dans le
dossier workspace/<target>/ (outputs, scripts
générés, rapports).

Fonctionnalités phares

Intégration Caido native

AIRecon se connecte à Caido sur
127.0.0.1:48080/graphql avec gestion auto des tokens. Cinq
outils intégrés : caido_list_requests (filtres HTTPQL),
caido_send_request (replay), caido_automate
(fuzzing style Intruder avec marqueurs §FUZZ§),
caido_get_findings, caido_intercept.

Exemple de filtre HTTPQL :

method:POST AND path:/api
status:500

Moteur de fuzzing intégré

Outre ffuf/wfuzz, AIRecon possède son propre moteur :
quick_fuzz (10-50 payloads), advanced_fuzz
(sélection heuristique), deep_fuzz (exhaustif + chaînes
d’exploitation) et generate_wordlist. Les catégories de
payloads couvrent SQLi (1000+), XSS (800+), SSRF (500+), SSTI (300+),
path traversal (400+) et command injection (600+).

Fuzzing API (Schemathesis)

Quand une cible expose /openapi.json,
/swagger.json, /api/docs…, AIRecon lance un
fuzzing property-based de chaque endpoint : erreurs
HTTP 500, échecs de validation de schéma, auth manquante, bypass
d’autorisation, content-type confusion.

Authentification navigateur

browser_action gère le login par
formulaire, le TOTP/2FA (générateur RFC 6238 à
partir du secret Base32), les flux OAuth, l’injection
de cookies et la persistance d’état (save_auth_state). Les
CAPTCHA (reCAPTCHA/hCaptcha) sont détectés et
déclenchent une demande d’entrée interactive à l’utilisateur.

Base de
connaissances locale (airecon-dataset)

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

L’agent interroge cette base via l’outil dataset_search
avant d’essayer une technique inconnue (le system
prompt l’y incite). ~1,09 M de records : workflows d’exploitation CVE,
données CTF, SQLi Q&A, templates nuclei, red team offensive, privesc
APT… Chaque résultat est tronqué à 500 caractères pour préserver le
budget de contexte.

MCP

AIRecon peut se brancher à des serveurs MCP externes
(/mcp add http://localhost:3001 auth:apikey:token name) et
exposer leurs outils à l’agent sous la forme
mcp_<server> (list_tools,
search_tools, call_tool). Exemples documentés
: hexstrike, xssgen, context7.

Multi-agents

• spawn_agent : spécialiste mono-domaine (sqli, xss,
  ssrf, lfi, recon, exploit, analyzer, reporter), exécuté en parallèle du
  loop principal ;
• run_parallel_agents : plusieurs agents simultanés sur
  des cibles différentes (bornés par un sémaphore) ;
• AgentGraph (DAG) : pipeline multi-agents séquentiel
  type Recon → Analyzer → Exploiter → Reporter.

Rapports vérifiés

create_vulnerability_report exige des preuves (code PoC
> 50 caractères avec URL réelle, mention du code HTTP, analyse
technique > 80 caractères, vecteur CVSS 3.1 valide). Les rapports
prétendant des findings sans preuve sont rejetés
([VALIDATION ERROR] … missing evidence).

Anti-context-loss
: comment le projet gère les longues sessions

Le changelog v0.1.7 et features.md décrivent une gestion
très poussée du contexte, source principale des échecs des agents sur de
longues sessions :

• récupération VRAM multi-niveaux : 4 paliers de
  réduction de num_ctx (÷1, ÷2, ÷4, 4096) après crash Ollama
  ;
• monitoring proactif : troncature à ≥80 % de tokens,
  agressive à ≥90 % ;
• compression dynamique (intervalles 5/10/15 selon la
  pleineur du contexte) ;
• strip des traces <think> dans
  tous les messages sauf le dernier (récupère 50-200K tokens) ;
• mémoire des endpoints testés (LRU 500) réinjectée
  après troncature ;
• session auto-sauvée après chaque récupération de
  crash.

Quand l’utiliser, quand
ne pas l’utiliser

Quand l’utiliser :

• bug bounty / recon sur une surface étendue nécessitant des milliers
  de décisions ;
• environnements sensibles où les données ne doivent pas quitter la
  machine ;
• absence de budget LLM cloud ou volonté de rester hors-ligne ;
• tests répétables avec reprise de session.

Quand ne pas l’utiliser :

• pas de GPU / VRAM < 8 Go (modèles < 8B = résultats peu
  fiables, cf. README) ;
• sans Docker ou sans volonté de gérer un bac à sable Kali de ~40 Go
  ;
• si vous avez besoin de la garantie d’un outil stable hors beta (le
  projet est en v0.1.7-beta, cf. CHANGELOG) ;
• uniquement des tests légitimes : le projet est destiné au
  test d’intrusion autorisé uniquement (section Responsible
  Use du README).

Liens utiles

• Dépôt AIRecon
• README
  (install, config, usage)
• Documentation MKdocs /
  GitHub Pages
• Guide
  d’installation
• Features
  & capabilities
• Tools
  Reference
• Configuration
  Reference
• Changelog
• airecon-skills
  (skills communautaires)
• airecon-dataset (base
  de connaissances locale)
• Notebook
  Colab officiel
• Ollama
• Caido
• Issues du
  projet

FAQ

AIRecon nécessite-t-il une clé API ? Non. C’est l’un
des objectifs centraux du projet : fonctionner avec un LLM local
(Ollama), sans clé API et sans dépendance cloud. Voir la section Why
AIRecon? du README.

Quel modèle faut-il ? Un modèle avec tool calling
fiable et extended thinking, de préférence ≥ 8B. Le README recommande
qwen3.5:35b pour la plupart des utilisateurs (20 Go VRAM),
qwen3.5:9b en minimum viable (6 Go).

AIRecon exécute-t-il réellement des outils de pentest
? Oui. Toutes les commandes tournent dans un conteneur Kali
Linux Docker (airecon-sandbox) via l’outil
execute : nmap, nuclei, sqlmap, ffuf, katana, subfinder,
etc.

Comment empêche-t-il les hallucinations ? Plusieurs
mécanismes (docs/features.md) : détection de patterns d’hallucination
dans les réponses du LLM, validation des appels d’outils, exigence de
preuves pour les rapports, confidence scoring et déduplication
Jaccard.

Peut-on tester des applications authentifiées ? Oui
: login par formulaire, TOTP/2FA (RFC 6238), OAuth, injection de
cookies, persistance d’état, et gestion des CAPTCHA avec demande
d’entrée interactive à l’utilisateur.

Comment reprendre une session ?
airecon start --session <session_id>. Les données
(sous-domaines, vulns, tokens, technologies) sont persistées dans
~/.airecon/sessions/.

Faut-il Docker pour AIRecon ? Oui, Docker 20.10+ est
un prérequis : le bac à sable Kali (airecon-sandbox) est
une image Docker.

Les données sortent-elles de la machine ? Non, c’est
un principe du projet : intelligence, sorties d’outils et rapports
restent en local. Seule exception documentée : le mode Colab (Ollama
distant via tunnel) si vous n’avez pas de GPU local.

Conclusion

AIRecon illustre une tendance forte de la cybersécurité :
déléguer l’orchestration d’outils à un LLM local sans abandonner
la confidentialité. Le projet est ambitieux (pipeline complet,
Caido natif, fuzzer intégré, base de connaissances locale, MCP,
multi-agents) et très verbeux côté documentation, mais il reste en
version beta et exige du matériel (VRAM 8 Go minimum
réaliste) ainsi qu’un modèle Ollama capable de tool calling fiable.

Si vous voulez tester un agent de pentest autonome sans clé API, le
parcours le plus simple est : installer Ollama, tirer
qwen3.5:35b, builder le sandbox Docker, lancer
airecon start sur une cible autorisée,
puis explorer ses skills et la base airecon-dataset. Et
rappelez-vous : test d’intrusion uniquement sur des cibles
explicitement autorisées.