tengu - AI-powered penetration testing MCP server

项目说明

Tengu — Pentesting MCP Server

<p align="center">
<img src="assets/Tengu.png" alt="Tengu" width="480"/>
</p>

<p align="center">
<em>"In Japanese mythology, the Tengu is a fierce mountain spirit — master strategist, warrior, and trainer of samurai. In cybersecurity, it guides you through every phase of the hunt."</em>
</p>

<p align="center">
<strong>From recon to report — AI-assisted pentesting in one command.</strong>
</p>

<p align="center">
<a href=" src=" alt="CI"></a>
<a href="LICENSE"><img src=" alt="License"></a>
<a href=" src=" alt="Python"></a>
<a href=" src=" alt="MCP"></a>
<img src=" alt="Tools">
<img src=" alt="">
<img src=" alt="Agent">
</p>

---

Tengu is an MCP server that turns Claude into a penetration testing copilot. It orchestrates 80 security tools — from Nmap to Metasploit — with built-in safety controls, audit logging, and professional reporting.

What is it? An MCP server that connects Claude to industry-standard pentest tools

Why use it? Automates recon and scanning while keeping the human in control of exploits

Who is it for? Pentesters, red teamers, security students, and consulting firms

Key Features

80 Tools — Nmap, Metasploit, SQLMap, Nuclei, Hydra, Burp-compatible ZAP, and more

AI-Orchestrated — Claude decides the next tool based on previous findings

Safety First — Allowlist, rate limiting, audit logs, and human-in-the-loop for destructi

Auto Reports — Correlate findings and generate professional pentest reports (MD/HTML/PDF)

35 Workflows — Pre-built prompts for full pentest, web app, AD, cloud, and more

20 Resources — Built-in OWASP Top 10, MITRE ATT&CK, PTES, and pentest checklists

Stealth Layer — Optional Tor/SOCKS5 proxy routing, UA rotation, and timing jitter

---

MCP Server Mode (Copilot)

Use Claude as an interacti copilot — you direct the engagement, Claude picks the right tools and chains them together automatically.

![Tengu copilot demo]()

Quick Start

Connect Claude Code to the running server:

Then ask Claude: Do a full pentest on

Claude chains tools automatically: → whatweb → nmap → nikto →
nuclei → sqlmap → correlate_findings → generate_report

Docker Profiles

| Command | What it starts |
|---------|----------------|
| make docker-up | Tengu MCP server (:8000) |
| make docker-lab | + Juice Shop, DVWA (safe practice targets) |
| make docker-pentest | + Metasploit, OWASP ZAP (real-world targets) |
| make docker-full | + Metasploit, ZAP, and lab targets |

Scan custom targets without editing files:

Image Tiers

Choose the right size for your use case:

| Tier | Size | MCP Tools | Use case |
|------|------|-----------|----------|
| minimal | ~480MB | 17 | Lightweight analysis, C, reporting |
| core | ~7GB | 47 | Full pentest toolkit (default) |
| full | ~8GB | 80 | E + AD, wireless, stealth/OPSEC |

> All tiers include all 35 prompts and 20 resources — only the binary tools differ.

<details>
<summary>Manual Install (without Docker)</summary>

Prerequisites: Python 3.12+, uv, Kali Linux (recommended)

Connect Claude Code:

Configure allowed targets in tengu.toml:

For Claude Desktop, VM/SSE remote setup, and ad configurations, see docs/deployment-guide.md.

</details>

Configuration Reference

See docs/configuration-reference.md for the full reference.

---

Autonomous Agent Mode

Run a fully autonomous pentest without manual tool in. The agent uses Claude as its strategic brain and Tengu as its execution toolset, following the PTES methodology from recon through reporting.

![Tengu autonomous agent demo]()

Quick Start

Lab targets (Juice Shop, DVWA):

Real-world pentests (Tengu + MSF + ZAP, no lab containers):

View reports in browser:

<p align="center">
<img src="assets/report.png" alt="Tengu report " width="800"/>
</p>

Without Docker:

Cost control — three env vars / CLI flags:

| Flag | Env var | Default |
|---|---|---|
| --model | TENGU_AGENT_MODEL | claude-sonnet-4-6 |
| --max-tokens | TENGU_AGENT_MAX_TOKENS | 2048 |
| --timeout | TENGU_AGENT_TIMEOUT | 60 (minutes, 0=unlimited) |

How It Works

Key behaviors:

Strategist (Claude) reads the current PTES phase and accumulated state to decide each action

Executor calls exactly one Tengu MCP tool per iteration

Analyst (Claude) extracts structured data from tool output and ad phases

Human gate interrupts execution before destructi (msf_run_module, hydra_attack, impacket_kerberoast, sqlmap_scan with level≥3)

Runs until all 7 PTES phases are covered or --max-iterations is reached

