Framework de agente de IA para testes de segurança em caixa preta com orquestração autônoma de múltiplos agentes, ferramentas de pentest integradas e integração com MCP para workflows de bug bounty, red-team e testes de penetração.
https://github.com/user-attachments/assets/a67db2b5-672a-43df-b709-149c8eaee975
# 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
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.
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.
pentestagent # Launch TUI
pentestagent -t 192.168.1.1 # Launch with target
pentestagent tui --docker # Run tools in Docker container
Execute ferramentas dentro de um contêiner Docker para isolamento e ferramentas de pentest pré-instaladas.
# 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
# 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.
PentestAgent possui três modos, acessíveis por comandos na TUI:
| Modo | Comando | Descrição |
|---|---|---|
| Assist | /assist <tarefa> | Uma instrução única, com execução de ferramentas |
| Agent | /agent <tarefa> | Execução autônoma de uma única tarefa |
| Crew | /crew <tarefa> | Modo multi-agente. O orquestrador cria trabalhadores especializados |
| Interact | /interact <tarefa> | Modo interativo. Converse com o agente, ele irá ajudar e guiar durante o procedimento de pentest |
/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.
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
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
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.
| Argumento | Tipo | Padrão | Descrição |
|---|---|---|---|
target | string | — | Alvo de pentest a ser passado para o 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 | Pular inicialização do motor RAG no filho |
no_mcp | boolean | true | Pular conexões de servidor MCP externas no filho (recomendado) |
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>"
/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