PentestAgent

Testes de Penetração com IA

https://github.com/user-attachments/assets/a67db2b5-672a-43df-b709-149c8eaee975

Requisitos

• Python 3.10+
• Chave de API para OpenAI, Anthropic ou outro provedor suportado pelo LiteLLM

Instalação

# Clone
git clone https://github.com/GH05TCREW/pentestagent.git
cd pentestagent

# Setup (creates venv, installs deps)
.\scripts\setup.ps1   # Windows
./scripts/setup.sh    # Linux/macOS

# Or manual
python -m venv venv
.\venv\Scripts\Activate.ps1  # Windows
source venv/bin/activate     # Linux/macOS
pip install -e ".[all]"
playwright install chromium  # Required for browser tool

Configuração

Crie .env na raiz do projeto:

ANTHROPIC_API_KEY=sk-ant-...
PENTESTAGENT_MODEL=claude-sonnet-4-20250514

Ou para OpenAI:

OPENAI_API_KEY=sk-...
PENTESTAGENT_MODEL=gpt-5

Qualquer modelo suportado pelo LiteLLM funciona.

Usando um relay / base de API personalizada

Aponte o PentestAgent para qualquer endpoint compatível com OpenAI via OPENAI_API_BASE:

OPENAI_API_KEY=your-relay-token
OPENAI_API_BASE=https://relay.example/v1
PENTESTAGENT_MODEL=openai/<model-name-on-your-relay>

Para endpoints compatíveis com Anthropic, use ANTHROPIC_API_BASE em vez disso. Veja .env.example para notas completas sobre provedores e opções de embeddings.

Executar

pentestagent                      # Launch TUI
pentestagent -t 192.168.1.1       # Launch with target
pentestagent tui --docker         # Run tools in Docker container

Docker

Execute ferramentas dentro de um contêiner Docker para isolamento e ferramentas de pentest pré-instaladas.

Opção 1: Baixar imagem pré-construída (mais rápido)

# Base image with nmap, netcat, curl
docker run -it --rm \
  -e ANTHROPIC_API_KEY=your-key \
  -e PENTESTAGENT_MODEL=claude-sonnet-4-20250514 \
  ghcr.io/gh05tcrew/pentestagent:latest

# Kali image with metasploit, sqlmap, hydra, etc.
docker run -it --rm \
  -e ANTHROPIC_API_KEY=your-key \
  ghcr.io/gh05tcrew/pentestagent:kali

Opção 2: Construir localmente

# Build
docker compose build

# Run
docker compose run --rm pentestagent

# Or with Kali
docker compose --profile kali build
docker compose --profile kali run --rm pentestagent-kali

O contêiner executa o PentestAgent com acesso a ferramentas de pentest Linux. O agente pode usar nmap, msfconsole, sqlmap, etc. diretamente via a ferramenta de terminal.

Requer Docker instalado e em execução.

Modos

PentestAgent possui três modos, acessíveis por comandos na TUI:

Comandos da TUI

/assist <tarefa>    Uma instrução única.
/agent <tarefa>     Executar agente autônomo na tarefa
/crew <tarefa>      Executar equipe multi-agente na tarefa
/interact <tarefa>  Conversar com o agente em modo guiado
/target <host>      Definir alvo
/tools              Listar ferramentas disponíveis
/notes              Mostrar notas salvas
/report             Gerar relatório da sessão
/memory             Mostrar uso de token/memória
/prompt             Mostrar prompt do sistema
/conversations      Navegar e restaurar conversas salvas
/mcp <list/add>     Visualizar ou adicionar um novo servidor MCP.
/spawn [alvo] [--scope CIDR] [--model M] [--no-rag] [--no-mcp]
                    Criar manualmente um agente MCP filho a partir da TUI.
/despawn <server_name>
                    Encerrar e remover um agente filho previamente criado.
/clear              Limpar chat e histórico
/quit               Sair (também /exit, /q)
/help               Mostrar ajuda (também /h, /?)

Pressione Esc para parar um agente em execução. Ctrl+Q para sair.

Playbooks

PentestAgent inclui playbooks de ataque pré-construídos para testes de segurança de caixa-preta. Playbooks definem uma abordagem estruturada para avaliações de segurança específicas.

Executar um playbook:

pentestagent run -t example.com --playbook thp3_web

Ferramentas

PentestAgent inclui ferramentas integradas e suporta MCP (Model Context Protocol) para extensibilidade.

Ferramentas integradas: terminal, browser, notes, web_search (requer TAVILY_API_KEY), spawn_mcp_agent

Auto-criação de Agente (spawn_mcp_agent)

spawn_mcp_agent é uma ferramenta integrada que permite a um agente em execução criar uma cópia filha de si mesmo como um servidor MCP subordinado conectado via stdio. O processo filho é totalmente isolado — seu próprio runtime, cliente LLM, histórico de conversas e armazenamento de notas — e seu conjunto completo de ferramentas é injetado de volta nas ferramentas disponíveis do agente pai após a criação.

