raven-nest-mcp

Raven Nest MCP

一款以 MCP 服务形式运行的渗透测试工具包，通过经过安全加固的接口，让 AI 助手能够以结构化方式访问行业标准安全工具。

仅限授权使用。 Raven Nest 是一款用于进攻性安全测试的工具，仅适用于测试您拥有或获得明确书面授权评估的系统。未经授权进行扫描、枚举或利用漏洞可能违法。您有责任取得授权并遵守所有适用法律。本软件按“原样”提供，不作任何形式的保证——请参阅 LICENSE。

演示

工具的真实 MCP 流量——无大模型参与，全程确定性运行。目标为已获授权的公共测试主机 example.com / scanme.nmap.org。

扫描 → 结构化发现 → 报告

侦察流程——连通性、端口、Web 技术栈

Metasploit 模块发现 - 需要启用 MSF 的构建版本；默认容器映像不包含 Metasploit

功能简介

Raven Nest 通过 MCP 接口封装 22 种安全工具和 Metasploit Framework，并提供输入验证、输出质量评估、支持会话感知的上下文预算，以及可配置的安全限制。它负责执行工具、管理重启后仍安全的后台扫描（已完成的结果在服务重启后仍会保留；中断的扫描则会显示为失败）、持久化漏洞发现、跟踪目标发现、比较扫描差异，以及生成多种格式的报告（Markdown、JSON、SARIF、HTML）。发现、报告和扫描也会作为 MCP 资源提供，方便浏览。共提供 46 个 MCP 端点。

支持的工具

类别	工具
侦察	nmap、masscan、whatweb、httpx、subfinder、dnsx、dnsrecon
爬取	katana
SMB/AD	enum4linux-ng
凭据枚举（受限）	netexec
漏洞扫描	nuclei、nikto、wpscan、dalfox（XSS）
Web 模糊测试	feroxbuster、ffuf
漏洞利用	sqlmap、hydra
密码破解	john
密钥扫描	gitleaks、trufflehog
TLS/SSL	testssl.sh
Metasploit	msf_search、msf_module_info、msf_exploit、msf_auxiliary、msf_sessions、msf_post
实用工具	ping_target、http_request
扫描管理	launch_scan、get_scan_status、get_scan_results、list_scans、cancel_scan
发现管理	save_finding、get_finding、list_findings、list_findings_by_scan、delete_finding、generate_report
测试任务	set_engagement、list_engagements
发现跟踪	get_target_info、list_targets、diff_scans

整体运作方式

Raven Nest 是一个 MCP 服务——它本身不执行任何操作。MCP 宿主通过 stdio 启动它并调用工具。选择适合你的宿主：

• 任意 MCP 宿主（推荐）——让 Claude Desktop、Cursor 或任意 MCP 客户端 使用下方的 Docker 镜像；宿主会为你启动服务。
• 配套 REPL——raven-nest-client 是一个 TypeScript 终端客户端（支持制表符补全、扫描／发现／报告命令、 测试范围限定），可手动驱动 Raven Nest。它可以启动本地 raven-server 构建版本或 Docker 镜像。

两种方式使用的都是同一个 stdio 二进制文件。

快速开始

使用 Docker 运行（推荐）

已发布的镜像以 Kali 为基础，内含 raven-server 和全部 22 个封装工具， 因此你无需自行安装这些工具。让 MCP 客户端通过 stdio 连接到它：

{
  "mcpServers": {
    "raven-nest": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/tidynest/raven-nest-mcp:latest"]
    }
  }
}

masscan 和 nmap -O 需要原始套接字——如果要使用它们，请在 args 中追加 --cap-add=NET_RAW 和 --cap-add=NET_ADMIN（容器以专用非 root 用户身份运行； 运行时会直接向容器进程授予这些能力，因此无需 root 权限也能正常使用）。该服务也已 列入 MCP Registry，名称为 io.github.tidynest/raven-nest-mcp。

前置条件

• Rust 1.93+（2024 edition）
• 已安装一个或多个外部工具（nmap、nuclei、nikto 等）

构建

cargo build --release

配置 MCP 客户端

在项目根目录中创建 .mcp.json（或直接配置 MCP 客户端）：

{
  "mcpServers": {
    "raven-nest": {
      "command": "/path/to/raven-server",
      "args": []
    }
  }
}

该服务通过 stdio 通信，无需网络端口。

配置

Raven Nest 从 TOML 加载配置，按以下顺序解析：

1. RAVEN_CONFIG 环境变量（文件路径）
2. 二进制文件旁的 config/default.toml
3. 工作目录中的 config/default.toml
4. 内置默认值

主要配置部分：

[safety]
allowed_tools = ["nmap", "nuclei", "nikto", "whatweb", "masscan", ". . ."] 
context_budget = 65536          # Model context window in chars (0 = disabled)
expected_tool_calls = 10        # Anticipated calls per session
sudo_tools = ["masscan", "nmap"] # Tools invoked via passwordless sudo
# auto_save_findings = false     # opt-in: auto-extract findings from scanners

