Framework di agenti AI per test di sicurezza black-box con orchestrazione autonoma multi-agente, strumenti di pentesting integrati e integrazione MCP per bug bounty, red-team e flussi di lavoro di penetration testing.
https://github.com/user-attachments/assets/a67db2b5-672a-43df-b709-149c8eaee975
# Clona
git clone https://github.com/GH05TCREW/pentestagent.git
cd pentestagent
# Configurazione (crea venv, installa dipendenze)
.\scripts\setup.ps1 # Windows
./scripts/setup.sh # Linux/macOS
# Oppure manuale
python -m venv venv
.\venv\Scripts\Activate.ps1 # Windows
source venv/bin/activate # Linux/macOS
pip install -e ".[all]"
playwright install chromium # Richiesto per lo strumento browser
Crea un file .env nella root del progetto:
ANTHROPIC_API_KEY=sk-ant-...
PENTESTAGENT_MODEL=claude-sonnet-4-20250514
Oppure per OpenAI:
OPENAI_API_KEY=sk-...
PENTESTAGENT_MODEL=gpt-5
Qualsiasi modello supportato da LiteLLM funziona.
Punta PentestAgent a qualsiasi endpoint compatibile con OpenAI tramite OPENAI_API_BASE:
OPENAI_API_KEY=your-relay-token
OPENAI_API_BASE=https://relay.example/v1
PENTESTAGENT_MODEL=openai/<nome-modello-sul-tuo-relay>
Per endpoint compatibili con Anthropic, usa ANTHROPIC_API_BASE.
Vedi .env.example per note complete sui provider e opzioni di embedding.
pentestagent # Avvia TUI
pentestagent -t 192.168.1.1 # Avvia con target
pentestagent tui --docker # Esegue strumenti in container Docker
Esegue gli strumenti all'interno di un container Docker per isolamento e strumenti di pentesting preinstallati.
# Immagine base con 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
# Immagine Kali con metasploit, sqlmap, hydra, ecc.
docker run -it --rm \
-e ANTHROPIC_API_KEY=your-key \
ghcr.io/gh05tcrew/pentestagent:kali
# Build
docker compose build
# Esecuzione
docker compose run --rm pentestagent
# Oppure con Kali
docker compose --profile kali build
docker compose --profile kali run --rm pentestagent-kali
Il container esegue PentestAgent con accesso agli strumenti di pentesting Linux. L'agente può usare nmap, msfconsole, sqlmap, ecc. direttamente tramite lo strumento terminale.
Richiede Docker installato e in esecuzione.
PentestAgent ha tre modalità, accessibili tramite comandi nella TUI:
| Modalità | Comando | Descrizione |
|---|---|---|
| Assist | /assist <compito> | Singola istruzione one-shot, con esecuzione di strumenti |
| Agent | /agent <compito> | Esecuzione autonoma di un singolo compito |
| Crew | /crew <compito> | Modalità multi-agente. L'orchestrator genera lavoratori specializzati |
| Interact | /interact <compito> | Modalità interattiva. Chatta con l'agente, che ti aiuterà e guiderà durante la procedura di pentesting |
/assist <compito> Singola istruzione one-shot.
/agent <compito> Esegue agente autonomo su un compito
/crew <compito> Esegue team multi-agente su un compito
/interact <compito> Chatta con l'agente in modalità guidata
/target <host> Imposta target
/tools Elenca strumenti disponibili
/notes Mostra note salvate
/report Genera report dalla sessione
/memory Mostra utilizzo token/memoria
/prompt Mostra prompt di sistema
/conversations Sfoglia e ripristina conversazioni salvate
/mcp <list/add> Visualizza o aggiunge un nuovo server MCP.
/spawn [target] [--scope CIDR] [--model M] [--no-rag] [--no-mcp]
Genera manualmente un agente MCP figlio dalla TUI.
/despawn <nome_server>
Termina e rimuove un agente figlio generato in precedenza.
/clear Pulisci chat e cronologia
/quit Esci (anche /exit, /q)
/help Mostra aiuto (anche /h, /?)
Premere Esc per fermare un agente in esecuzione. Ctrl+Q per uscire.
PentestAgent include playbook di attacco predefiniti per test di sicurezza black-box. I playbook definiscono un approccio strutturato a specifiche valutazioni di sicurezza.
Esegui un playbook:
pentestagent run -t example.com --playbook thp3_web
PentestAgent include strumenti integrati e supporta MCP (Model Context Protocol) per estensibilità.
Strumenti integrati: terminal, browser, notes, web_search (richiede TAVILY_API_KEY), spawn_mcp_agent
spawn_mcp_agent)spawn_mcp_agent è uno strumento integrato che permette a un agente in esecuzione di generare una copia figlia di sé stesso come server MCP subordinato connesso su stdio. Il processo figlio è completamente isolato — proprio runtime, client LLM, cronologia conversazioni e archivio note — e l'insieme completo dei suoi strumenti viene iniettato negli strumenti disponibili dell'agente padre dopo la generazione.
Ciò consente flussi di lavoro multi-agente gerarchici senza orchestrazione esterna: l'agente si auto-organizza delegando sottocompiti con ambito definito a figli che genera su richiesta.
| Argomento | Tipo | Default | Descrizione |
|---|---|---|---|
target | stringa | — | Target di pentest da passare al figlio |
scope | stringa[] | — | Target/CIDR nell'ambito per il figlio |
model | stringa | variabile d'ambiente | Identificatore del modello, sovrascrive PENTESTAGENT_MODEL sul figlio |
no_rag | booleano | false | Salta inizializzazione motore RAG sul figlio |
no_mcp | booleano | true | Salta connessioni server MCP esterni sul figlio (consigliato) |
Dopo che spawn_mcp_agent ritorna, gli strumenti del figlio (run_task, run_task_async, await_tasks, ecc.) sono disponibili alla prossima chiamata di strumento. Il nome del server figlio viene assegnato automaticamente (es. child_agent_1) e restituito nel risultato.
Esempio — orchestratore delega ricognizione parallela a due figli:
# Turno 1: genera due agenti figli isolati
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"]
# Turno 2: gli strumenti dei figli sono ora disponibili — delega lavoro in modo asincrono
child_agent_1__run_task_async task="Scansione porte completa ed enumerazione servizi"
child_agent_2__run_task_async task="Scansione porte completa ed enumerazione servizi"
# Turno 3: attendi e raccogli
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)