National Cyber Warfare Foundation (NCWF)login

airecon for autonomous LLM-driven reconnaissance and pentest pipelines


0 user ratings
2026-11-13 11:24:59
milo
Red Team (CNA)
"airecon

airecon is a Python autonomous penetration-testing agent that drives any OpenAI-compatible LLM through a Kali Docker sandbox, designed for authorized assessments and private lab workflows.








Toolpikpikcu/airecon — AI-powered autonomous penetration testing agent with a self-hosted LLM backend and Kali Linux Docker sandbox
CategoryAI-driven offensive security automation / reconnaissance CLI
Primary UseAutomating RECON → ANALYSIS → EXPLOIT → REPORT pipelines during authorized engagements, with Caido proxy integration and offline local-model operation
Safe UseIntended solely for authorized penetration tests, bug bounty programs within defined scope, CTF labs, and defensive research environments; its scope guard refuses out-of-scope targets
Telemetry NoteAll telemetry is local-on-disk: SQLite memory at ~/.airecon/memory/airecon.db, learning state in ~/.airecon/learning/global_learning.json, per-target memory under ~/.airecon/memory/by_target/, plus an audit log recording every executed command — defenders monitoring lab or assessment hosts can observe this footprint

airecon positions itself as an autonomous penetration-testing agent rather than yet another LLM wrapper, and the README's first paragraph makes the architectural bet clear: the agent drives any OpenAI-compatible LLM gateway — LiteLLM, vLLM, a hosted endpoint, or a gateway proxying a local Ollama — paired with a Kali Linux Docker sandbox for tool execution. At roughly 1,090 stars, MIT-licensed and written in Python 3.12+, it is an active and unusually well-documented entry in the ai-agents meets penetration-testing niche. The headline framing is backend-agnostic: point openai_base_url at a local gateway for fully offline operation where target intelligence and reports never leave the machine, or at a hosted GPT/Claude/Gemini endpoint when maximum reasoning quality matters. That choice is genuinely consequential for consultants under NDA constraints, and the README treats it as a first-class feature rather than a footnote.


The execution model is a structured RECON → ANALYSIS → EXPLOIT → REPORT pipeline with per-phase objectives, recommended tools, and automatic transition criteria. Notably, phase enforcement is explicitly soft — the agent is guided, not blocked — and a checkpoint cadence runs every 5, 10, and 15 iterations for phase evaluation, self-evaluation, and context compression respectively. This tells you the design anticipates the classic failure mode of long-running agents: context bloat and phase drift. The compression checkpoint is the more interesting mechanism from an operator's perspective, because a 32K-token context window (as suggested in the Colab config example) fills quickly during deep recon, and how gracefully the agent summarizes its own state largely determines whether hour-long autonomous sessions stay coherent.


The most substantive part of the README is the memory and learning section, which opens with a refreshingly honest disclaimer: airecon does not fine-tune the LLM. Its learning is local, structured telemetry that guides tool selection and avoids repeating failed paths. Persistence lives entirely on disk — a SQLite database at ~/.airecon/memory/airecon.db holding sessions, findings, patterns, target intel, and tool usage; adaptive learning state in ~/.airecon/learning/global_learning.json; per-target memory files under ~/.airecon/memory/by_target/ with endpoints, vulnerabilities, WAF bypasses, and auth endpoints; and optional payload memory snapshots in workspace//payload_memory.json. On session start, memory context is injected; learned patterns are re-injected every intelligence_memory_recall_interval iterations (default 4), with correlation running every 6.


The verified-only learning policy is the detail worth highlighting. Only findings that were verified or high-confidence are persisted to the cross-session brain — controlled by intelligence_learn_only_verified, on by default — so the agent compounds proven knowledge rather than hallucinated false positives. This directly addresses the biggest credibility problem in LLM-driven security tooling: an agent that learns from its own fabrications degrades over engagements. Adaptive tool ranking uses historical success/failure to order tools and suggest strategies, and within-session adaptation begins after as few as two observations (intelligence_adaptive_min_observations). Cold starts are handled by injecting a knowledge brief from a static tech_correlations dataset so the dataset functions as the brain from iteration one.