[execution]
default_timeout_secs = 600
max_concurrent_scans = 3
output_dir = "/tmp/raven-nest"

# [scope]                        # engagement authorization allowlist (deny-wins)
# enabled = true
# allowed_domains = ["example.com"]

# [network]
# http_proxy = "http://127.0.0.1:8080"

# [metasploit]
# enabled = true
# host = "127.0.0.1"
# port = 55553
# password = "changeme"

# [netexec]                      # gated, read-only credentialed enumeration
# enabled = true

完整的参数参考和各工具的配置选项，请参阅 docs/USAGE.md。

安全架构

每次工具调用都会经过六层检查：

1. 允许列表 -- 只有明确许可的工具才能执行
2. 输入验证 -- 目标必须是有效的 IP、主机名、CIDR 或 URL；拒绝 shell 元字符
3. 预设参数 -- 用户选择扫描类型，而不是原始 CLI 标志
4. 执行隔离 -- 可配置超时时间，并启用 kill_on_drop
5. 输出净化 -- 移除 ANSI 序列，并按可配置的限制截断（确保 UTF-8 安全）
6. 质量评估 -- 检测空结果、速率限制和 WAF 拦截

其他加固措施：

• 启动时验证配置 -- 安全限制（sqlmap level/risk、hydra tasks、masscan rate）会进行范围检查；如果配置值超出范围或使用默认 MSF 凭据，服务将拒绝启动
• 字典路径验证 -- hydra、john、feroxbuster 和 ffuf 仅接受 /usr/share/、/usr/lib/ 或配置的 output_dir 下的字典；拒绝路径遍历（..）
• 位置参数防护 -- 对作为位置参数传递给工具的自由文本值进行字符集检查，防止它们被重新解析为标志：hydra service（小写字母／数字／连字符）和 form_params（不得以 - 开头，不得包含控制字符）、sqlmap technique（BEUSTQ 的子集）、ffuf filter_size（数字／逗号）。目标也会进行相同处理（-oN/tmp/evil 这类类似标志的输入会被拒绝）
• 端口规范验证 -- nmap 和 masscan 的端口参数仅接受数字、逗号和连字符
• 文件权限 -- Cookie 文件和扫描临时文件仅允许所有者访问，创建时权限为 0o600
• Markdown 转义 -- 生成报告时会转义用户提供的发现字段，以防止 Markdown 注入
• 发现 ID 验证 -- 获取／删除发现记录的操作要求使用有效的 UUID 格式，以防止路径遍历
• 授权范围 -- 可选的授权允许列表（[scope]）：启用后，每个目标都必须匹配允许的 CIDR／域名，且不得匹配拒绝项（拒绝优先）；除非禁用，否则允许回环地址。http_request 会针对每一跳重定向重新验证范围，因此重定向无法越出范围。默认关闭
• 审计日志 -- 每次工具执行都会追加记录到 {output_dir}/audit.log，包含工具、目标和已脱敏的参数
• 主动冷却 -- 可选的 min_exec_gap_ms 会错开连续启动工具的时间，避免连续运行激进工具触发目标的 WAF 或速率限制；per_target_min_gap_ms 则针对每个主机执行相同操作，同时允许独立目标并行处理；这两项与被动式 WAF／速率限制检测相辅相成。默认均关闭

Metasploit 集成额外采用 5 层安全模型：默认禁用、按工具设置允许列表、基于路径边界的模块拒绝列表、漏洞利用确认门槛（需二次调用才能执行），以及会话命令过滤。错误消息中的密码会被脱敏，且仅允许在本地主机连接中绕过 TLS 证书验证。请参阅 docs/METASPLOIT.md。

需要 root 权限的工具（masscan、nmap OS 检测）可通过免密码 sudo 运行，无需提升整个服务的权限。请参阅配置文档中的 sudo_tools。

上下文预算

具有会话感知能力的上下文预算跟踪器会根据剩余上下文窗口空间动态调整每个工具的输出上限。这样可以避免上下文窗口有限（49-64K tokens）的本地 AI 模型出现上下文溢出。

• 完整模式——所有发现和详细信息，每次工具调用最多 8K 个字符
• 精简模式——仅显示前 N 个结果和严重/高危发现（在消耗量达到 40% 时触发）
• 最简模式——单行摘要（在消耗量达到 70% 时触发）

解析器的结果上限会通过 scale_cap() 动态调整——每个工具的输出解析器都会根据当前预算模式调整结果上限。所有工具输出都会经过集中式 ANSI 清理，并由 wrap_result() 根据预算进行截断。

预算耗尽时，服务会返回一条消息，提示 AI 保存发现并生成报告，而不是继续执行扫描。

目标发现跟踪与扫描差异比较

每次 nmap 扫描结果（run_nmap 和后台 nmap 扫描）都会累积到按主机记录的发现信息中：端口、状态、服务、版本和操作系统猜测，以及首次/最后发现时间戳。重新扫描时会合并而非覆盖记录，因此可以查看目标的演变情况。

