Agente Autônomo de Teste de Penetração com IA

O AIRecon é um agente autônomo de teste de penetração que combina um Ollama LLM auto-hospedado com um sandbox Docker Kali Linux, integração nativa com proxy Caido, um pipeline estruturado RECON → ANALYSIS → EXPLOIT → REPORT e uma TUI Textual em tempo real — completamente offline, sem necessidade de chaves de API.

Por que AIRecon?

Modelos comerciais baseados em API (OpenAI GPT-4, Claude, Gemini) tornam-se proibitivamente caros para fluxos de trabalho de reconhecimento autônomo e recursivo que podem exigir milhares de chamadas LLM por sessão.

O AIRecon é construído 100% para operação local e privada.

• Privacidade em Primeiro Lugar — Inteligência sobre o alvo, saídas de ferramentas e relatórios nunca saem da sua máquina.
• Caido Nativo — 5 ferramentas integradas: list, replay, automate (§FUZZ§), findings, scope.
• Stack Completo — Sandbox Kali + automação de navegador + fuzzer personalizado + fuzzing de API Schemathesis + Semgrep SAST.
• Base de Conhecimento de Habilidades — 57 arquivos de habilidades integrados, 289 mapeamentos automáticos de palavra-chave → habilidade. Estendido por airecon-skills — uma biblioteca comunitária de habilidades com 57 playbooks adicionais baseados em CLI para CTF, bug bounty e pentest.
• Base de Conhecimento de Segurança Local — Opcional airecon-dataset indexa ~1.09M registros de segurança (CVEs, técnicas de red team, writeups de CTF, templates nuclei, payloads de bug bounty) em bancos de dados SQLite FTS5 locais. O LLM chama dataset_search autonomamente antes de tentar técnicas desconhecidas — fundamentando suas decisões em dados reais indexados.

Pipeline

RECON → ANALYSIS → EXPLOIT → REPORT

Cada fase tem objetivos específicos, ferramentas recomendadas e critérios de transição automáticos. A aplicação das fases é suave — o agente é guiado, mas nunca bloqueado. Os checkpoints são executados a cada 5 (avaliação de fase), 10 (autoavaliação) e 15 (compressão de contexto) iterações.

Memória e Aprendizado (O Que Realmente Faz)

O AIRecon não ajusta finamente o LLM. Seu 'aprendizado' é telemetria local e estruturada que orienta a escolha de ferramentas e evita repetir caminhos que falharam.

Persistência local (tudo em disco, sem nuvem):

• Banco de dados SQLite de memória em ~/.airecon/memory/airecon.db armazenando sessões, descobertas, padrões, inteligência do alvo, uso de ferramentas, desempenho do modelo, uso de habilidades e descobertas de cadeias de ataque.
• Estado de aprendizado adaptativo em ~/.airecon/learning/global_learning.json (estatísticas de desempenho de ferramentas, padrões de estratégia, registro de observações, insights destilados).
• Arquivos de memória por alvo em ~/.airecon/memory/by_target/ quando persistidos, contendo endpoints, vulnerabilidades, bypasses WAF, parâmetros sensíveis e endpoints de autenticação.
• Snapshots de memória de payloads podem ser salvos em workspace/<target>/payload_memory.json quando a persistência de sessão é executada.

Como isso afeta o comportamento:

• No início da sessão, o contexto de memória é injetado (inteligência do alvo, descobertas semelhantes, padrões aprendidos, confiabilidade das ferramentas).
• A cada 8 iterações, padrões aprendidos e descobertas semelhantes podem ser reinjetados com base na tecnologia detectada.
• A classificação adaptativa de ferramentas usa sucesso/falha histórica para ordenar ferramentas e sugerir estratégias.
• A memória de payloads (quando ativada) ignora payloads que falharam repetidamente para o mesmo alvo/parâmetro.

Requisitos do Modelo

O AIRecon requer um modelo com pensamento estendido (blocos <think>) e capacidades confiáveis de chamada de ferramenta. As capacidades são detectadas automaticamente via metadados do ollama show.

⚠️ Suporte a chamada de ferramentas é OBRIGATÓRIO. O modelo deve suportar chamada nativa de função/ferramenta. Modelos sem essa capacidade serão incapazes de executar qualquer ferramenta (http_observe, execute, ações de navegador, etc.), tornando o AIRecon completamente não funcional.

Mínimo recomendado: 8B-9B parâmetros. Modelos abaixo de 8B são tecnicamente utilizáveis, mas fortemente desencorajados — eles frequentemente alucinam saídas de ferramentas, inventam CVEs, ignoram regras de escopo e produzem chamadas de ferramenta não confiáveis.

Orientação de tamanho do modelo:

