pentest-copilot

Agente di penetration testing basato sull'IA che si connette a una macchina Kali, esegue autonomamente strumenti di sicurezza, analizza i risultati e itera attraverso flussi di lavoro basati su browser.

Guardalo su YouTube

Star History

Cosa Fa

• Esecuzione agentica - l'IA esegue comandi direttamente sull'attack box, legge l'output, decide i passi successivi e ripete. Fino a 25 iterazioni per turno, senza necessità di intervento manuale.
• 16 strumenti dell'agente - bash, script Python, installazione di strumenti, gestione della shell, ricerca su Google, generazione di subagent, Burp Suite (cronologia del proxy, Repeater, Intruder, Collaborator) e automazione del browser.
• Oltre 100 capacità - registro curato di strumenti di sicurezza e pacchetti Python in 7 categorie (network, rev, pwn, crypto, forensics, stego, core). Seleziona ciò che ti serve, l'agente installa il resto.
• Integrazione con Burp Suite - visualizzatore della cronologia del proxy, invio di richieste a Repeater/Intruder, Collaborator per test out-of-band. Tutto accessibile all'agente e tramite l'interfaccia utente.
• Agente browser - automazione reale del browser tramite Magnitude. Testa flussi di login, compila form, interagisci con applicazioni ricche di JavaScript. Facoltativamente, instrada il traffico attraverso Burp. In modalità Docker, osserva il browser tramite lo stream VNC integrato; in modalità developer, il browser si apre sul tuo desktop locale.
• Gestione VPN - carica bundle .ovpn/.conf con certificati, chiavi o credenziali referenziate e connettiti/disconnettiti dal browser. Sono supportate più connessioni simultanee.
• Parallelismo dei subagent - genera agenti in background per eseguire attività in modo concorrente (ad esempio directory brute-force + enumerazione di sottodomini contemporaneamente).
• Controlli di sicurezza - i comandi pericolosi (eliminazioni ricorsive, scritture su dispositivi, fork bomb) richiedono approvazione esplicita, anche in modalità auto-run.
• Porta il tuo modello - OpenAI, Anthropic (API key o OAuth), Google, Mistral o qualsiasi endpoint compatibile con OpenAI.
• Usa gli abbonamenti locali esistenti - Pentest Copilot può utilizzare una Codex CLI autenticata in modalità Docker o host, e Claude Code in modalità host/developer, come normali provider di inferenza mantenendo il proprio ciclo di strumenti e consenso.

Avvio Rapido

Apri http://localhost:3000, registrati e avvia una sessione.

run.sh attende che frontend, backend, MongoDB e Redis siano pronti prima di segnalare il successo. Se l'avvio fallisce, stampa lo stato dei container interessati e i log recenti. Configura e assegna un modello in Settings -> Models dopo il primo avvio.

Su Windows, esegui Pentest Copilot all'interno di WSL2 con l'integrazione WSL di Docker Desktop abilitata. Gli host nativi PowerShell e Windows SSH non sono supportati perché i comandi del workspace richiedono una shell POSIX. Per permessi dei file e prestazioni affidabili, clona il repository nel filesystem WSL, non sotto /mnt/c.

Inferenza tramite abbonamento Codex e Claude

Settings -> Models rileva le CLI Codex e Claude Code autenticate. Autentica una volta sulla macchina che esegue la CLI:

Poi seleziona Use Codex o Use Claude Code. La CLI ufficiale gestisce login, refresh e gestione dei diritti di abbonamento; Pentest Copilot non copia né riproduce i token OAuth. I trasporti tramite abbonamento ricevono la stessa cronologia di conversazione e gli stessi schemi di funzione dei provider API e restituiscono lo stesso contratto di chiamata assistant/tool, quindi Pentest Copilot continua a eseguire strumenti e controlli di consenso.

Il backend Docker include la Codex CLI per Linux e monta solo il file ~/.codex/auth.json basato su file dell'host, seguendo il flusso documentato da Codex per il trasferimento del login headless/Docker. Imposta CODEX_AUTH_FILE prima di docker compose up se il tuo file di credenziali si trova altrove. La CLI potrebbe aggiornare quel file durante il normale utilizzo; non committarlo né condividerlo mai. Le credenziali solo Keychain dell'host e Claude Code rimangono disponibili solo in modalità developer/host finché non viene configurato un bridge di inferenza sull'host. L'uso dell'abbonamento Claude è controllo locale della CLI e deve essere conforme ai termini vigenti di Anthropic per prodotti e abbonamenti di terze parti.