Final Reporter calls correlate_findings + score_risk + generate_report

PTES Methodology — 7 Phases

| Phase | Name | What Tengu Does | Key Tools |
|:---:|---|---|---|
| 1 | Pre-Engagement | confirms scope, check_tools readiness | , check_tools |
| 2 | Intelligence Gathering | OSINT, DNS recon, subdomain enumeration, technology fingerprinting | nmap, subfinder, amass, shodan, whatweb |
| 3 | Threat Modeling | Claude analyzes gathered intel, prioritizes attack surface, builds threat scenarios | *(AI-driven — no external tool)* |
| 4 | Analysis | Template scanning, web app testing, SSL/TLS analysis, parameter fuzzing | nuclei, nikto, ffuf, sqlmap, testssl |
| 5 | Exploitation | Controlled exploitation of confirmed with human-in-the-loop | msf_run_module, sqlmap, hydra, searchsploit |
| 6 | Post-Exploitation | Credential har, lateral mo assessment, pri escalation | impacket_kerberoast, nxc_enum, enum4linux |
| 7 | Reporting | Correlate all findings, calculate risk scores, generate professional report | correlate_findings, score_risk, generate_report |

---

Tool Catalog

> minimal (17 tools, ~480MB) · core (47 tools, ~7GB, default) · full (80 tools, ~8GB)
> Build with: TENGU_TIER=<tier> make docker-build. All tiers include all 35 prompts and 20 resources.

| Category | Tools | Count |
|----------|-------|-------|
| Reconnaissance | Nmap, Masscan, Amass, Subfinder, Gowitness, HTTrack, Katana, httpx, SNMPwalk, RustScan | 10 |
| Web Scanning | Nikto, Nuclei, FFUF, Gobuster, WPScan, Feroxbuster, OWASP ZAP, wafw00f | 8 |
| SSL / TLS | sslyze, testssl.sh, HTTP headers analysis, CORS tester | 4 |
| DNS | DNS Enumerate, DNSRecon, Subjack, WHOIS | 4 |
| OSINT | theHar, Shodan, WhatWeb, DNStwist | 4 |
| Injection Testing | SQLMap, Dalfox (XSS), Commix, CRLFuzz, GraphQL Security Check, Arjun | 6 |
| Brute Force | Hydra, John the Ripper, Hashcat, CeWL | 4 |
| Exploitation | Metasploit (search, info, run, sessions, cmd), SearchSploit | 6 |
| Social Engineering | SET credential har, QR code attack, payload generator | 3 |
| Secrets & Code | TruffleHog, Gitleaks | 2 |
| Container & Cloud | Tri, ScoutSuite, Prowler | 4 |
| Acti | NetExec, Enum4linux, Impacket (Kerberoast, secretsdump, psexec, wmiexec, smbclient), BloodHound, Responder, SMBMap | 10 |
| Wireless | aircrack-ng / airodump-ng | 1 |
| Anonymity & Stealth | Tor check/rotate, proxy check, identity rotation | 5 |
| Analysis & Reporting | Finding correlation, CVSS risk scoring, report generation | 3 |
| C | C (NVD), C by keyword/product/se | 2 |
| Utility | Tool checker, target | 2 |

<details>
<summary>Full tool list (80 tools)</summary>

Reconnaissance

| Tool | Description |
|------|-------------|
| nmap_scan | Port scanning and service/OS detection |
| masscan_scan | High-speed port scanner for large networks |
| subfinder_enum | Passi enumeration |
| amass_enum | Attack surface mapping and DNS brute-force |
| dnsrecon_scan | DNS recon (zone transfer, brute-force, PTR) |
| dns_enumerate | DNS record enumeration (A, MX, NS, TXT, SOA…) |
| whois_lookup | WHOIS domain and IP lookup |
| subjack_check | Subdomain takeo |
| gowitness_screenshot | Web screenshot capture for documentation |
| httrack_mirror | Full website mirror for offline analysis and forensics |
| katana_crawl | Fast web crawler for link discovery and endpoint mapping |
| httpx_probe | HTTP probe — status codes, tech stack, redirects |
| snmpwalk_scan | SNMP enumeration and MIB walking |
| rustscan_scan | Ultra-fast port scanning (finds open ports for Nmap follow-up) |

Web Scanning

| Tool | Description |
|------|-------------|
| nuclei_scan | Template-based scanner (CVEs, misconfigs) |
| nikto_scan | Web ser and outdated software scanner |
| ffuf_fuzz | Directory, parameter, and vhost fuzzing |
| gobuster_scan | Directory, DNS, and vhost brute-force |
| wpscan_scan | WordPress scanner |
| testssl_check | Comprehensive SSL/TLS configuration analysis |
| analyze_headers | HTTP security headers analysis and grading |
| test_cors | CORS misconfiguration detection |
| ssl_tls_check | SSL/TLS certificate and cipher check (sslyze) |
| wafw00f_scan | Web Application Firewall detection and fingerprinting |
| feroxbuster_scan | Fast, recursi discovery |