• list_targets / get_target_info 可查看已跟踪的主机及其完整的逐主机服务表，无需重新扫描。
• diff_scans 可比较两次已完成的 nmap 扫描：新增/移除的主机和端口，以及逐端口的状态/服务/版本变化（open (ssh OpenSSH 8.9) → open (ssh OpenSSH 9.0)）。
• 发现数据与发现项一样按测评范围隔离（{engagement}/targets/），并会在重启后保留。

run_nmap 和 run_nuclei 还会在响应中附带机器可读的 structured_content（主机/端口/CVE；发现列表），不受上下文预算限制，因此客户端无需解析自然语言即可处理结果。

报告生成

generate_report 端点会生成结构化报告——默认格式为 Markdown，也可以通过 format 参数指定 JSON、SARIF 或 HTML——其中包含：

• 目录，带有指向各发现项的链接
• 执行摘要，包含严重程度分类表和总体风险评级
• 方法论部分（PTES 框架）
• 使用的工具（根据发现项去重）
• 范围与时间线——根据发现项得出的评估目标和测评时间范围
• 编号的发现项，包含严重程度、目标、工具、CVSS 分数、CVE 标识符、OWASP Top 10 类别、证据和修复建议

Markdown 和 HTML 格式会呈现完整的叙述内容（目录、方法论、范围、生成时间戳）；JSON 和 SARIF 则是供工具使用的结构化封装。发现项支持 owasp_category 字段，用于映射到 OWASP Top 10 中的漏洞类别（例如，“A03:2021 Injection”）。

MCP 资源

除了工具，服务还会通过 raven:// 协议方案将数据作为只读 MCP 资源公开，让客户端无需调用工具即可浏览或附加这些资源：

• raven://findings ——所有已保存发现项的 JSON 索引
• raven://findings/{id} ——单条发现项的 JSON 数据
• raven://reports/{markdown|json|sarif|html} ——按需生成的报告
• raven://scans ——后台扫描的 JSON 索引
• raven://scans/{id} ——扫描捕获的输出

每条已保存的发现项和已跟踪的扫描也会单独列出，因此它们会显示为支持资源的客户端中的可浏览条目。

输出解析器

每个安全工具都有一个结构化输出解析器，用于从原始工具输出中提取关键数据：

• nmap —— 使用 NSE 脚本提取的 XML 解析器（按 CVSS 评分筛选 vulners CVE）
• nuclei —— 带有严重性筛选的 JSONL 解析器
• nikto/feroxbuster/ffuf/masscan —— 可配置结果上限的逐行解析器
• sqlmap —— 注入类型和参数提取
• testssl —— 漏洞和证书发现项提取
• hydra/whatweb —— 凭据和技术识别
• subfinder/dnsrecon/dnsx —— 子域名和 DNS 记录提取
• httpx/katana —— HTTP 指纹和爬取端点提取
• dalfox/wpscan/enum4linux-ng/john —— 结构化发现项提取
• netexec —— 身份验证结果和逐主机枚举提取

所有解析器都返回 Option<String>，解析失败时会回退到原始输出。结果上限会根据当前预算模式动态调整。

身份验证扫描

http_request 工具维护一个共享 Cookie jar，该 jar 会在会话期间以及清除上下文后继续保留（保存到磁盘）。外部子进程工具（sqlmap、nikto、feroxbuster 等）不会共享此 jar——请通过各工具的 cookie 参数传递 Cookie。

测试

3 个 crate 中共有 381 个单元测试和集成测试：

cargo test --workspace

Crate	测试数
raven-core	106
raven-report	71
raven-server	191
集成测试	13

另有一个基于 Python 的 MCP 集成测试框架可用：

python3 -u tests/manual_test_harness.py all     # full suite
python3 -u tests/manual_test_harness.py phase0   # single phase

项目结构

crates/
  raven-core/     # Safety validation, subprocess execution, config (TOML),
                  # scan manager (background scans with disk spill), audit log
  raven-report/   # Finding types (with OWASP categories), file-per-finding
                  # persistence, host/service discovery store (targets),
                  # multi-format report generators (md/json/sarif/html)
  raven-server/   # MCP server (rmcp), tool handlers (one module per tool),
                  # context budget tracker, output parsers, progress ticker,
                  # structured scan results, scan diffing
config/
  default.toml    # Default configuration
  sudoers-raven-nest  # Sudoers drop-in for privilege escalation
tests/
  manual_test_harness.py  # MCP integration test harness

文档

• docs/USAGE.md —— 工具安装、配置参考和完整参数文档
• docs/MCP_TOOLS.md —— 所有 46 个工具的机器可读清单（名称 + 描述）
• docs/LOCAL_AI_INTEGRATION.md —— 使用本地模型（Ollama、LM Studio）运行 Raven Nest
• docs/METASPLOIT.md —— Metasploit Framework 集成设置和安全模型
• docs/DATA_FLOW.md —— 数据流和真实数据源：各模块负责管理哪些状态
• raven-nest-client —— 配套的 TypeScript REPL 客户端（与服务版本同步发布）
• CHANGELOG.md —— 版本发布历史（当前版本：v0.4.1）

许可证

Apache-2.0