tengu (Rfunix)

Tengu——测试MCP服务器

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

______________________________________________________________________

天狗 是一个MCP服务器，它将Claude变成了渗透测试的副驾驶。它整合了80个安全工具，从Nmap到Metasploit，具有内置的安全控制、审计日志和专业报告。

• 这是怎么一回事？ 将Claude连接到行业标准pentest工具的MCP服务器
• 为什么要使用它？ 自动化侦察和扫描，同时让人类控制漏洞
• 这是给谁的？ Pentester、红队成员、安全专业学生和咨询公司

主要特点

• 80工具 --Nmap、Metasploit、SQLMap、Nuclei、Hydra、兼容Burp的ZAP等
• 人工智能编排 --Claude根据之前的发现决定下一个工具
• 安全第一 --允许列表、速率限制、审核日志和破坏性行为的人在环
• 自动报告 --关联调查结果并生成专业的渗透测试报告（MD/HTML/PDF）
• 35个工作流程 --预构建的完整渗透测试、web应用程序、广告、云等提示
• 20资源 --内置OWASP Top 10、MITRE ATT&CK、PTES和pentest检查表
• 隐形层 --可选的Tor/SOCKS5代理路由、UA轮换和定时抖动

______________________________________________________________________

MCP服务器模式（副驾驶）

使用Claude作为交互式最重要的副驾驶——你指导参与，Claude会选择合适的工具并自动将它们连接在一起。


快速开始

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

将Claude Code连接到正在运行的服务器：

claude mcp add --transport sse tengu http://localhost:8000/sse

然后问克劳德： Do a full pentest on http://192.168.1.100

Claude自动链接工具： validate_target → whatweb → nmap → nikto → nuclei → sqlmap → correlate_findings → generate_report

Docker配置文件

扫描自定义目标而不编辑文件：

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

图像层

为您的用例选择合适的尺寸：

TENGU_TIER=minimal make docker-build   # lightweight
TENGU_TIER=core    make docker-build   # default
TENGU_TIER=full    make docker-build   # everything

所有级别包括所有35个提示和20个资源 --只有二进制工具不同。

Manual Install (without Docker)

先决条件： Python 3.12+， uvKali Linux（推荐）

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

在中配置允许的目标 tengu.toml:

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

有关Claude Desktop、VM/SSE远程设置和高级配置，请参阅 docs/deployment-guide.md.

配置参考

[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

看 docs/configuration-reference.md 以获取完整参考。

______________________________________________________________________

自主代理模式

运行一个完全自主的pentest，无需手动调用工具。该代理使用Claude作为其战略大脑，Tengu作为其执行工具集，遵循从侦察到报告的PTES方法。


快速开始

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

实验室目标（果汁店、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

真实世界的五项测试（Tengu+MSF+ZAP，无实验室容器）：

make docker-pentest
make docker-agent

在浏览器中查看报告：

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

没有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

费用控制 --三个env变量/CLI标志：

运作原理

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

关键行为：

• 战略家 （Claude）读取当前PTES阶段和累积状态以决定每个动作
• 执行者 每次迭代只调用一个Tengu MCP工具
• 分析师 （Claude）从工具输出中提取结构化数据并推进阶段
• 人门 在破坏性工具之前中断执行(msf_run_module, hydra_attack, impacket_kerberoast, sqlmap_scan 等级≥3）
• 运行至涵盖所有7个PTES阶段或 --max-iterations 已达到
• 最终 记者 电话 correlate_findings + score_risk + generate_report

PTES方法论——7个阶段

______________________________________________________________________

工具目录

minimal （17个工具，约480MB）· core （47个工具，约7GB，默认值）· full （80个工具，约8GB） 使用以下内容构建： TENGU_TIER= make docker-build。所有级别包括所有35个提示和20个资源。

Full tool list (80 tools)

侦察

网络扫描

公开来源情报

注入测试

剥削

社会工程学

蛮力

代理/DAST

秘密与代码分析

容器安全

云安全

活动目录

无线

IaC安全

隐形/作战安全

分析与实用

______________________________________________________________________

工作流程和提示（35）

预构建的工作流模板，指导Claude完成整个项目。

______________________________________________________________________

内置资源（20）

克劳德在交战期间加载的静态参考数据。

______________________________________________________________________

建筑

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

______________________________________________________________________

配置文件

Tengu使用三个配置文件。编辑错误的是最常见的来源 在本地和Docker工作流之间切换时会出现混乱。

副驾驶模式快速配置（本地）： 编辑 tengu.toml 从项目根源-- 将您的目标添加到 [targets] allowed_hosts.

代理模式快速配置（Docker）： 编辑 docker/tengu.toml，然后运行 make docker-rebuild-tengu 之前 make docker-agent.

常见陷阱： 如果扫描失败 TargetNotAllowedError 在Docker中，你 可能已编辑 tengu.toml （根）而不是 docker/tengu.tomlDocker使用其 将自己的副本烘焙到图像中。编辑后，运行 make docker-rebuild-tengu.

______________________________________________________________________

设计安全

Tengu是作为一个 人戊酯的力倍增器，而不是自主攻击工具。

______________________________________________________________________

发展

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有2643多个测试，涵盖单元逻辑、安全性（命令注入、输入验证）和集成场景。看 CLAUDE.md 查看完整的贡献者指南。

______________________________________________________________________

法律声明

Tengu是为 仅限授权安全测试。仅扫描您拥有或有明确书面许可进行测试的系统。未经授权的扫描在大多数司法管辖区都是非法的。作者对误用不承担任何责任。