OSINT

| Tool | Description |
|------|-------------|
| thehar | Email, subdomain, and host enumeration from public sources |
| shodan_lookup | Shodan host and asset search |
| whatweb_scan | Web technology fingerprinting (CMS, WAF, frameworks) |
| dnstwist_scan | Domain permutation and typosquatting detection |

Injection Testing

| Tool | Description |
|------|-------------|
| sqlmap_scan | Automated SQL injection detection and exploitation |
| xss_scan | XSS detection |
| commix_scan | Automated command injection detection and exploitation |
| crlfuzz_scan | CRLF injection fuzzing for header injection |
| graphql_security_check | GraphQL introspection, batching, depth limit, field suggestions |
| arjun_discover | Hidden HTTP parameter discovery |

Exploitation

| Tool | Description |
|------|-------------|
| msf_search | Search Metasploit modules |
| msf_module_info | Get detailed Metasploit module information |
| msf_run_module | Execute a Metasploit module (requires explicit confirmation) |
| msf_sessions_list | List acti sessions |
| msf_session_cmd | Execute a command on an acti (shell/Meterpreter) |
| searchsploit_query | Search Exploit-DB offline database |

Social Engineering

| Tool | Description |
|------|-------------|
| set_credential_har | Clone a website and capture submitted credentials (authorized phishing simulations) |
| set_qrcode_attack | Generate QR code pointing to a URL for physical social engineering assessments |
| set_payload_generator | Generate social engineering payloads (PowerShell, HTA) for authorized campaigns |

Brute Force

| Tool | Description |
|------|-------------|
| hydra_attack | Network login brute-force (SSH, FTP, HTTP, SMB…) |
| hash_crack | Dictionary hash cracking (Hashcat / John the Ripper) |
| hash_identify | Hash type identification |
| cewl_generate | Custom wordlist generation from a target website |

Proxy / DAST

| Tool | Description |
|------|-------------|
| zap_spider | OWASP ZAP web spider |
| zap_acti | OWASP ZAP acti scan |
| zap_get_alerts | Retrieve ZAP scan findings |

Secrets & Code Analysis

| Tool | Description |
|------|-------------|
| trufflehog_scan | Leaked secrets detection in git repositories |
| gitleaks_scan | Credential scanning in git history |

Container Security

| Tool | Description |
|------|-------------|
| tri | scanning for Docker images, IaC, and SBOM |

Cloud Security

| Tool | Description |
|------|-------------|
| scoutsuite_scan | Cloud security audit (AWS, Azure, GCP) |
| prowler_scan | AWS/GCP/Azure security best practices and compliance audit |

Acti

| Tool | Description |
|------|-------------|
| enum4linux_scan | SMB/NetBIOS enumeration |
| nxc_enum | Acti enumeration |
| impacket_kerberoast | Kerberoasting with Impacket GetUserSPNs |
| impacket_secretsdump | Remote SAM/LSA/NTDS secrets dump |
| impacket_psexec | Remote command execution via SMB (PsExec-style) |
| impacket_wmiexec | Remote command execution via WMI |
| impacket_smbclient | SMB share enumeration and file access |
| bloodhound_collect | BloodHound AD data collection (SharpHound/bloodhound-python) |
| responder_capture | LLMNR/NBT-NS/MDNS poisoning for credential capture |
| smbmap_scan | SMB share enumeration and access testing |

Wireless

| Tool | Description |
|------|-------------|
| aircrack_scan | Passi network scan (airodump-ng) |

IaC Security

| Tool | Description |
|------|-------------|
| checko | IaC misconfiguration scan (Terraform, K8s, Dockerfile) |

Stealth / OPSEC

| Tool | Description |
|------|-------------|
| tor_check | Tor connectivity and exit node IP |
| tor_new_identity | Request new Tor circuit (NEWNYM) |
| check_anonymity | Check exposed IP, DNS leaks, and anonymity level |
| proxy_check | proxy latency, exit IP, and anonymity type |
| rotate_identity | Rotate Tor circuit and User-Agent simultaneously |

Analysis & Utility

| Tool | Description |
|------|-------------|
| check_tools | which external tools are installed |
| | target against allowlist |
| correlate_findings | Correlate findings across multiple scans |
| score_risk | C risk scoring |
| c | C from NVD (CVSS, CWE, affected products) |
| c | Search CVEs by keyword, product, or se |
| generate_report | Generate Markdown/HTML/PDF pentest report |

</details>

---

Workflows & Prompts (35)

Pre-built workflow templates that guide Claude through complete engagements.