Model requirements are stated bluntly: native tool/function calling is required, full stop. Without it the agent cannot invoke http_observe, execute, the browser tools, or the Caido integration, and is non-functional. Reasoning support is auto-detected at runtime — the agent sends the standard reasoning_effort parameter and, if the backend returns HTTP 400 for an unsupported parameter, strips it and remembers, avoiding per-model hardcoding lists that rot. Two wire protocols are supported: llm_provider: openai against /v1/chat/completions and llm_provider: anthropic against /v1/messages, with llm_anthropic_auth selectable between x-api-key, bearer, or both. The quality guidance is candid: strong reasoning models yield reliable full recon pipelines, 8B–14B local models are usable for simple tasks with more tool-call errors, and sub-8B models are not recommended for serious testing.


Integration depth is where airecon differentiates from generic agent frameworks. Native Caido proxy integration exposes list, replay, automate with §FUZZ§, findings, scope, sitemap, and intercept operations directly to the model — meaning HTTP traffic observed through the proxy becomes agent-addressable surface. The full stack includes the Kali sandbox, browser automation, a custom fuzzer, Schemathesis API fuzzing, and Semgrep static analysis. A skills knowledge base ships with 57 built-in skill files and 289 keyword-to-skill auto-mappings, extendable through the companion airecon-skills repository with 57 additional community CLI playbooks for CTF, bug bounty, and pentest workflows. An optional airecon-dataset indexes roughly 1.09 million security records — CVEs, red team techniques, CTF writeups, nuclei templates, bug bounty payloads — into local SQLite FTS5, which the LLM queries via a dataset_search tool before attempting unfamiliar techniques, grounding decisions in indexed data rather than model memory alone.


For operators without local GPUs, the README documents a pragmatic pattern: run Ollama on a free Google Colab T4, expose it through a cloudflared tunnel, and point openai_base_url at the tunnel's /v1 path. A bundled notebook at scripts/airecon_colab.ipynb automates setup, with a VRAM-to-model table mapping T4 (15 GB) to 9B-class models up through H100 (80 GB) to 122B. The limitations are stated honestly — Colab sessions cap at 12 hours free, tunnel URLs rotate on reconnect, and the T4 minimum is described as producing slower responses and more tool-call errors, unsuitable for long autonomous sessions. Note the security implication: tunneling an LLM gateway over a public URL during an engagement is a trade-off worth weighing against the privacy guarantees of a purely local setup.


Installation offers two paths. The recommended one-liner pipes scripts/install.sh from the repository into bash, which auto-detects remote vs local mode, installs Poetry if missing, builds the wheel, and installs to ~/.local/bin. The manual path is a standard git clone https://github.com/pikpikcu/airecon.git followed by ./install.sh, then verifying with airecon --version. Configuration lives in ~/.airecon/config.yaml, auto-generated on first run, with the required openai_base_url (including /v1), openai_model, and openai_api_key for gateways that need one. Prerequisites are Python 3.12+, Docker 20.10+, git, and curl.


Two governance features deserve explicit mention because they are what make this tool defensible in an authorized workflow: a scope guard that refuses out-of-scope targets, and an audit log recording every command the agent executes. An autonomous agent running exploitation tooling without those two controls would be a liability in any professional engagement; with them, airecon fits into a scoped assessment where every action is reviewable after the fact. The session resume capability — covering both chat and tool calls — also matters for real engagements split across days. The README does carry a sponsor section for a residential proxy service, which readers should treat as advertising rather than technical documentation.


Operationally, airecon sits alongside tools like PentestGPT-style assistants but goes further by owning the execution environment (Kali sandbox), the traffic layer (Caido), persistent memory, and phase orchestration. The realistic best fit today is bug bounty recon and CTF-style exploration with a strong reasoning model, where the verified-only learning loop and dataset grounding measurably reduce noise. For defenders, the telemetry angle is straightforward: everything stays local and observable — the ~/.airecon/ directory tree, the SQLite database, and per-workspace payload memory snapshots give blue teams monitoring assessment infrastructure a complete record of what the agent did, which doubles as engagement documentation when it is time to write the report the pipeline's final phase promises.



Official project repository for pikpikcu/airecon.

Download Tool

Educational analysis for authorized security professionals. Use only in controlled, authorized environments.






Source: OffensiveSec
Source Link: https://www.offsecblog.com/2026/11/airecon-for-autonomous-llm-driven.html


Comments
new comment
Nobody has commented yet. Will you be the first?
 
Forum
Red Team (CNA)



Copyright 2012 through 2026 - National Cyber Warfare Foundation - All rights reserved worldwide.