"在日本神话中，天狗是一种凶猛的山灵——战略大师、武士和武士的导师。在网络安全中，它引导你度过狩猎的每个阶段。"
从侦察到报告——人工智能辅助渗透测试，只需一条命令。
Tengu 是一个 MCP 服务器，将 Claude 转变为渗透测试副驾驶员。它协调 80 种安全工具——从 Nmap 到 Metasploit——并内置安全控制、审计日志和专业报告生成。
将 Claude 用作交互式渗透测试副驾驶——你来指导行动，Claude 自动选择正确的工具并串联它们。
git clone https://github.com/rfunix/tengu.git && cd tengu make docker-build make docker-up
将Claude Code连接到运行中的服务器：```bash
claude mcp add --transport sse tengu http://localhost:8000/sse
然后询问 Claude：Do a full pentest on http://192.168.1.100
Claude 自动链式使用工具：validate_target → whatweb → nmap → nikto →
nuclei → sqlmap → correlate_findings → generate_report
| 命令 | 启动内容 |
|---|---|
make docker-up | Tengu MCP 服务器 (:8000) |
make docker-lab | + Juice Shop、DVWA（安全练习目标） |
make docker-pentest | + Metasploit、OWASP ZAP（真实世界目标） |
make docker-full | + Metasploit、ZAP 和实验目标 |
无需编辑文件即可扫描自定义目标：```bash TENGU_ALLOWED_HOSTS="192.168.1.0/24,10.0.0.0/8" make docker-up
### 镜像层级
为您的使用场景选择合适的大小：
| 层级 | 大小 | MCP工具 | 使用场景 |
|------|------|-----------|----------|
| `最小` | ~480MB | 17 | 轻量级分析、CVE研究、报告撰写 |
| `核心` | ~7GB | 47 | 完整渗透测试工具包（默认） |
| `完整` | ~8GB | 80 | 全部 + 活动目录、无线、隐蔽/OPSEC |```bash
TENGU_TIER=minimal make docker-build # lightweight
TENGU_TIER=core make docker-build # default
TENGU_TIER=full make docker-build # everything
所有层级均包含全部35个提示和20个资源 — 仅有二进制工具不同。
前提条件: Python 3.12+, uv, Kali Linux（推荐）```bash
git clone https://github.com/rfunix/tengu.git && cd tengu
uv sync
make install-tools
uv run tengu
连接 Claude Code:```bash
claude mcp add --scope user tengu -- uv run --directory /path/to/tengu tengu
在 tengu.toml 中配置允许的目标：```toml
[targets]
allowed_hosts = ["192.168.1.0/24", "example.com"]
关于 Claude Desktop、VM/SSE 远程设置及高级配置，请参阅 [docs/deployment-guide.md](https://github.com/rfunix/tengu/blob/main/docs/deployment-guide.md)。
</details>
### 配置参考```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
有关完整参考，请参见 docs/configuration-reference.md。
运行完全自主的渗透测试，无需手动调用工具。该代理使用 Claude 作为其战略大脑，Tengu 作为其执行工具集，遵循 PTES 方法论，从侦察到报告全程自动化。
cp .env.example .env
**实验目标 (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
真实世界的渗透测试（Tengu + MSF + ZAP，无实验室容器）：```bash make docker-pentest make docker-agent
**在浏览器中查看报告：**```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
不使用 Docker：```bash uv sync --extra agent python autonomous_tengu.py 192.168.1.100 --scope 192.168.1.0/24 --type blackbox
python autonomous_tengu.py 192.168.1.100 --model claude-haiku-4-5 --max-tokens 1024 --timeout 30
**成本控制** — 三个环境变量/CLI 标志：
| 标志 | 环境变量 | 默认值 |
|---|---|---|
| `--model` | `TENGU_AGENT_MODEL` | `claude-sonnet-4-6` |
| `--max-tokens` | `TENGU_AGENT_MAX_TOKENS` | `2048` |
| `--timeout` | `TENGU_AGENT_TIMEOUT` | `60` (分钟, `0`=无限制) |
### 工作原理```
START → initializer → strategist ─┬─→ executor → analyst ─┬─→ strategist (loop)
│ └─→ reporter → END
├─→ human_gate → executor
└─→ reporter → END
关键行为：
msf_run_module、hydra_attack、impacket_kerberoast、sqlmap_scan 且 level≥3）执行前中断--max-iterationscorrelate_findings + score_risk + generate_report| 阶段 | 名称 | Tengu 所做工作 | 关键工具 |
|---|---|---|---|
| 1 | 前期参与 | validate_target 确认范围，check_tools 验证就绪状态 | validate_target, check_tools |
| 2 | 情报收集 | OSINT、DNS 侦察、子域名枚举、技术指纹识别 | nmap, subfinder, amass, shodan, whatweb |
| 3 | 威胁建模 | Claude 分析已收集情报，对攻击面进行优先级排序，构建威胁场景 | (AI 驱动 — 无外部工具) |
| 4 | 漏洞分析 | 模板扫描、Web 应用测试、SSL/TLS 分析、参数模糊测试 | nuclei, nikto, ffuf, sqlmap, testssl |
| 5 | 利用 | 对人机协作确认的漏洞进行受控利用 | msf_run_module, sqlmap, hydra, searchsploit |
| 6 | 后利用 | 凭证收集、横向移动评估、权限提升 | impacket_kerberoast, nxc_enum, enum4linux |
| 7 | 报告 | 关联所有发现、计算风险评分、生成专业报告 | correlate_findings, score_risk, generate_report |
minimal（17 个工具，约 480MB）·core（47 个工具，约 7GB，默认）·full（80 个工具，约 8GB） 使用TENGU_TIER=<tier> make docker-build构建。所有层级均包含全部 35 个提示词和 20 个资源。
| 类别 | 工具 | 数量 |
|---|---|---|
| 侦察 | Nmap, Masscan, Amass, Subfinder, Gowitness, HTTrack, Katana, httpx, SNMPwalk, RustScan | 10 |
| Web 扫描 | Nikto, Nuclei, FFUF, Gobuster, WPScan, Feroxbuster, OWASP ZAP, wafw00f | 8 |
| SSL / TLS | sslyze, testssl.sh, HTTP 头部分析, CORS 测试器 | 4 |
| DNS | DNS 枚举, DNSRecon, Subjack, WHOIS | 4 |
| OSINT | theHarvester, Shodan, WhatWeb, DNStwist | 4 |
| 注入测试 | SQLMap, Dalfox (XSS), Commix, CRLFuzz, GraphQL 安全检查, Arjun | 6 |
| 暴力破解 | Hydra, John the Ripper, Hashcat, CeWL | 4 |
| 利用 | Metasploit (search, info, run, sessions, cmd), SearchSploit | 6 |
| 社会工程 | SET 凭证收割器、QR 码攻击、Payload 生成器 | 3 |
| 密钥与代码 | TruffleHog, Gitleaks | 2 |
| 容器与云 | Trivy, Checkov, ScoutSuite, Prowler | 4 |
| Active Directory | NetExec, Enum4linux, Impacket (Kerberoast, secretsdump, psexec, wmiexec, smbclient), BloodHound, Responder, SMBMap | 10 |
| 无线 | aircrack-ng / airodump-ng | 1 |
| 匿名与隐匿 | Tor 检查/轮换、代理检查、身份轮换 | 5 |
| 分析与报告 | 发现关联、CVSS 风险评分、报告生成 | 3 |
| CVE 情报 | CVE 查询（NVD）、CVE 关键词/产品/严重级别搜索 | 2 |
| 实用工具 | 工具检查器、目标验证器 | 2 |
| 工具 | 描述 |
|---|---|
nmap_scan | 端口扫描和服务/操作系统检测 |
masscan_scan | 用于大型网络的高速端口扫描器 |
subfinder_enum | 被动子域名枚举 |
amass_enum | 攻击面映射和 DNS 暴力破解 |
dnsrecon_scan | DNS 侦察（区域传输、暴力破解、PTR） |
dns_enumerate | DNS 记录枚举（A、MX、NS、TXT、SOA……） |
whois_lookup | WHOIS 域名和 IP 查询 |
subjack_check | 子域名劫持检测 |
gowitness_screenshot | 用于文档的网页截图捕获 |
httrack_mirror | 用于离线分析和取证的完整网站镜像 |
katana_crawl | 用于链接发现和端点映射的快速 Web 爬虫 |
httpx_probe | HTTP 探测 — 状态码、技术栈、重定向 |
snmpwalk_scan | SNMP 枚举和 MIB 遍历 |
rustscan_scan | 超快速端口扫描（为 Nmap 后续扫描发现开放端口） |
| 工具 | 描述 |
|---|---|
nuclei_scan | 基于模板的漏洞扫描器（CVE、错误配置） |
nikto_scan | Web 服务器错误配置和过时软件扫描器 |
ffuf_fuzz | 目录、参数和虚拟主机模糊测试 |
gobuster_scan | 目录、DNS 和虚拟主机暴力破解 |
wpscan_scan | WordPress 漏洞扫描器 |
testssl_check | 全面的 SSL/TLS 配置分析 |
analyze_headers | HTTP 安全标头分析和评级 |
test_cors | CORS 错误配置检测 |
ssl_tls_check | SSL/TLS 证书和密码检查（sslyze） |
wafw00f_scan | Web 应用防火墙检测和指纹识别 |
feroxbuster_scan | 通过暴力破解进行快速递归内容发现 |
| 工具 | 描述 |
|---|---|
theharvester_scan | 从公共来源枚举电子邮件、子域名和主机 |
shodan_lookup | Shodan 主机和资产搜索 |
whatweb_scan | Web 技术指纹识别（CMS、WAF、框架） |
dnstwist_scan | 域名置换和域名抢注检测 |
| 工具 | 描述 |
|---|---|
sqlmap_scan | 自动化 SQL 注入检测与利用 |
xss_scan | 通过 Dalfox 检测 XSS |
commix_scan | 自动化命令注入检测与利用 |
crlfuzz_scan | CRLF 注入模糊测试，用于标头注入漏洞 |
graphql_security_check | GraphQL 内省、批处理、深度限制、字段建议 |
arjun_discover | 隐藏 HTTP 参数发现 |
| 工具 | 描述 |
|---|---|
msf_search | 搜索 Metasploit 模块 |
msf_module_info | 获取详细 Metasploit 模块信息 |
msf_run_module | 执行 Metasploit 模块（需要明确确认） |
msf_sessions_list | 列出活跃 Metasploit 会话 |
msf_session_cmd | 在活跃会话上执行命令（Shell/Meterpreter） |
searchsploit_query | 搜索 Exploit-DB 离线数据库 |
| 工具 | 描述 |
|---|---|
set_credential_harvester | 克隆网站并捕获提交的凭证（授权的钓鱼模拟） |
set_qrcode_attack | 生成指向 URL 的二维码，用于物理社会工程评估 |
set_payload_generator | 为授权活动生成社会工程 Payload（PowerShell、HTA） |
| 工具 | 描述 |
|---|---|
hydra_attack | 网络登录暴力破解（SSH、FTP、HTTP、SMB……） |
hash_crack | 字典哈希破解（Hashcat / John the Ripper） |
hash_identify | 哈希类型识别 |
cewl_generate | 从目标网站生成自定义单词表 |
| 工具 | 描述 |
|---|---|
zap_spider | OWASP ZAP Web 爬虫 |
zap_active_scan | OWASP ZAP 主动漏洞扫描 |
zap_get_alerts | 获取 ZAP 扫描结果 |
| 工具 | 描述 |
|---|---|
trufflehog_scan | Git 仓库中泄露密钥检测 |
gitleaks_scan | Git 历史中的凭证扫描 |
| 工具 | 描述 |
|---|---|
trivy_scan | Docker 镜像、IaC 和 SBOM 的漏洞扫描 |
| 工具 | 描述 |
|---|---|
scoutsuite_scan | 云安全审计（AWS、Azure、GCP） |
prowler_scan | AWS/GCP/Azure 安全最佳实践和合规审计 |
| 工具 | 描述 |
|---|---|
enum4linux_scan | SMB/NetBIOS 枚举 |
nxc_enum | 通过 NetExec 进行 Active Directory 枚举 |
impacket_kerberoast | 使用 Impacket GetUserSPNs 进行 Kerberoasting |
impacket_secretsdump | 通过 Impacket 进行远程 SAM/LSA/NTDS 密钥转储 |
impacket_psexec | 通过 SMB 执行远程命令（PsExec 风格） |
impacket_wmiexec | 通过 WMI 执行远程命令 |
impacket_smbclient | SMB 共享枚举和文件访问 |
bloodhound_collect | BloodHound AD 数据收集（SharpHound/bloodhound-python） |
responder_capture | LLMNR/NBT-NS/MDNS 中毒用于凭证捕获 |
smbmap_scan | SMB 共享枚举和访问测试 |
| 工具 | 描述 |
|---|---|
aircrack_scan | 被动无线网络扫描（airodump-ng） |
| 工具 | 描述 |
|---|---|
checkov_scan | IaC 错误配置扫描（Terraform、K8s、Dockerfile） |
| 工具 | 描述 |
|---|---|
tor_check | 验证 Tor 连接和出口节点 IP |
tor_new_identity | 请求新的 Tor 电路（NEWNYM） |
check_anonymity | 检查暴露的 IP、DNS 泄露和匿名性等级 |
proxy_check | 验证代理延迟、出口 IP 和匿名性类型 |
rotate_identity | 同时轮换 Tor 电路和 User-Agent |
| 工具 | 描述 |
|---|---|
check_tools | 验证已安装哪些外部工具 |
validate_target | 根据允许列表验证目标 |
correlate_findings | 跨多个扫描关联发现 |
score_risk | 基于 CVSS 的风险评分 |
cve_lookup | 来自 NVD 的 CVE 详情（CVSS、CWE、受影响产品） |
cve_search | 按关键词、产品或严重级别搜索 CVE |
generate_report | 生成 Markdown/HTML/PDF 渗透测试报告 |
预构建的工作流模板，指导 Claude 完成完整的渗透测试。
| 类别 | 提示词 |
|---|---|
| 渗透测试工作流 | full_pentest, quick_recon, web_app_assessment |
| 漏洞评估 | assess_injection, assess_access_control, assess_crypto, assess_misconfig |
| OSINT | osint_investigation |
| 报告 | executive_report, technical_report, full_pentest_report, finding_detail, risk_matrix, remediation_plan, retest_report, save_report |
| 隐匿/OPSEC | stealth_assessment, opsec_checklist |
| 专项 | ad_assessment, api_security_assessment, container_assessment, cloud_assessment, wireless_assessment, bug_bounty_workflow, compliance_assessment |
| 快速操作 | explore_url, map_network, hunt_subdomains, find_vulns, find_secrets, go_stealth, crack_wifi, pwn_target, msf_exploit_workflow |
| 社会工程 | social_engineering_assessment |
Claude 在渗透测试期间加载的静态参考数据。
| URI | 内容 |
|---|---|
owasp://top10/2025 | OWASP Top 10:2025 完整列表 |
owasp://top10/2025/{A01..A10} | 各类别详情 + 测试清单 |
owasp://api-security/top10 | OWASP API 安全 Top 10 (2023) |
owasp://api-security/top10/{API1..API10} | 各类别详情 |
ptes://phases | PTES 7 阶段方法论概述 |
ptes://phase/{1..7} | 阶段详情（目标、工具、交付物） |
checklist://web-application | Web 应用渗透测试清单（OWASP 测试指南） |
checklist://api | API 渗透测试清单 |
checklist://network | 网络基础设施清单 |
mitre://attack/tactics | MITRE ATT&CK 企业战术 + 技术 |
mitre://attack/technique/{T1xxx} | 按 ID 的技术详情 |
creds://defaults/{product} | 默认凭证数据库 |
payloads://{type} | 按类型分类的精选 Payload 列表（xss、sqli、lfi、ssti 等） |
stealth://techniques | 操作安全技术参考指南 |
stealth://proxy-guide | 分步代理和 Tor 配置指南 |
tools://catalog | 实时工具可用性状态 |
tools://{tool}/usage | nmap、nuclei、sqlmap、metasploit、trivy、amass 的使用指南 |
prompts://list | 所有可用提示词列表及描述 |
prompts://category/{category} | 按类别过滤的提示词 |
┌─────────────┐ 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`（项目根目录） | 本地运行：`uv run tengu`、`uv run python autonomous_tengu.py` | MCP 服务器配置：`allowed_hosts`、工具路径、速率限制、隐身设置 |
| `docker/tengu.toml` | 通过 Docker 运行：`make docker-up`、`make docker-agent` | 与根目录相同设置，但预先配置为 Docker 网络（`172.16.0.0/12`、服务 DNS 别名）。在构建时打包到镜像中 — 更改后 **需要重新构建**（`make docker-rebuild-tengu`） |
| `.env` | 本地和 Docker 均可 | 密钥和运行时变量：`ANTHROPIC_API_KEY`、`TENGU_AGENT_TARGET`、`TENGU_AGENT_MODEL`、`TENGU_AGENT_MAX_TOKENS` 等。由 `docker compose` 和 `load_dotenv()` 读取 |
| `.env.example` | 仅作参考 | 列出所有可用环境变量的模板 |
**copilot 模式（本地）快速配置：** 编辑项目根目录的 `tengu.toml` — 将目标添加到 `[targets] allowed_hosts` 中。
**agent 模式（Docker）快速配置：** 编辑 `docker/tengu.toml`，然后运行 `make docker-rebuild-tengu`，再执行 `make docker-agent`。
> **常见陷阱：** 如果在 Docker 内扫描失败并显示 `TargetNotAllowedError`，你很可能编辑的是 `tengu.toml`（根目录）而非 `docker/tengu.toml`。Docker 使用其打包在镜像中的独立副本。编辑后，请运行 `make docker-rebuild-tengu`。
---
## 安全设计
Tengu 被设计为 **人类渗透测试人员的效能倍增器**，而非自主攻击工具。
| 控制措施 | 描述 |
|----------|------|
| **目标白名单** | 只扫描 `tengu.toml` 中预先批准的目标 |
| **输入净化** | 所有输入在到达任何工具前均经过严格模式验证 |
| **速率限制** | 滑动窗口 + 并发槽限制，防止意外拒绝服务攻击 |
| **审计日志** | 每次工具调用均以 JSON 格式记录到 `./logs/tengu-audit.log` |
| **人在回路中** | `msf_run_module`、`hydra_attack` 和 `impacket_kerberoast` 需要明确确认 |
| **绝不使用 shell=True** | 所有子进程调用均使用 `asyncio.create_subprocess_exec` |
---
## 开发```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 拥有 2643+ 项测试，涵盖单元逻辑、安全性（命令注入、输入验证）和集成场景。完整贡献指南请参阅 CLAUDE.md。
Tengu 设计用于授权的安全测试。请仅扫描您拥有或已获得明确书面许可的系统。在大多数司法管辖区，未经授权的扫描是违法的。作者对误用不承担任何责任。