Tengu

Tengu — Pentesting MCP Server

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

---

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.

[](https://www.youtube.com/watch?v=KklDFk4pxZ0)

Quick Start

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

Connect Claude Code to the running server:

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:

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 |

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, Kali Linux (recommended)

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:

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

Configure allowed targets in tengu.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

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

[](https://www.youtube.com/watch?v=BESaKamKPO8)

Quick Start

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

Lab targets (Juice Shop, DVWA):

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):

make docker-pentest
make docker-agent

View reports in browser:

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

Without Docker:

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 keywor

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rfunix
• Source: rfunix/tengu
• License: MIT

Install and usage instructions live in the source repository linked above.