Le famiglie di modelli first-class attuali includono GPT-5.6 Sol/Terra/Luna, Claude Fable/Opus/Sonnet 5 e Kimi K3 (API Moonshot diretta o OpenRouter).

Profili SSH con ambito workspace

In modalità Docker, Pentest Copilot monta le directory ~/.ssh e ~/keys dell'host in sola lettura. Ogni workspace può selezionare un alias Host concreto da ~/.ssh/config in Connection. Ogni sessione in quel workspace usa lo stesso host e la stessa cartella di lavoro senza copiare chiavi private in MongoDB. Imposta HOST_SSH_DIR o HOST_SSH_KEYS_DIR prima di avviare Docker quando quelle directory si trovano altrove.

Usa alias con nome invece di voci solo wildcard:

run.sh gestisce la generazione dei file di configurazione, le build Docker e l'orchestrazione dei container. Usa ./run.sh start -q per riutilizzare la modalità di avvio precedente e saltare i prompt nelle esecuzioni successive.

Per la matrice completa di scenari relativi a OS, Docker, SSH, VPN, proxy, permessi, ripristino e deployment, consulta Setup and Troubleshooting.

Accesso MCP

Pentest Copilot può esporre il proprio control plane locale tramite MCP per client come Claude Code o Codex. Apri Settings -> MCP Access per copiare l'endpoint MCP locale e il bearer token.

Tratta il token come accesso admin locale: può eseguire comandi sull'exploit box configurato, gestire Burp, l'automazione del browser e i flussi VPN, leggere artefatti, scrivere finding e aggiornare la configurazione locale di Pentest Copilot. Le azioni MCP legate a un engagement vengono registrate in quella sessione, così rimangono visibili nell'interfaccia di Pentest Copilot.

Dopo aver copiato l'endpoint e il token, puoi fare uno smoke test della connessione MCP:

Requisiti di Sistema

La modalità Docker associa le porte dell'interfaccia e dei servizi a 127.0.0.1 per impostazione predefinita. Non esporre lo stack a una LAN o a Internet senza TLS, autenticazione e una configurazione deliberata di reverse proxy. In modalità Kali integrata, mantieni i file durevoli del workspace sotto /kali-data; i file altrove nel container Kali vengono rimossi quando il container viene ricreato.

Documentazione

La guida Setup and Troubleshooting nel repository è la fonte autorevole per installazione, configurazione, ripristino e deployment. La Wiki contiene riferimenti aggiuntivi alle funzionalità e potrebbe essere indietro rispetto alla release corrente:

• Getting Started - panoramica del progetto
• Architecture - progettazione del sistema, loop dell'agente, subagent
• Usage - workflow, modello di consenso, interfaccia chat
• Features - panoramica completa delle funzionalità
• Settings - modelli, SSH, VNC, Burp, Magnitude
• Capabilities - registro degli strumenti e bucket
• Agent Tools - tutti i 16 strumenti e il comportamento del consenso
• Burp Suite Integration - configurazione e utilizzo
• Browser Agent - configurazione di Magnitude
• VPN Management - gestione dei profili
• Slash Commands - utilità di sessione
• Changelog - novità

Sviluppo Locale

Poi in terminali separati:

Per la configurazione di sviluppo e la risoluzione dei problemi, consulta la guida Setup and Troubleshooting.

Autori

• Dhruva Goyal - [email protected] | LinkedIn | GitHub | X
• Aditya Peela - [email protected] | LinkedIn | GitHub | X
• Sitaraman Subramanian - [email protected] | LinkedIn | GitHub | X

Citazioni

Contribuire

Contributi benvenuti. Consulta la Guida alla Contribuzione e il Codice di Condotta.

Licenza

MIT License

Disclaimer

Pentest Copilot è destinato esclusivamente a test di sicurezza autorizzati. Ottieni sempre un permesso esplicito prima di testare qualsiasi sistema.