Isso permite fluxos de trabalho multi-agente hierárquicos sem qualquer orquestração externa: o agente se auto-organiza delegando subtarefas com escopo definido a filhos que cria sob demanda.

Após o retorno de spawn_mcp_agent, as ferramentas do filho (run_task, run_task_async, await_tasks, etc.) estarão disponíveis na próxima chamada de ferramenta. O nome do servidor do filho é atribuído automaticamente (ex: child_agent_1) e retornado no resultado.

Exemplo — orquestrador delegando recon paralelo a dois filhos:

# Turn 1: spawn two isolated child agents
spawn_mcp_agent  target="10.0.1.0/24"  scope=["10.0.1.0/24"]
spawn_mcp_agent  target="10.0.2.0/24"  scope=["10.0.2.0/24"]

# Turn 2: children's tools are now available — delegate work asynchronously
child_agent_1__run_task_async  task="Full port scan and service enumeration"
child_agent_2__run_task_async  task="Full port scan and service enumeration"

# Turn 3: wait and collect
child_agent_1__await_tasks  task_ids=["<id1>"]  timeout_seconds=600
child_agent_2__await_tasks  task_ids=["<id2>"]  timeout_seconds=600
child_agent_1__get_task_result  task_id="<id1>"
child_agent_2__get_task_result  task_id="<id2>"

Controle Manual de Agente Filho (/spawn e /despawn)

Além da ferramenta automática spawn_mcp_agent, a TUI expõe dois comandos que permitem criar e encerrar agentes filhos manualmente, independentemente de um loop de agente em execução.

/spawn

/spawn [alvo] [--scope CIDR ...] [--model MODEL] [--no-rag] [--no-mcp]

Cria um novo agente MCP filho via stdio e o anexa à sessão atual. O filho aparece como um painel de terminal recolhível na barra lateral da TUI e suas ferramentas ficam disponíveis para o agente pai na próxima chamada de ferramenta.

Exemplos:

/spawn 10.0.1.1
/spawn 10.0.1.1 --scope 10.0.1.0/24 --model claude-sonnet-4-20250514
/spawn --target 10.0.1.1 --scope 10.0.1.0/24 --no-rag

/despawn

/despawn <server_name>

Encerra o agente filho identificado por server_name (ex: child_agent_1), remove seu painel de terminal da TUI e desconecta suas ferramentas da sessão pai. Use /mcp list para ver os nomes de todos os agentes filhos ativos.

Exemplo:

/despawn child_agent_1

Otimizador de Ferramentas MCP RAG

Quando um servidor MCP expõe mais de 128 ferramentas, o PentestAgent substitui automaticamente o catálogo completo por uma única ferramenta mcp_<server>_rag_optimizer. Esta meta-ferramenta usa similaridade de embeddings (via LiteLLM, padrão text-embedding-3-small) para recuperar as ferramentas mais relevantes para a tarefa em questão e as injeta na próxima iteração do agente — mantendo a janela de contexto gerenciável sem perder acesso ao conjunto completo de ferramentas.

O otimizador é transparente para o agente: ele chama a ferramenta RAG com consultas focadas em linguagem natural descrevendo o que precisa, e as ferramentas correspondentes ficam disponíveis na próxima iteração para serem chamadas diretamente.

Orientação de uso para o agente:

Os embeddings são calculados uma vez na inicialização e armazenados em cache, portanto consultas repetidas são rápidas. O otimizador é construído por servidor, então cada servidor MCP com um grande catálogo obtém seu próprio índice independente.

Dica: Passe uma consulta por capacidade distinta, em vez de combinar tudo em uma consulta. ["list open ports on a host", "get process memory usage"] obtém melhores resultados do que ["list ports and memory and CPU"].

Integração MCP

PentestAgent suporta MCP (Model Context Protocol) em duas direções: consumindo servidores MCP externos como fontes de ferramentas, e expondo-se como um servidor MCP para que clientes externos (Claude Desktop, Cursor, etc.) possam controlar o PentestAgent programaticamente.

Consumindo Servidores MCP Externos (Modo Cliente)

Configure mcp_servers.json para conectar o PentestAgent a qualquer servidor MCP externo. Exemplo de configuração:

{
  "mcpServers": {
    "nmap": {
      "command": "npx",
      "args": ["-y", "gc-nmap-mcp"],
      "env": {
        "NMAP_PATH": "/usr/bin/nmap"
      }
    }
  }
}

Expondo o PentestAgent como um Servidor MCP (Modo Servidor)

O PentestAgent pode ser executado como um servidor MCP, permitindo que qualquer cliente compatível com MCP envie tarefas, inspecione resultados e controle o agente remotamente. Dois transportes são suportados:

STDIO — para clientes locais (ex: Claude Desktop, Cursor):

pentestagent mcp_server --type stdio
pentestagent mcp_server --type stdio --target 192.168.1.1 --scope 192.168.1.0/24
pentestagent mcp_server --type stdio --model claude-sonnet-4-20250514 --docker

SSE (HTTP) — para clientes remotos ou em rede:

pentestagent mcp_server --type sse
pentestagent mcp_server --type sse --host 0.0.0.0 --port 8080
pentestagent mcp_server --type sse --target 10.0.0.1 --scope 10.0.0.0/24 --docker

O transporte SSE expõe um único endpoint /mcp suportando POST (requisições), GET (stream SSE persistente para push iniciado pelo servidor) e DELETE (encerramento de sessão). As sessões são rastreadas através do cabeçalho Mcp-Session-Id.

Todos os flags de mcp_server:

Exemplo: Configuração do Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "pentestagent": {
      "command": "pentestagent",
      "args": ["mcp_server", "--type", "stdio"]
    }
  }
}

Referência de Ferramentas do Servidor MCP

Quando atua como servidor MCP, o PentestAgent expõe as seguintes ferramentas:

Status e Config do Servidor

Execução de Tarefas

Inspeção de Tarefas

Controle de Tarefas

Gerenciamento de Ferramentas

Histórico de Conversas

Memória

Observabilidade

Exemplo de Fluxo de Trabalho de Tarefa Assíncrona

Para tarefas de reconhecimento de longa duração, use o padrão assíncrono:

# 1. Submit tasks without blocking
run_task_async  task="Enumerate subdomains of example.com"  target="example.com"
run_task_async  task="Run nmap SYN scan on example.com"     target="example.com"

# 2. Block until both finish (up to 5 minutes)
await_tasks  task_ids=["<id1>", "<id2>"]  timeout_seconds=300

# 3. Retrieve full results
get_task_result  task_id="<id1>"
get_task_result  task_id="<id2>"

Gerenciamento de Ferramentas via CLI

pentestagent tools list         # List all tools
pentestagent tools info <name>  # Show tool details
pentestagent mcp list           # List MCP servers
pentestagent mcp add <name> <command> [args...]  # Add MCP server
pentestagent mcp test <name>    # Test MCP connection

Controles de Histórico de Conversas

Cada mensagem do usuário na TUI expõe dois botões de ação inline: rewind e fork.

Rewind

Clique em rewind em qualquer mensagem do usuário para truncar a conversa de volta ao ponto imediatamente anterior àquela mensagem — tanto na interface quanto no histórico em memória do agente. Use para tentar novamente uma consulta do zero sem salvar o caminho descartado.

Fork

Clique em >> fork em qualquer mensagem do usuário para ramificar a conversa a partir daquele ponto:

1. A conversa completa atual é salva no armazenamento de conversas e um ID curto de snapshot é exibido.
2. A conversa é então truncada para imediatamente antes da mensagem selecionada (mesmo que o rewind).

Isso permite tentar uma abordagem alternativa a partir de qualquer ponto, mantendo o thread original recuperável via /conversations.

Histórico de Conversas

PentestAgent persiste automaticamente cada conversa para que você possa revisar, comparar e restaurar sessões passadas.

O salvamento automático é acionado após cada tarefa /assist, /agent, /crew e /interact, e antes de /clear. Até 20 conversas são mantidas; as mais antigas são removidas automaticamente.

Local de armazenamento: workspaces/<active>/memory/conversations/ quando um workspace está ativo, ou conversations/ na raiz do projeto caso contrário. Cada conversa é um arquivo JSON.

Navegar e restaurar com /conversations:

O comando /conversations abre um modal de painel dividido dentro da TUI:

• Painel esquerdo — lista de conversas salvas com título e data.
• Painel direito — pré-visualização de metadados mais as primeiras 5 mensagens (mensagens do usuário em azul, respostas do agente em verde, chamadas de ferramenta em amarelo, resultados de ferramenta em cinza). Uma contagem mostra quantas mensagens adicionais existem.

Selecione uma conversa e pressione Restore para recarregá-la na sessão atual, ou Close para dispensar o modal.

Conhecimento

• RAG: Coloque metodologias, CVEs ou wordlists em pentestagent/knowledge/sources/ para injeção automática de contexto.
• Notas: Agentes salvam descobertas em loot/notes.json com categorias (credential, vulnerability, finding, artifact). As notas persistem entre sessões e são injetadas no contexto do agente.
• Shadow Graph: No modo Crew, o orquestrador constrói um grafo de conhecimento a partir das notas para derivar insights estratégicos (ex.: "Temos credenciais para o host X").

Estrutura do Projeto

pentestagent/
  agents/         # Agent implementations
  config/         # Settings and constants
  interface/      # TUI and CLI
  knowledge/      # RAG system and shadow graph
  llm/            # LiteLLM wrapper
  mcp/            # MCP client and server configs
  playbooks/      # Attack playbooks
  runtime/        # Execution environment
  tools/          # Built-in tools

Desenvolvimento

pip install -e ".[dev]"
pytest                       # Run tests
pytest --cov=pentestagent    # With coverage
black pentestagent           # Format
ruff check pentestagent      # Lint

Legal

Use apenas contra sistemas para os quais você tenha autorização explícita para testar. Acesso não autorizado é ilegal.

Licença

MIT