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.

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

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:

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.

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

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

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

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

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:

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

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.

Workflows & Prompts (35)

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

Built-in Resources (20)

Static reference data loaded by Claude during engagements.

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.

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.

Development

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 2643+ tests covering unit logic, security (command injection, input validation), 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 have explicit written permission to test. Unauthorized scanning is illegal in most jurisdictions. The authors accept no liability for misuse.