| Category | Prompts |
|----------|---------|
| Pentest workflows | full_pentest, quick_recon, web_app_assessment |
| assessment | assess_injection, assess_access_control, assess_crypto, assess_misconfig |
| OSINT | osint_in |
| Reports | executi, technical_report, full_pentest_report, finding_detail, risk_matrix, remediation_plan, retest_report, sa |
| Stealth/OPSEC | stealth_assessment, opsec_checklist |
| Specialized | ad_assessment, api_security_assessment, container_assessment, cloud_assessment, wireless_assessment, bug_bounty_workflow, compliance_assessment |
| Quick actions | explore_url, map_network, hunt_subdomains, find_vulns, find_secrets, go_stealth, crack_wifi, pwn_target, msf_exploit_workflow |
| Social Engineering | social_engineering_assessment |

---

Built-in Resources (20)

Static reference data loaded by Claude during engagements.

| URI | Content |
|-----|---------|
| owasp://top10/2025 | OWASP Top 10:2025 full list |
| owasp://top10/2025/{A01..A10} | Per-category details + testing checklist |
| owasp://api-security/top10 | OWASP API Security Top 10 (2023) |
| owasp://api-security/top10/{API1..API10} | Per-category details |
| ptes://phases | PTES 7-phase methodology o |
| ptes://phase/{1..7} | Phase details (objectives, tools, deli) |
| checklist://web-application | Web app pentest checklist (OWASP Testing Guide) |
| checklist://api | API pentest checklist |
| checklist://network | Network infrastructure checklist |
| mitre://attack/tactics | MITRE ATT&CK Enterprise tactics + techniques |
| mitre://attack/technique/{T1xxx} | Technique detail by ID |
| creds://defaults/{product} | Default credentials database |
| payloads://{type} | Curated payload lists by type (xss, sqli, lfi, ssti, etc.) |
| stealth://techniques | Reference guide for operational security techniques |
| stealth://proxy-guide | Step-by-step proxy and Tor configuration guide |
| tools://catalog | Live tool a status |
| tools://{tool}/usage | Usage guide for nmap, nuclei, sqlmap, metasploit, tri |
| prompts://list | List of all a prompts with descriptions |
| prompts://category/{category} | Prompts filtered by category |

---

Architecture

---

Configuration Files

Tengu uses three configuration files. Editing the wrong one is the most common source
of confusion when switching between local and Docker workflows.

| File | When to use | What it controls |
|------|-------------|------------------|
| tengu.toml (root) | Running locally: uv run tengu, uv run python autonomous_tengu.py | MCP ser: allowed_hosts, tool paths, rate limits, stealth |
| docker/tengu.toml | Running : make docker-up, make docker-agent | Same settings as root, but pre-configured for Docker networking (172.16.0.0/12, service DNS aliases). Baked into the image at build time — rebuild required after changes (make docker-rebuild-tengu) |
| .env | Both local and Docker | Secrets and runtime vars: ANTHROPIC_API_KEY, TENGU_AGENT_TARGET, TENGU_AGENT_MODEL, TENGU_AGENT_MAX_TOKENS, etc. Read by docker compose and load_dotenv() |
| .en | Reference only | Template listing all a en |

Quick config for copilot mode (local): edit tengu.toml at the project root —
add your target to [targets] allowed_hosts.

Quick config for agent mode (Docker): edit docker/tengu.toml, then run
make docker-rebuild-tengu before make docker-agent.

> Common pitfall: if scans fail with TargetNotAllowedError inside Docker, you
> probably edited tengu.toml (root) instead of docker/tengu.toml. Docker uses its
> own copy baked into the image. After editing, run make docker-rebuild-tengu.

---

Safety by Design

Tengu is built as a force multiplier for human pentesters, not an autonomous attack tool.

| Control | Description |
|---------|-------------|
| Target Allowlist | Only pre-appro in tengu.toml are e |
| Input Sanitization | All inputs are against strict patterns before reaching any tool |
| Rate Limiting | Sliding window + concurrent slot limits prevent accidental DoS |
| Audit Logging | Every tool in logged to ./logs/tengu-audit.log in JSON format |
| Human-in-the-Loop | msf_run_module, hydra_attack, and impacket_kerberoast require explicit confirmation |
| No shell=True — ever | All subprocess calls use asyncio.create_subprocess_exec |

---

De

Tengu has 2643+ tests co unit logic, security (command injection, input ), and integration scenarios. See CLAUDE.md for the full contributor guide.

---

Legal Notice

Tengu is designed for authorized security testing only. Only scan systems you own or ha written permission to test. Unauthorized scanning is illegal in most jurisdictions. The authors accept no liability for misuse.

项目信息

开发语言：Python

Star 数：61

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕AI-powered penetration testing MCP server展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。