AIRecon¶

AI-Assisted Penetration Testing Agent

AIRecon 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.

Why AIRecon?¶

AIRecon is designed for local-first workflows where model execution and tool orchestration run in your own environment.

Feature	AIRecon	Cloud-based agents
API keys required	No	Yes
Target data sent to cloud	No	Yes
Works offline	Yes	No
Caido integration	Native	None
Session resume	Yes	Varies
VRAM/oom recovery	Yes	N/A
MCP support	Built-in	Varies

Core Features¶

Pipeline Engine¶

Structured 4-phase state machine: RECON → ANALYSIS → EXPLOIT → REPORT. Auto-transitions based on real findings, not iteration counts.

Ollama Stability¶

Includes VRAM/OOM recovery paths, context monitoring, and conversation compression controls.

Exploration Engine¶

Anti-stagnation with tool diversity tracking, same-tool streak detection, and per-phase exploration directives.

Docker Sandbox¶

Kali Linux container with a curated recon/testing toolset. See the tools reference for the current catalog.

Skills System¶

Built-in skill files are loaded on demand and can be extended with airecon-skills.

Local Knowledge Base¶

Optional airecon-dataset indexes ~1.09M security records (13 datasets: CVEs, red team techniques, CTF writeups, nuclei templates, SQLi, reverse engineering, priv esc) locally. The agent queries it via dataset_search before attempting unfamiliar techniques.

Caido Integration¶

Built-in tools: list, replay, automate (§FUZZ§), findings, and scope. Default endpoint: 127.0.0.1:48080.

Browser Automation¶

Headless Chromium via Playwright, with session/cookie support and authentication helper flows.

Session Memory¶

Findings and session state are persisted to disk. Sessions can be resumed with airecon start --session <id>.

Security Controls¶

Includes command validation, symlink safety checks, CVE format validation, and session-save locking.

Stability Focused¶

Config-based context limits, tool result truncation (50KB), incremental pruning, per-request timeouts, browser cleanup with force kill.

Release Notes¶

See Changelog for versioned updates.

Quick Start¶

1. install (recommended)¶

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

2. Start¶

airecon start

Model guidance

Use the largest model you can run reliably. AIRecon requires native tool calling support. Smaller models can work for limited tasks but are less reliable for long, autonomous runs.

Small models

Models below 8B are not recommended for full engagements. Expect more tool-call errors and hallucinations as model size shrinks.

Pipeline¶

RECON ──────────────────────► ANALYSIS
  Enumerate attack surface       Identify injection points
  subfinder, nmap, katana,       semgrep, browser, httpx,
  httpx, ffuf, web_search        technology fingerprinting
         │                              │
         └──────────────────────────────┘
                                        │
                               EXPLOIT  ▼
                               Confirm vulnerabilities
                               quick_fuzz, advanced_fuzz,
                               sqlmap, dalfox, spawn_agent
                                        │
                               REPORT   ▼
                               Document all findings
                               create_vulnerability_report

Each phase has objectives, recommended tools, and transition criteria. Tool lists are examples; actual execution depends on scope and data. Phase enforcement is guidance-based and configurable.

Documentation¶

Guide	Description
Installation	Hardware requirements, step-by-step setup, troubleshooting
Configuration	All config options with defaults, presets, and env var overrides
Features	Deep dive into every feature — pipeline, browser auth, fuzzing, skills, anti-context-loss
Tools Reference	Complete reference for native tools and MCP tools
Creating Skills	Write your own skill files, use the airecon-skills community library
Stability & Quality Status	Current validation snapshot, known blockers, and release-stability criteria
Changelog	Version history and release notes

Community¶

GitHub: github.com/pikpikcu/airecon
Skills Library: github.com/pikpikcu/airecon-skills
Dataset Library: github.com/pikpikcu/airecon-dataset
Issues / Bug Reports: GitHub Issues

Legal Disclaimer

AIRecon is built strictly for educational purposes, ethical hacking, and authorized security assessments. Any actions related to the material in this tool are solely your responsibility. Do not use this tool on systems you do not own or have explicit permission to test.