Server MCP per test di penetrazione basato sull'IA
"Nella mitologia giapponese, il Tengu è un feroce spirito della montagna — maestro stratega, guerriero e addestratore di samurai. In cybersecurity, ti guida attraverso ogni fase della caccia."
Dalla ricognizione al report — pentesting assistito da IA in un unico comando.
Tengu è un server MCP che trasforma Claude in un co-pilota per penetration testing. Orchestra 80 strumenti di sicurezza — da Nmap a Metasploit — con controlli di sicurezza integrati, logging di audit e report professionali.
Usa Claude come un co-pilota interattivo per pentest — tu dirigi l'engagement, Claude sceglie gli strumenti giusti e li collega automaticamente.
git clone https://github.com/rfunix/tengu.git && cd tengu make docker-build make docker-up
Collega Claude Code al server in esecuzione:```bash
claude mcp add --transport sse tengu http://localhost:8000/sse
Then ask Claude: Do a full pentest on http://192.168.1.100
Claude concatena gli strumenti automaticamente: validate_target → whatweb → nmap → nikto →
nuclei → sqlmap → correlate_findings → generate_report
| Comando | Cosa avvia |
|---|
Scansiona target personalizzati senza modificare i file:```bash TENGU_ALLOWED_HOSTS="192.168.1.0/24,10.0.0.0/8" make docker-up
### Livelli delle Immagini
Scegli la dimensione giusta per il tuo caso d'uso:
| Tier | Dimensione | MCP Tools | Caso d'uso |
|------|------------|-----------|------------|
| `minimal` | ~480MB | 17 | Analisi leggera, ricerca CVE, reporting |
| `core` | ~7GB | 47 | Set completo di strumenti per pentest (predefinito) |
| `full` | ~8GB | 80 | Tutto + AD, wireless, stealth/OPSEC |```bash
TENGU_TIER=minimal make docker-build # lightweight
TENGU_TIER=core make docker-build # default
TENGU_TIER=full make docker-build # everything
Tutti i livelli includono tutti i 35 prompt e 20 risorse — solo gli strumenti binari differiscono.
Prerequisiti: Python 3.12+, uv, Kali Linux (consigliato)```bash
git clone https://github.com/rfunix/tengu.git && cd tengu
uv sync
make install-tools
uv run tengu
Collega Claude Code:```bash
claude mcp add --scope user tengu -- uv run --directory /path/to/tengu tengu
Configura i target consentiti in tengu.toml:```toml
[targets]
allowed_hosts = ["192.168.1.0/24", "example.com"]
Per Claude Desktop, configurazione remota VM/SSE e configurazioni avanzate, consulta [docs/deployment-guide.md](https://github.com/rfunix/tengu/blob/HEAD/docs/deployment-guide.md).
</details>
### Riferimento configurazione```toml
[targets]
# REQUIRED: Only these hosts will be scanned
allowed_hosts = ["192.168.1.0/24", "example.com"]
blocked_hosts = [] # Always blocked, even if in allowed_hosts
[stealth]
enabled = false # Route traffic through Tor/proxy
[stealth.proxy]
enabled = false
type = "socks5h"
host = "127.0.0.1"
port = 9050
[osint]
shodan_api_key = "" # Required for shodan_lookup
[tools.defaults]
scan_timeout = 300 # seconds
make docker-up | Server Tengu MCP (:8000) |
make docker-lab | + Juice Shop, DVWA (target di pratica sicuri) |
make docker-pentest | + Metasploit, OWASP ZAP (target reali) |
make docker-full | + Metasploit, ZAP e target di laboratorio |
Vedi docs/configuration-reference.md per il riferimento completo.
Esegui un pentest completamente autonomo senza invocazione manuale degli strumenti. L'agente utilizza Claude come cervello strategico e Tengu come set di strumenti di esecuzione, seguendo la metodologia PTES dalla ricognizione alla reportistica.
cp .env.example .env
**Target di laboratorio (Juice Shop, DVWA):**```bash
make docker-lab
make docker-agent # default model (sonnet)
make docker-agent-haiku # cheaper — claude-haiku-4-5, max_tokens=1024
make docker-agent-sonnet # balanced — claude-sonnet-4-6, max_tokens=4096
Pentest reali (Tengu + MSF + ZAP, nessun contenitore di laboratorio):```bash make docker-pentest make docker-agent
**Visualizza i report nel browser:**```bash
make docker-report-view # http://localhost:8888 — styled HTML, all reports
make docker-report-browse # same, auto-opens browser
REPORT_PORT=9999 make docker-report-view # custom port
Senza Docker:```bash uv sync --extra agent python autonomous_tengu.py 192.168.1.100 --scope 192.168.1.0/24 --type blackbox
python autonomous_tengu.py 192.168.1.100 --model claude-haiku-4-5 --max-tokens 1024 --timeout 30
**Controllo dei costi** — tre variabili d'ambiente / flag CLI:
| Flag | Variabile d'ambiente | Predefinito |
|---|---|---|
| `--model` | `TENGU_AGENT_MODEL` | `claude-sonnet-4-6` |
| `--max-tokens` | `TENGU_AGENT_MAX_TOKENS` | `2048` |
| `--timeout` | `TENGU_AGENT_TIMEOUT` | `60` (minuti, `0`=illimitato) |
### Come Funziona```
START → initializer → strategist ─┬─→ executor → analyst ─┬─→ strategist (loop)
│ └─→ reporter → END
├─→ human_gate → executor
└─→ reporter → END
Comportamenti chiave:
msf_run_module, hydra_attack, impacket_kerberoast, sqlmap_scan con livello≥3)--max-iterationscorrelate_findings + score_risk + generate_report| Fase | Nome | Cosa fa Tengu | Strumenti chiave |
|---|---|---|---|
| 1 | Pre-Impegno | validate_target conferma l'ambito, check_tools verifica la prontezza | validate_target, check_tools |
| 2 | Raccolta Intelligence | OSINT, ricognizione DNS, enumerazione sottodomini, fingerprinting tecnologico | nmap, subfinder, amass, shodan, whatweb |
| 3 | Modellazione delle Minacce | Claude analizza le intelligence raccolte, prioritizza la superficie d'attacco, costruisce scenari di minaccia | (Guidato da IA — nessuno strumento esterno) |
| 4 | Analisi delle Vulnerabilità | Scansione template, test applicazioni web, analisi SSL/TLS, fuzzing parametri | nuclei, nikto, ffuf, sqlmap, testssl |
| 5 | Sfruttamento | Sfruttamento controllato di vulnerabilità confermate con human-in-the-loop | msf_run_module, sqlmap, hydra, searchsploit |
| 6 | Post-Sfruttamento | Raccolta credenziali, valutazione movimento laterale, escalation privilegi | impacket_kerberoast, nxc_enum, enum4linux |
| 7 | Reportistica | Correla tutti i reperti, calcola punteggi di rischio, genera report professionale | correlate_findings, score_risk, generate_report |
minimal(17 strumenti, ~480MB) ·core(47 strumenti, ~7GB, predefinito) ·full(80 strumenti, ~8GB) Crea con:TENGU_TIER=<tier> make docker-build. Tutti i livelli includono tutti i 35 prompt e 20 risorse.
| Categoria | Strumenti | Conteggio |
|---|---|---|
| Ricognizione | Nmap, Masscan, Amass, Subfinder, Gowitness, HTTrack, Katana, httpx, SNMPwalk, RustScan | 10 |
| Scansione Web | Nikto, Nuclei, FFUF, Gobuster, WPScan, Feroxbuster, OWASP ZAP, wafw00f | 8 |
| SSL / TLS | sslyze, testssl.sh, Analisi header HTTP, tester CORS | 4 |
| DNS | DNS Enumerate, DNSRecon, Subjack, WHOIS | 4 |
| OSINT | theHarvester, Shodan, WhatWeb, DNStwist | 4 |
| Test di Iniezione | SQLMap, Dalfox (XSS), Commix, CRLFuzz, GraphQL Security Check, Arjun | 6 |
| Forza Bruta | Hydra, John the Ripper, Hashcat, CeWL | 4 |
| Sfruttamento | Metasploit (ricerca, info, esecuzione, sessioni, cmd), SearchSploit | 6 |
| Ingegneria Sociale | Raccolta credenziali SET, attacco QR code, generatore payload | 3 |
| Segreti e Codice | TruffleHog, Gitleaks | 2 |
| Container e Cloud | Trivy, Checkov, ScoutSuite, Prowler | 4 |
| Active Directory | NetExec, Enum4linux, Impacket (Kerberoast, secretsdump, psexec, wmiexec, smbclient), BloodHound, Responder, SMBMap | 10 |
| Wireless | aircrack-ng / airodump-ng | 1 |
| Anonimato e Stealth | Controllo/rotazione Tor, controllo proxy, rotazione identità | 5 |
| Analisi e Reportistica | Correlazione reperti, punteggio rischio CVSS, generazione report | 3 |
| Intelligence CVE | Ricerca CVE (NVD), ricerca CVE per parola chiave/prodotto/gravità | 2 |
| Utilità | Controllo strumenti, validatore target | 2 |
| Strumento | Descrizione |
|---|---|
nmap_scan | Scansione porte e rilevamento servizi/OS |
masscan_scan | Scanner porte ad alta velocità per reti grandi |
subfinder_enum | Enumerazione passiva di sottodomini |
amass_enum | Mappatura superficie d'attacco e brute-force DNS |
dnsrecon_scan | Ricognizione DNS (trasferimento zona, brute-force, PTR) |
dns_enumerate | Enumerazione record DNS (A, MX, NS, TXT, SOA…) |
whois_lookup | Ricerca WHOIS di domini e IP |
subjack_check | Rilevamento takeover sottodominio |
gowitness_screenshot | Acquisizione schermate web per documentazione |
httrack_mirror | Mirror completo di sito web per analisi offline e forense |
katana_crawl | Web crawler veloce per scoperta link e mappatura endpoint |
httpx_probe | Sonda HTTP — codici di stato, stack tecnologico, redirect |
snmpwalk_scan | Enumerazione SNMP e walking MIB |
rustscan_scan | Scansione porte ultra-veloce (trova porte aperte per Nmap successivo) |
| Strumento | Descrizione |
|---|---|
theharvester_scan | Enumerazione email, sottodomini e host da fonti pubbliche |
| Strumento | Descrizione |
|---|---|
set_credential_harvester | Clona un sito web e cattura le credenziali inviate (simulazioni phishing autorizzate) |
set_qrcode_attack | Genera codice QR che punta a un URL per valutazioni di ingegneria sociale fisica |
set_payload_generator | Genera payload di ingegneria sociale (PowerShell, HTA) per campagne autorizzate |
| Strumento | Descrizione |
|---|---|
hydra_attack | Brute-force login di rete (SSH, FTP, HTTP, SMB…) |
| Strumento | Descrizione |
|---|---|
zap_spider | Web spider OWASP ZAP |
zap_active_scan | Scansione vulnerabilità attiva OWASP ZAP |
zap_get_alerts | Recupera risultati scansione ZAP |
| Strumento | Descrizione |
|---|---|
trufflehog_scan | Rilevamento segreti divulgati in repository git |
gitleaks_scan | Scansione credenziali nella cronologia git |
| Strumento | Descrizione |
|---|---|
trivy_scan | Scansione vulnerabilità per immagini Docker, IaC e SBOM |
| Strumento | Descrizione |
|---|---|
scoutsuite_scan | Audit sicurezza cloud (AWS, Azure, GCP) |
prowler_scan | Audit best practice e conformità sicurezza AWS/GCP/Azure |
| Strumento | Descrizione |
|---|---|
aircrack_scan | Scansione passiva reti wireless (airodump-ng) |
| Strumento | Descrizione |
|---|---|
checkov_scan | Scansione misconfigurazione IaC (Terraform, K8s, Dockerfile) |
Template di workflow predefiniti che guidano Claude attraverso impegni completi.
| Categoria | Prompt |
|---|---|
| Workflow pentest | full_pentest, quick_recon, web_app_assessment |
| Valutazione vulnerabilità | assess_injection, assess_access_control, assess_crypto, assess_misconfig |
| OSINT | osint_investigation |
| Report | executive_report, technical_report, full_pentest_report, finding_detail, risk_matrix, remediation_plan, retest_report, save_report |
| Stealth/OPSEC | stealth_assessment, opsec_checklist |
| Specializzati | ad_assessment, api_security_assessment, container_assessment, cloud_assessment, wireless_assessment, bug_bounty_workflow, compliance_assessment |
| Azioni rapide | explore_url, map_network, hunt_subdomains, find_vulns, find_secrets, go_stealth, crack_wifi, pwn_target, msf_exploit_workflow |
| Ingegneria Sociale | social_engineering_assessment |
Dati di riferimento statici caricati da Claude durante gli impegni.
| URI | Contenuto |
|---|---|
owasp://top10/2025 | Elenco completo OWASP Top 10:2025 |
owasp://top10/2025/{A01..A10} | Dettagli per categoria + lista di controllo test |
owasp://api-security/top10 | OWASP API Security Top 10 (2023) |
owasp://api-security/top10/{API1..API10} | Dettagli per categoria |
ptes://phases | Panoramica metodologia PTES a 7 fasi |
ptes://phase/{1..7} | Dettagli fase (obiettivi, strumenti, deliverable) |
checklist://web-application | Lista di controllo pentest web app (OWASP Testing Guide) |
checklist://api | Lista di controllo pentest API |
checklist://network | Lista di controllo infrastruttura di rete |
mitre://attack/tactics | Tattiche e tecniche MITRE ATT&CK Enterprise |
mitre://attack/technique/{T1xxx} | Dettaglio tecnica per ID |
creds://defaults/{product} | Database credenziali predefinite |
payloads://{type} | Liste payload curate per tipo (xss, sqli, lfi, ssti, ecc.) |
stealth://techniques | Guida di riferimento per tecniche di sicurezza operativa |
stealth://proxy-guide | Guida passo-passo configurazione proxy e Tor |
tools://catalog | Stato disponibilità strumenti in tempo reale |
tools://{tool}/usage | Guida all'uso per nmap, nuclei, sqlmap, metasploit, trivy, amass |
prompts://list | Elenco di tutti i prompt disponibili con descrizioni |
prompts://category/{category} | Prompt filtrati per categoria |
┌─────────────┐ MCP ┌─────────────────┐ subprocess ┌─────────────────┐ │ Claude │◄────────────►│ Tengu │─────────────────►│ Nmap, SQLMap, │ │ (Desktop / │ stdio/SSE │ MCP Server │ (never shell=T) │ Metasploit... │ │ Code) │ │ │ └─────────────────┘ └─────────────┘ └────────┬─────────┘ │ Every tool call passes through: │ ┌────────▼─────────┐ │ Safety Pipeline │ │ │ │ 1. sanitizer │ ← strip metacharacters, validate format │ 2. allowlist │ ← check target against tengu.toml │ 3. rate_limiter │ ← sliding window + concurrent slots │ 4. audit logger │ ← JSON log to ./logs/tengu-audit.log └──────────────────┘
---
## File di Configurazione
Tengu utilizza tre file di configurazione. Modificare quello sbagliato è la fonte più comune
di confusione quando si passa tra flussi di lavoro locali e Docker.
| File | Quando usarlo | Cosa controlla |
|------|---------------|----------------|
| `tengu.toml` (root) | Esecuzione locale: `uv run tengu`, `uv run python autonomous_tengu.py` | Configurazione server MCP: `allowed_hosts`, percorsi degli strumenti, limiti di richiesta, stealth |
| `docker/tengu.toml` | Esecuzione tramite Docker: `make docker-up`, `make docker-agent` | Stesse impostazioni del root, ma preconfigurate per il networking Docker (`172.16.0.0/12`, alias DNS dei servizi). Incorporato nell'immagine al momento della build — **necessaria ricostruzione** dopo le modifiche (`make docker-rebuild-tengu`) |
| `.env` | Sia locale che Docker | Segreti e variabili di runtime: `ANTHROPIC_API_KEY`, `TENGU_AGENT_TARGET`, `TENGU_AGENT_MODEL`, `TENGU_AGENT_MAX_TOKENS`, ecc. Letti da `docker compose` e `load_dotenv()` |
| `.env.example` | Solo di riferimento | Template che elenca tutte le variabili d'ambiente disponibili |
**Configurazione rapida per la modalità copilota (locale):** modifica `tengu.toml` nella root del progetto —
aggiungi il tuo target a `[targets] allowed_hosts`.
**Configurazione rapida per la modalità agente (Docker):** modifica `docker/tengu.toml`, poi esegui
`make docker-rebuild-tengu` prima di `make docker-agent`.
> **Errore comune:** se le scansioni falliscono con `TargetNotAllowedError` all'interno di Docker, probabilmente
> hai modificato `tengu.toml` (root) invece di `docker/tengu.toml`. Docker usa la sua copia incorporata nell'immagine.
> Dopo la modifica, esegui `make docker-rebuild-tengu`.
---
## Sicurezza per Progettazione
Tengu è costruito come un **moltiplicatore di forza per pentester umani**, non uno strumento di attacco autonomo.
| Controllo | Descrizione |
|-----------|-------------|
| **Lista di Approvazione dei Target** | Vengono scansionati solo i target pre-approvati in `tengu.toml` |
| **Sanificazione degli Input** | Tutti gli input vengono validati secondo pattern rigorosi prima di raggiungere qualsiasi strumento |
| **Limitazione della Frequenza** | Finestra scorrevole + limiti di slot concorrenti prevengono il DoS accidentale |
| **Registrazione di Audit** | Ogni invocazione di strumento viene registrata in `./logs/tengu-audit.log` in formato JSON |
| **Uomo nel Ciclo** | `msf_run_module`, `hydra_attack` e `impacket_kerberoast` richiedono conferma esplicita |
| **Mai shell=True — mai** | Tutte le chiamate ai sottoprocessi usano `asyncio.create_subprocess_exec` |
---
## Sviluppo```bash
make install-dev # Install Python deps + dev extras
make test # Run unit + security tests
make lint # ruff check
make typecheck # mypy strict
make check # lint + typecheck
make coverage # pytest --cov
make inspect # Open MCP Inspector
make doctor # Check which pentest tools are installed
Tengu ha oltre 2643 test che coprono logica unitaria, sicurezza (command injection, validazione input) e scenari di integrazione. Vedi CLAUDE.md per la guida completa per i collaboratori.
Tengu è progettato esclusivamente per test di sicurezza autorizzati. Scansiona solo sistemi di tua proprietà o per cui hai ricevuto esplicita autorizzazione scritta. La scansione non autorizzata è illegale nella maggior parte delle giurisdizioni. Gli autori non si assumono alcuna responsabilità per un uso improprio.
| Strumento | Descrizione |
|---|
nuclei_scan | Scanner vulnerabilità basato su template (CVE, misconfigurazioni) |
nikto_scan | Scanner misconfigurazioni server web e software obsoleto |
ffuf_fuzz | Fuzzing di directory, parametri e vhost |
gobuster_scan | Brute-force di directory, DNS e vhost |
wpscan_scan | Scanner vulnerabilità WordPress |
testssl_check | Analisi completa configurazione SSL/TLS |
analyze_headers | Analisi e valutazione header di sicurezza HTTP |
test_cors | Rilevamento misconfigurazione CORS |
ssl_tls_check | Controllo certificato e cifratura SSL/TLS (sslyze) |
wafw00f_scan | Rilevamento e fingerprinting Web Application Firewall |
feroxbuster_scan | Scoperta ricorsiva veloce di contenuti tramite brute-force |
shodan_lookup |
| Ricerca host e asset Shodan |
whatweb_scan | Fingerprinting tecnologia web (CMS, WAF, framework) |
dnstwist_scan | Rilevamento permutazioni dominio e typosquatting |
| Strumento | Descrizione |
|---|
sqlmap_scan | Rilevamento e sfruttamento automatico SQL injection |
xss_scan | Rilevamento XSS tramite Dalfox |
commix_scan | Rilevamento e sfruttamento automatico command injection |
crlfuzz_scan | Fuzzing CRLF injection per vulnerabilità di iniezione header |
graphql_security_check | GraphQL introspection, batching, limiti profondità, suggerimenti campo |
arjun_discover | Scoperta parametri HTTP nascosti |
| Strumento | Descrizione |
|---|
msf_search | Cerca moduli Metasploit |
msf_module_info | Ottieni informazioni dettagliate modulo Metasploit |
msf_run_module | Esegui un modulo Metasploit (richiede conferma esplicita) |
msf_sessions_list | Elenca sessioni Metasploit attive |
msf_session_cmd | Esegui un comando su una sessione attiva (shell/Meterpreter) |
searchsploit_query | Cerca nel database offline Exploit-DB |
hash_crack| Cracking dizionario hash (Hashcat / John the Ripper) |
hash_identify | Identificazione tipo hash |
cewl_generate | Generazione wordlist personalizzata da un sito web target |
| Strumento | Descrizione |
|---|
enum4linux_scan | Enumerazione SMB/NetBIOS |
nxc_enum | Enumerazione Active Directory tramite NetExec |
impacket_kerberoast | Kerberoasting con Impacket GetUserSPNs |
impacket_secretsdump | Dump remoto segreti SAM/LSA/NTDS tramite Impacket |
impacket_psexec | Esecuzione comandi remota via SMB (stile PsExec) |
impacket_wmiexec | Esecuzione comandi remota via WMI |
impacket_smbclient | Enumerazione condivisioni SMB e accesso file |
bloodhound_collect | Raccolta dati AD BloodHound (SharpHound/bloodhound-python) |
responder_capture | Avvelenamento LLMNR/NBT-NS/MDNS per cattura credenziali |
smbmap_scan | Enumerazione condivisioni SMB e test accesso |
| Strumento | Descrizione |
|---|
tor_check | Verifica connettività Tor e IP nodo di uscita |
tor_new_identity | Richiedi nuovo circuito Tor (NEWNYM) |
check_anonymity | Controlla IP esposto, perdite DNS e livello di anonimato |
proxy_check | Valida latenza proxy, IP di uscita e tipo di anonimato |
rotate_identity | Ruota circuito Tor e User-Agent simultaneamente |
| Strumento | Descrizione |
|---|
check_tools | Verifica quali strumenti esterni sono installati |
validate_target | Valida target rispetto alla lista consentita |
correlate_findings | Correla reperti tra più scansioni |
score_risk | Punteggio rischio basato su CVSS |
cve_lookup | Dettagli CVE da NVD (CVSS, CWE, prodotti affetti) |
cve_search | Cerca CVE per parola chiave, prodotto o gravità |
generate_report | Genera report pentest Markdown/HTML/PDF |