• ≥32B: Confiável para pipelines completos de reconhecimento, boa precisão de chamada de ferramenta
• 8B-14B: Utilizável para tarefas simples, espere 20-40% de erros de chamada de ferramenta e alucinações
• <8B: Tecnicamente funciona, mas produz resultados não confiáveis — não recomendado para testes sérios

Problemas conhecidos: DeepSeek R1 produz chamadas de função incompletas. Modelos < 8B não possuem suporte confiável de chamada de ferramenta.

Executando Ollama no Google Colab (Hardware Limitado)

Se você não tem uma GPU ou sua VRAM local está abaixo do mínimo, você pode executar o Ollama em uma GPU T4 gratuita do Google Colab e conectar o AIRecon a ela através de um túnel público.

Abra o notebook:

Como funciona:

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

Passos:

1. Abra o link do Colab acima e selecione Runtime → Change runtime type → T4 GPU
2. Execute todas as células de cima para baixo (leva ~5–10 minutos na primeira vez)
3. Copie o trecho de configuração impresso na Célula 6 para ~/.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. Inicie o AIRecon normalmente: airecon start

GPU Colab → disponibilidade de modelo:

Limitações:

• As sessões do Colab duram no máximo 12 horas (grátis) / 24 horas (Pro) — a URL do túnel muda ao reconectar
• T4 com qwen3.5:9b é a configuração mínima viável — espere respostas mais lentas e mais erros de chamada de ferramenta do que um modelo local 35B+
• Não é adequado para sessões autônomas longas (reconhecimento profundo pode exceder os limites da sessão)
• O notebook do Colab está localizado em scripts/airecon_colab.ipynb se você quiser auto-hospedar ou modificá-lo

Instalação

Pré-requisitos: Python 3.12+, Docker 20.10+, Ollama (em execução), git, curl

Instalação em uma linha (recomendada)

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

O script detecta automaticamente o modo remoto vs local, instala o Poetry se estiver faltando (via instalador oficial — sem conflitos de pacotes do sistema), compila o wheel e instala em ~/.local/bin.

Instalação manual (a partir do código fonte)

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

Configuração

Arquivo de configuração: ~/.airecon/config.yaml (gerado automaticamente na primeira execução). O AIRecon criará ~/.airecon/ se não existir, inclusive quando um caminho personalizado ~ for usado.

# ======================================
# 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 (servidor LAN ou túnel 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

Integração MCP

O AIRecon pode conectar-se a servidores MCP externos e expor suas ferramentas dinamicamente como ferramentas mcp_<server>.

Arquivo de configuração: ~/.airecon/mcp.json

Exemplo de configuração:

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

Usando ferramentas MCP no chat:

• Formato do nome da ferramenta: mcp_<server>
• Ações: list_tools, search_tools, call_tool

Exemplo:

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

Base de Conhecimento (airecon-dataset)

airecon-dataset é um complemento opcional que baixa conjuntos de dados de segurança do HuggingFace e os indexa localmente em bancos de dados SQLite FTS5. Depois de instalado, o LLM os consulta autonomamente através da ferramenta dataset_search.

Como funciona: dataset_search é uma ferramenta padrão do agente em tools.json. O LLM decide quando chamá-la — o AIRecon não a aciona automaticamente. O prompt do sistema instrui o agente a consultar a base de conhecimento antes de tentar técnicas desconhecidas.

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

Conjuntos de dados incluídos (~1.09M registros no total, 100% offline):

Exemplos de consultas do agente (chamadas autonomamente pelo 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"}

Os resultados são limitados a 500 caracteres cada. Caracteres especiais em IDs de CVE (traços, colchetes) são sanitizados automaticamente.

Uso

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

Exemplos de 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

Espaço de Trabalho

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)

As sessões persistem em ~/.airecon/sessions/<session_id>.json — subdomínios, portas, tecnologias, URLs, vulnerabilidades (dedup Jaccard), tokens de autenticação e fases concluídas.

Solução de Problemas

Ollama OOM / página de erro HTML — Mais comum em sessões longas ou modelos grandes próximos aos limites de VRAM.

sudo systemctl restart ollama

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

Agente em loop/travado — Geralmente uma falha de raciocínio. Tente um modelo maior ou reduza ollama_temperature para < 0.2.

Sandbox Docker não está iniciando:

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

Conexão Caido recusada — O Caido deve estar em execução antes do AIRecon. Padrão: 127.0.0.1:48080.

PATH não encontrado após a instalação:

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

Histórico de Estrelas

Contribuindo

Issues e PRs são bem-vindos. Se você relatar um bug, inclua logs, configuração e passos mínimos para reproduzir.

Uso Responsável

O AIRecon é apenas para testes de segurança autorizados. Sempre obtenha permissão explícita e siga as leis aplicáveis e o escopo do programa.

Licença

Veja LICENSE.