pentestagent

Framework de agente de teste de segurança com IA que pode operar como ou consumir servidores MCP, com ferramentas Docker/Kali. Use apenas contra sistemas para os quais você tenha autorização explícita de teste.

GitHub

3.2k

Documentação

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 o arquivo .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. Consulte .env.example para notas completas sobre provedores e opções de embeddings.

Execução

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

Docker

Execute as 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ápida)

# 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: Compilar 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

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

Modo	Comando	Descrição
Assist	`/assist <task>`	Uma única instrução pontual, com execução de ferramentas
Agent	`/agent <task>`	Execução autônoma de uma única tarefa
Crew	`/crew <task>`	Modo multiagente. O orquestrador cria agentes especializados
Interact	`/interact <task>`	Modo interativo. Converse com o agente; ele ajudará e orientará durante o procedimento de pentest

Comandos da TUI

/assist <task>    One single-shot instruction.
/agent <task>     Run autonomous agent on task
/crew <task>      Run multi-agent crew on task
/interact <task>  Chat with the agent in guided mode
/target <host>    Set target
/tools            List available tools
/notes            Show saved notes
/report           Generate report from session
/memory           Show token/memory usage
/prompt           Show system prompt
/conversations    Browse and restore saved conversations
/mcp <list/add>   Visualizes or adds a new MCP server.
/spawn [target] [--scope CIDR] [--model M] [--no-rag] [--no-mcp]
                  Manually spawn a child MCP agent from the TUI.
/despawn <server_name>
                  Terminate and remove a previously spawned child agent.
/clear            Clear chat and history
/quit             Exit (also /exit, /q)
/help             Show help (also /h, /?)

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

Playbooks

O PentestAgent inclui playbooks de ataque pré-construídos para testes de segurança black-box. Os playbooks definem uma abordagem estruturada para avaliações de segurança específicas.

Executar um playbook:

pentestagent run -t example.com --playbook thp3_web

Playbook Demo

Ferramentas

