An open API service indexing awesome lists of open source software.

https://github.com/rfunix/tengu

AI-powered penetration testing MCP server
https://github.com/rfunix/tengu

ai-security claude cybersecurity ethical-hacking infosec kali-linux mcp mcp-server metasploit nmap offensive-security owasp penetration-testing pentesting red-team security vulnerability-scanner

Last synced: 4 months ago
JSON representation

AI-powered penetration testing MCP server

Awesome Lists containing this project

README

          

# Tengu — Pentesting MCP Server


Tengu


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


From recon to report — AI-assisted pentesting in one command.


CI
License
Python
MCP
Tools
Version
Agent

---

**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 destructive actions
- **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 interactive pentest copilot — you direct the engagement, Claude picks the right tools and chains them together automatically.

[![Tengu copilot demo](https://img.youtube.com/vi/KklDFk4pxZ0/maxresdefault.jpg)](https://www.youtube.com/watch?v=KklDFk4pxZ0)

### Quick Start

```bash
git clone https://github.com/rfunix/tengu.git && cd tengu
make docker-build
make docker-up
```

Connect Claude Code to the running server:

```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 chains tools automatically: `validate_target` → `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:**

```bash
TENGU_ALLOWED_HOSTS="192.168.1.0/24,10.0.0.0/8" make docker-up
```

### Image Tiers

Choose the right size for your use case:

| Tier | Size | MCP Tools | Use case |
|------|------|-----------|----------|
| `minimal` | ~480MB | 17 | Lightweight analysis, CVE research, reporting |
| `core` | ~7GB | 47 | Full pentest toolkit (default) |
| `full` | ~8GB | 80 | Everything + 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
```

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

Manual Install (without Docker)

**Prerequisites:** Python 3.12+, [`uv`](https://github.com/astral-sh/uv), Kali Linux (recommended)

```bash
git clone https://github.com/rfunix/tengu.git && cd tengu

# Install Python dependencies
uv sync

# Install external pentesting tools (Kali/Debian)
make install-tools

# Run the MCP server (stdio transport)
uv run tengu
```

Connect Claude Code:

```bash
claude mcp add --scope user tengu -- uv run --directory /path/to/tengu tengu
```

Configure allowed targets in `tengu.toml`:

```toml
[targets]
allowed_hosts = ["192.168.1.0/24", "example.com"]
```

For Claude Desktop, VM/SSE remote setup, and advanced configurations, see [docs/deployment-guide.md](docs/deployment-guide.md).

### Configuration Reference

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

See [docs/configuration-reference.md](docs/configuration-reference.md) for the full reference.

---

## Autonomous Agent Mode

Run a fully autonomous pentest without manual tool invocation. 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](https://img.youtube.com/vi/BESaKamKPO8/maxresdefault.jpg)](https://www.youtube.com/watch?v=BESaKamKPO8)

### Quick Start

```bash
cp .env.example .env
# Edit .env: set ANTHROPIC_API_KEY and TENGU_AGENT_TARGET
```

**Lab targets (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
```

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

```bash
make docker-pentest
make docker-agent
```

**View reports in 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
```


Tengu report viewer

**Without Docker:**

```bash
uv sync --extra agent
python autonomous_tengu.py 192.168.1.100 --scope 192.168.1.0/24 --type blackbox

# Cost-optimised run
python autonomous_tengu.py 192.168.1.100 --model claude-haiku-4-5 --max-tokens 1024 --timeout 30
```

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

```
START → initializer → strategist ─┬─→ executor → analyst ─┬─→ strategist (loop)
│ └─→ reporter → END
├─→ human_gate → executor
└─→ reporter → END
```

**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 advances phases
- **Human gate** interrupts execution before destructive tools (`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 | `validate_target` confirms scope, `check_tools` verifies readiness | `validate_target`, `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 | Vulnerability Analysis | Template scanning, web app testing, SSL/TLS analysis, parameter fuzzing | `nuclei`, `nikto`, `ffuf`, `sqlmap`, `testssl` |
| 5 | Exploitation | Controlled exploitation of confirmed vulnerabilities with human-in-the-loop | `msf_run_module`, `sqlmap`, `hydra`, `searchsploit` |
| 6 | Post-Exploitation | Credential harvesting, lateral movement assessment, privilege 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= 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 | theHarvester, 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 harvester, QR code attack, payload generator | 3 |
| Secrets & Code | TruffleHog, Gitleaks | 2 |
| Container & 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 |
| Anonymity & Stealth | Tor check/rotate, proxy check, identity rotation | 5 |
| Analysis & Reporting | Finding correlation, CVSS risk scoring, report generation | 3 |
| CVE Intelligence | CVE lookup (NVD), CVE search by keyword/product/severity | 2 |
| Utility | Tool checker, target validator | 2 |

Full tool list (80 tools)

### Reconnaissance
| Tool | Description |
|------|-------------|
| `nmap_scan` | Port scanning and service/OS detection |
| `masscan_scan` | High-speed port scanner for large networks |
| `subfinder_enum` | Passive subdomain 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 takeover detection |
| `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 vulnerability scanner (CVEs, misconfigs) |
| `nikto_scan` | Web server misconfiguration and outdated software scanner |
| `ffuf_fuzz` | Directory, parameter, and vhost fuzzing |
| `gobuster_scan` | Directory, DNS, and vhost brute-force |
| `wpscan_scan` | WordPress vulnerability 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, recursive content discovery via brute-force |

### OSINT
| Tool | Description |
|------|-------------|
| `theharvester_scan` | 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 via Dalfox |
| `commix_scan` | Automated command injection detection and exploitation |
| `crlfuzz_scan` | CRLF injection fuzzing for header injection vulnerabilities |
| `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 active Metasploit sessions |
| `msf_session_cmd` | Execute a command on an active session (shell/Meterpreter) |
| `searchsploit_query` | Search Exploit-DB offline database |

### Social Engineering
| Tool | Description |
|------|-------------|
| `set_credential_harvester` | 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_active_scan` | OWASP ZAP active vulnerability 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 |
|------|-------------|
| `trivy_scan` | Vulnerability 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 |

### Active Directory
| Tool | Description |
|------|-------------|
| `enum4linux_scan` | SMB/NetBIOS enumeration |
| `nxc_enum` | Active Directory enumeration via NetExec |
| `impacket_kerberoast` | Kerberoasting with Impacket GetUserSPNs |
| `impacket_secretsdump` | Remote SAM/LSA/NTDS secrets dump via Impacket |
| `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` | Passive wireless network scan (airodump-ng) |

### IaC Security
| Tool | Description |
|------|-------------|
| `checkov_scan` | IaC misconfiguration scan (Terraform, K8s, Dockerfile) |

### Stealth / OPSEC
| Tool | Description |
|------|-------------|
| `tor_check` | Verify 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` | Validate proxy latency, exit IP, and anonymity type |
| `rotate_identity` | Rotate Tor circuit and User-Agent simultaneously |

### Analysis & Utility
| Tool | Description |
|------|-------------|
| `check_tools` | Verify which external tools are installed |
| `validate_target` | Validate target against allowlist |
| `correlate_findings` | Correlate findings across multiple scans |
| `score_risk` | CVSS-based risk scoring |
| `cve_lookup` | CVE details from NVD (CVSS, CWE, affected products) |
| `cve_search` | Search CVEs by keyword, product, or severity |
| `generate_report` | Generate Markdown/HTML/PDF pentest report |

---

## Workflows & Prompts (35)

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

| Category | Prompts |
|----------|---------|
| **Pentest workflows** | `full_pentest`, `quick_recon`, `web_app_assessment` |
| **Vulnerability assessment** | `assess_injection`, `assess_access_control`, `assess_crypto`, `assess_misconfig` |
| **OSINT** | `osint_investigation` |
| **Reports** | `executive_report`, `technical_report`, `full_pentest_report`, `finding_detail`, `risk_matrix`, `remediation_plan`, `retest_report`, `save_report` |
| **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 overview |
| `ptes://phase/{1..7}` | Phase details (objectives, tools, deliverables) |
| `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 availability status |
| `tools://{tool}/usage` | Usage guide for nmap, nuclei, sqlmap, metasploit, trivy, amass |
| `prompts://list` | List of all available prompts with descriptions |
| `prompts://category/{category}` | Prompts filtered by category |

---

## Architecture

```
┌─────────────┐ 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
└──────────────────┘
```

---

## 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 server config: `allowed_hosts`, tool paths, rate limits, stealth |
| `docker/tengu.toml` | Running via Docker: `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()` |
| `.env.example` | Reference only | Template listing all available environment variables |

**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-approved targets in `tengu.toml` are ever scanned |
| **Input Sanitization** | All inputs are validated against strict patterns before reaching any tool |
| **Rate Limiting** | Sliding window + concurrent slot limits prevent accidental DoS |
| **Audit Logging** | Every tool invocation 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` |

---

## Development

```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 has 1931+ tests covering unit logic, security (command injection, input validation), and integration scenarios. See [CLAUDE.md](CLAUDE.md) for the full contributor guide.

---

## Legal Notice

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