PentestAgent

Test di Penetrazione AI

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

Requisiti

• Python 3.10+
• Chiave API per OpenAI, Anthropic o altri provider supportati da LiteLLM

Installazione

# 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

Configurazione

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.

Utilizzo di un relay / base API personalizzata

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.

Esecuzione

pentestagent                      # Avvia TUI
pentestagent -t 192.168.1.1       # Avvia con target
pentestagent tui --docker         # Esegue strumenti in container Docker

Docker

Esegue gli strumenti all'interno di un container Docker per isolamento e strumenti di pentesting preinstallati.

Opzione 1: Scarica immagine pre-costruita (più veloce)

# 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

Opzione 2: Build locale

# 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.

Modalità

PentestAgent ha tre modalità, accessibili tramite comandi nella TUI:

Comandi TUI

/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.

Playbook

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

Strumenti

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

Auto-generazione dell'agente (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.

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

Controllo Manuale dell'Agente Figlio (/spawn e /despawn)

Oltre allo strumento automatico spawn_mcp_agent, la TUI espone due comandi che ti permettono di generare e terminare agenti figli manualmente, indipendentemente da un ciclo agente in esecuzione.

/spawn

/spawn [target] [--scope CIDR ...] [--model MODELLO] [--no-rag] [--no-mcp]

Genera un nuovo agente MCP figlio su stdio e lo collega alla sessione corrente. Il figlio appare come pannello terminale collassabile nella barra laterale della TUI e i suoi strumenti diventano disponibili per l'agente padre alla prossima chiamata di strumento.

Esempi:

/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 <nome_server>

Termina l'agente figlio identificato da nome_server (es. child_agent_1), rimuove il suo pannello terminale dalla TUI e disconnette i suoi strumenti dalla sessione padre. Usa /mcp list per vedere i nomi di tutti gli agenti figli attualmente attivi.

Esempio:

/despawn child_agent_1

Ottimizzatore di Strumenti MCP RAG

Quando un server MCP espone più di 128 strumenti, PentestAgent sostituisce automaticamente l'intero catalogo con un singolo strumento mcp_<server>_rag_optimizer. Questo meta-strumento utilizza la similarità di embedding (tramite LiteLLM, default text-embedding-3-small) per recuperare gli strumenti più rilevanti per il compito corrente e li inietta nel turno successivo dell'agente — mantenendo la finestra di contesto gestibile senza perdere l'accesso all'insieme completo degli strumenti.

L'ottimizzatore è trasparente per l'agente: chiama lo strumento RAG con query mirate in linguaggio naturale che descrivono ciò di cui ha bisogno, e gli strumenti corrispondenti diventano disponibili al turno successivo per essere chiamati direttamente.

Guida all'uso per l'agente:

Gli embedding vengono calcolati una volta all'avvio e memorizzati nella cache, quindi le query ripetute sono veloci. L'ottimizzatore è costruito per server, quindi ogni server MCP con un catalogo grande ha il proprio indice indipendente.

Suggerimento: Passa una query per ogni capacità distinta invece di combinare tutto in una singola query. ["list open ports on a host", "get process memory usage"] produce risultati migliori rispetto a ["list ports and memory and CPU"].

Integrazione MCP

PentestAgent supporta MCP (Model Context Protocol) in due direzioni: consumare server MCP esterni come fonti di strumenti, ed esporsi come server MCP in modo che client esterni (Claude Desktop, Cursor, ecc.) possano guidare PentestAgent programmaticamente.

Consumare Server MCP Esterni (Modalità Client)

Configura mcp_servers.json per connettere PentestAgent a qualsiasi server MCP esterno. Esempio di configurazione:

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

Esporre PentestAgent come Server MCP (Modalità Server)

PentestAgent può essere eseguito come server MCP, permettendo a qualsiasi client compatibile con MCP di inviare compiti, ispezionare risultati e controllare l'agente da remoto. Sono supportati due trasporti:

STDIO — per client locali (es. 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) — per client remoti o in rete:

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

Il trasporto SSE espone un singolo endpoint /mcp che supporta POST (richieste), GET (stream SSE persistente per push iniziati dal server) e DELETE (teardown della sessione). Le sessioni vengono tracciate tramite l'header Mcp-Session-Id.

Tutti i flag di mcp_server:

Esempio: Configurazione Claude Desktop (claude_desktop_config.json)

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

Riferimento agli Strumenti del Server MCP

Quando agisce come server MCP, PentestAgent espone i seguenti strumenti:

Stato e Configurazione del Server