O 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 Agentes (`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 conversa 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 hierárquicos e multiagente sem orquestração externa: o agente se auto-organiza delegando subtarefas com escopo definido a filhos que ele cria sob demanda.

Argumento	Tipo	Padrão	Descrição
`target`	string	—	Alvo de pentest a ser passado ao filho
`scope`	string[]	—	Alvos/CIDRs no escopo para o filho
`model`	string	variável de ambiente	Identificador do modelo, substitui `PENTESTAGENT_MODEL` no filho
`no_rag`	boolean	`false`	Ignora a inicialização do mecanismo RAG no filho
`no_mcp`	boolean	`true`	Ignora conexões externas de servidores MCP no filho (recomendado)

Após spawn_mcp_agent retornar, as ferramentas do filho (run_task, run_task_async, await_tasks, etc.) ficam 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 reconhecimento 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 Agentes Filhos (`/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 [target] [--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 ao agente pai na próxima chamada de ferramenta.

Argumento	Descrição
`target`	Alvo de pentest a ser passado ao filho (posicional ou `--target`)
`--scope CIDR`	Um ou mais CIDRs no escopo (repetível)
`--model MODEL`	Substitui o modelo do agente filho
`--no-rag`	Ignora a inicialização do mecanismo RAG no filho
`--no-mcp`	Ignora conexões externas de servidores MCP no filho

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 RAG do MCP

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. Essa 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 rodada 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 em linguagem natural focadas descrevendo o que precisa, e as ferramentas correspondentes ficam disponíveis na próxima rodada para chamada direta.

Orientações de uso para o agente:

Argumento	Tipo	Padrão	Descrição
`queries`	string[]	(obrigatório)	Uma consulta focada por capacidade necessária. Quanto mais específica, maior a precisão
`top_k`	inteiro	`20`	Ferramentas a recuperar por consulta (máx. 128). Os resultados são mesclados e deduplicados

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 catálogo grande recebe seu próprio índice independente.

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

Integração MCP

O 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 acionar o PentestAgent programaticamente.

Consumindo Servidores MCP Externos (Modo Cliente)

Configure mcp_servers.json para conectar o PentestAgent a quaisquer servidores MCP externos. Exemplo de configuração:

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

Expondo o PentestAgent como 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 que suporta POST (requisições), GET (fluxo SSE persistente para push iniciado pelo servidor) e DELETE (encerramento de sessão). As sessões são rastreadas via cabeçalho Mcp-Session-Id.

Todas as flags de mcp_server:

Flag	Padrão	Descrição
`--type`	(obrigatório)	Transporte: `stdio` ou `sse`
`--host`	`0.0.0.0`	Host de bind do SSE
`--port`	`8080`	Porta de bind do SSE
`--target`	nenhum	Alvo principal de pentest (IP / hostname)
`--scope`	`[]`	Alvos/CIDRs no escopo (separados por espaço)
`--model`	variável de ambiente	Identificador do modelo, substitui `PENTESTAGENT_MODEL`
`--docker`	false	Usa DockerRuntime em vez de LocalRuntime
`--no-rag`	false	Ignora a inicialização do mecanismo RAG
`--no-mcp`	false	Ignora conexões externas de servidores MCP

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

Ao atuar como servidor MCP, o PentestAgent expõe as seguintes ferramentas:

Status e Configuração do Servidor

Ferramenta	Descrição
`get_server_status`	Status do servidor em tempo real: prontidão, contagens de tarefas por estado, alvo/escopo principal, tamanho do armazenamento de memória
`get_config`	Configuração principal do agente: alvo, escopo, iterações máximas, lista de ferramentas
`update_config`	Atualiza alvo, escopo ou iterações máximas para todas as tarefas subsequentes

Execução de Tarefas

Ferramenta	Descrição
`run_task`	Envia uma tarefa e bloqueia até que ela seja concluída. Retorna resultado completo, ferramentas usadas e snapshot de notas
`run_task_async`	Envia uma tarefa e retorna imediatamente com um `task_id`. Consulte com `get_task_status`

Inspeção de Tarefas

Ferramenta	Descrição
`list_tasks`	Lista todas as tarefas com status, alvo e resumo. Filtrável por status
`get_task_status`	Consulta o status atual e a prévia do resultado de uma tarefa
`get_task_result`	Resultado completo da tarefa: saída final, etapas de raciocínio, todas as chamadas de ferramentas e resultados, snapshot de notas
`await_tasks`	Bloqueia até que um conjunto de IDs de tarefas assíncronas tenha terminado (consulta a cada 500 ms, timeout configurável)

Controle de Tarefas

Ferramenta	Descrição
`cancel_task`	Cancela uma tarefa em execução ou pendente por ID

Gerenciamento de Ferramentas

Ferramenta	Descrição
`list_tools`	Lista todas as ferramentas disponíveis ao agente
`enable_tool`	Habilita uma ferramenta nomeada no agente principal
`disable_tool`	Desabilita uma ferramenta nomeada no agente principal

Histórico de Conversa

Ferramenta	Descrição
`get_conversation_history`	Retorna o histórico de mensagens de uma tarefa ou do agente principal. Suporta um parâmetro `limit`
`reset_conversation`	Limpa o histórico de conversa de uma tarefa ou do agente principal

Memória

Ferramenta	Descrição
`store_memory`	Persiste um par chave-valor no armazenamento de memória em processo
`retrieve_memory`	Recupera por chave exata, busca por substring ou lista todas as chaves
`clear_memory`	Exclui uma chave específica ou apaga toda a memória com `scope='all'`

Observabilidade

Ferramenta	Descrição
`get_logs`	Retorna logs de execução recentes, opcionalmente filtrados por nível (`info` / `warning` / `error`)
`get_metrics`	Métricas de runtime: contagens de tarefas, taxa de sucesso, total de chamadas de ferramentas, tamanhos de memória e logs

Exemplo de Fluxo de Trabalho com Tarefas Assíncronas

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 Conversa

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 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:

A conversa completa atual é salva no armazenamento de conversas e um ID curto de snapshot é exibido.
A conversa é então truncada até o ponto imediatamente anterior à mensagem selecionada (mesmo comportamento do rewind). Isto permite que você tente uma abordagem alternativa a partir de qualquer ponto, mantendo o thread original recuperável via /conversations.

Histórico de Conversas

O PentestAgent salva automaticamente todas as conversas para que você possa revisar, comparar e restaurar sessões anteriores.

Salvamento automático é acionado após cada tarefa de /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.

Navegue e restaure com /conversations:

O comando /conversations abre um modal de painel dividido dentro do 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 ferramentas em amarelo, resultados de ferramentas em cinza). Um contador mostra quantas mensagens adicionais existem.

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

Conhecimento

RAG: Coloque metodologias, CVEs ou wordlists em pentestagent/knowledge/sources/ para injeção automática de contexto.
Notas: Os 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ê tem autorização explícita para testar. Acesso não autorizado é ilegal.

Licença

MIT