Esecuzione dei Compiti

Ispezione dei Compiti

Controllo dei Compiti

Gestione degli Strumenti

Cronologia delle Conversazioni

Memoria

Osservabilità

Esempio di Flusso di Lavoro con Compiti Asincroni

Per compiti di ricognizione di lunga durata, usa il pattern asincrono:

# 1. Invia compiti senza bloccare
run_task_async  task="Enumera sottodomini di example.com"  target="example.com"
run_task_async  task="Esegui scansione nmap SYN su example.com"     target="example.com"

# 2. Blocca fino al completamento di entrambi (massimo 5 minuti)
await_tasks  task_ids=["<id1>", "<id2>"]  timeout_seconds=300

# 3. Recupera risultati completi
get_task_result  task_id="<id1>"
get_task_result  task_id="<id2>"

Gestione degli Strumenti tramite CLI

pentestagent tools list         # Elenca tutti gli strumenti
pentestagent tools info <nome>  # Mostra dettagli dello strumento
pentestagent mcp list           # Elenca i server MCP
pentestagent mcp add <nome> <comando> [args...]  # Aggiungi server MCP
pentestagent mcp test <nome>    # Testa connessione MCP

Controlli della Cronologia delle Conversazioni

Ogni messaggio utente nella TUI espone due pulsanti di azione inline: rewind e fork.

Rewind

Clicca rewind su qualsiasi messaggio utente per troncare la conversazione fino a prima di quel messaggio — sia nell'interfaccia che nella cronologia in memoria dell'agente. Usalo per riprovare una query da zero senza salvare il percorso scartato.

Fork

Clicca >> fork su qualsiasi messaggio utente per diramare la conversazione da quel punto:

1. La conversazione corrente completa viene salvata nell'archivio conversazioni e viene mostrato un breve ID snapshot.
2. La conversazione viene quindi troncata fino a prima del messaggio selezionato (come per rewind).

Questo ti permette di provare un approccio alternativo da qualsiasi punto mantenendo il thread originale recuperabile tramite /conversations.

Cronologia Conversazioni

PentestAgent persiste automaticamente ogni conversazione in modo che tu possa rivedere, confrontare e ripristinare sessioni passate.

Salvataggio automatico avviene dopo ogni compito /assist, /agent, /crew e /interact, e prima di /clear. Vengono mantenute fino a 20 conversazioni; quelle più vecchie vengono eliminate automaticamente.

Posizione di archiviazione: workspaces/<attivo>/memory/conversations/ quando un workspace è attivo, o conversations/ nella root del progetto altrimenti. Ogni conversazione è un file JSON.

Sfoglia e ripristina con /conversations:

Il comando /conversations apre un modale a pannello diviso all'interno della TUI:

• Pannello sinistro — elenco delle conversazioni salvate con titolo e data.
• Pannello destro — anteprima dei metadati più i primi 5 messaggi (messaggi utente in blu, risposte agente in verde, chiamate strumenti in giallo, risultati strumenti in grigio). Un conteggio mostra quanti messaggi aggiuntivi esistono.

Seleziona una conversazione e premi Restore per ricaricarla nella sessione corrente, o Close per chiudere il modale.

Conoscenza

• RAG: Posiziona metodologie, CVE o wordlist in pentestagent/knowledge/sources/ per l'iniezione automatica di contesto.
• Note: Gli agenti salvano i risultati in loot/notes.json con categorie (credential, vulnerability, finding, artifact). Le note persistono tra le sessioni e vengono iniettate nel contesto dell'agente.
• Shadow Graph: In modalità Crew, l'orchestratore costruisce un grafo di conoscenza dalle note per derivare informazioni strategiche (es. "Abbiamo credenziali per l'host X").

Struttura del Progetto

pentestagent/
  agents/         # Implementazioni degli agenti
  config/         # Impostazioni e costanti
  interface/      # TUI e CLI
  knowledge/      # Sistema RAG e shadow graph
  llm/            # Wrapper LiteLLM
  mcp/            # Configurazioni client e server MCP
  playbooks/      # Playbook di attacco
  runtime/        # Ambiente di esecuzione
  tools/          # Strumenti integrati

Sviluppo

pip install -e ".[dev]"
pytest                       # Esegui test
pytest --cov=pentestagent    # Con copertura
black pentestagent           # Formatta
ruff check pentestagent      # Lint
## Aspetti Legali

Utilizza solo contro sistemi per i quali hai esplicita autorizzazione al test. L'accesso non autorizzato è illegale.

## Licenza

MIT