tidynest/raven-nest-mcp

# Raven Nest MCP [](https://opensource.org/licenses/Apache-2.0) [](https://github.com/tidynest/raven-nest-mcp/actions) [](https://github.com/tidynest/raven-nest-mcp/releases) [](https://github.com/tidynest/raven-nest-mcp) [](https://modelcontextprotocol.io) 一个作为 [MCP](https://modelcontextprotocol.io/) server 运行的渗透测试工具包，通过安全加固的接口让 AI 助手能够结构化地访问行业标准安全工具。 ## 它的功能 Raven Nest 将 22 款安全工具以及 Metasploit Framework 封装在 MCP 接口之后，提供输入验证、输出质量评估、会话感知上下文预算以及可配置的安全限制。它负责处理工具执行、后台扫描管理、漏洞发现持久化以及多格式报告生成（Markdown、JSON、SARIF、HTML）。共有 43 个 MCP endpoint。 ### 支持的工具 | 类别 | 工具 | |----------|-------| | 信息收集 | nmap, masscan, whatweb, httpx, subfinder, dnsx, dnsrecon | | 爬虫 | katana | | SMB/AD | enum4linux-ng | | 凭据枚举（受控） | netexec | | 漏洞扫描 | nuclei, nikto, wpscan, dalfox (XSS) | | Web fuzzing | 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 | ## 快速开始 ### 使用 Docker 运行（推荐） 发布的镜像在 Kali 基础镜像上捆绑了 `raven-server` **以及所有 22 个封装的工具**，因此您无需自行安装它们。将您的 MCP client 指向它（stdio）： ``` { "mcpServers": { "raven-nest": { "command": "docker", "args": ["run", "--rm", "-i", "ghcr.io/tidynest/raven-nest-mcp:latest"] } } } ``` `masscan` 和 `nmap -O` 需要 raw socket —— 如果您使用它们，请在 `args` 中附加 `--cap-add=NET_RAW` 和 `--cap-add=NET_ADMIN`。该 server 也在 [MCP Registry](https://registry.modelcontextprotocol.io) 上列为 `io.github.tidynest/raven-nest-mcp`。 ### 前置条件 - Rust 1.93+（2024 版本） - 已安装一个或多个外部工具（nmap、nuclei、nikto 等） ### 构建 ``` cargo build --release ``` ### 配置您的 MCP client 在您的项目根目录中创建 `.mcp.json`（或直接配置您的 MCP client）： ``` { "mcpServers": { "raven-nest": { "command": "/path/to/raven-server", "args": [] } } } ``` 该 server 通过 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 # 选择启用：从 scanners 自动提取 findings [execution] default_timeout_secs = 600 max_concurrent_scans = 3 output_dir = "/tmp/raven-nest" # [scope] # 授权允许列表（拒绝优先） # 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] # 受限的只读凭据枚举 # enabled = true ``` 有关完整的参数参考和各个工具的配置选项，请参阅 [docs/USAGE.md](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 任务数、masscan 速率）进行范围检查；server 会拒绝使用超出范围的值或默认的 MSF 凭据启动 - **字典路径验证** -- hydra、john、feroxbuster 和 ffuf 仅接受位于 `/usr/share/`、`/usr/lib/` 或配置的 `output_dir` 下的字典；拒绝路径遍历（`..`） - **端口规范验证** -- nmap 和 masscan 端口参数仅接受数字、逗号和连字符 - **文件权限** -- cookie 文件和扫描临时文件以 `0o600`（仅所有者）权限创建 - **Markdown 转义** -- 报告生成时会转义用户提供的发现字段，以防止 Markdown 注入 - **发现 ID 验证** -- 获取/删除发现的操作需要有效的 UUID 格式，防止路径遍历 - **授权测试范围** -- 可选的授权允许列表（`[scope]`）：启用后，每个目标必须匹配允许的 CIDR/域名，且不得匹配被拒绝的 CIDR/域名（拒绝优先）；除非明确禁用，否则允许回环地址。默认关闭 - **审计日志** -- 每次工具执行都会附加到 `{output_dir}/audit.log` 中，包含工具、目标和脱敏后的参数 - **主动冷却** -- 可选的 `min_exec_gap_ms` 用于拉开连续工具启动的间隔，以防连续的激进工具触发目标的 WAF 或速率限制器；作为响应式 WAF/速率限制检测的补充。默认关闭 Metasploit 集成增加了 5 层安全模型：默认禁用、基于工具的允许列表、路径边界模块黑名单、漏洞利用确认门（双重调用执行）以及会话命令过滤。密码在错误消息中会被脱敏，TLS 证书绕过仅限于 localhost 连接。请参阅 [docs/METASPLOIT.md](docs/METASPLOIT.md)。 需要 root 权限的工具（masscan、nmap 操作系统检测）可以通过无密码 `sudo` 运行，而无需提升整个 server 的权限。请参阅[配置文档](docs/USAGE.md#sudo_tools--privilege-escalation)中的 `sudo_tools`。 ## 上下文预算 一个具有会话感知能力的**上下文预算跟踪器**会根据剩余的上下文窗口空间动态调整每个工具的输出上限。这可以防止在具有有限上下文窗口（49-64K token）的本地 AI 模型上发生上下文溢出。 - **完整模式** -- 所有发现，所有细节，每次工具调用最多 8K 字符 - **紧凑模式** -- Top-N 结果，仅严重/高危发现（在消耗 40% 时触发） - **最小模式** -- 单行摘要（在消耗 70% 时触发） 解析器结果上限通过 `scale_cap()` 动态缩放 —— 每个工具的输出解析器会根据当前活动的预算模式调整其结果限制。所有工具输出都会在 `wrap_result()` 中通过集中的 ANSI 剥离和预算感知截断进行处理。 当预算耗尽时，server 会返回一条消息，指引 AI 保存发现并生成报告，而不是运行额外的扫描。 ## 报告生成 `generate_report` endpoint 会生成一份结构化的报告 —— 默认为 Markdown，或通过 `format` 参数生成 JSON、SARIF 或 HTML —— 其中包含： - 带有链接的**目录** - 带有严重性分类表和总体风险评级的**执行摘要** - **测试方法论**部分（PTES 框架） - **使用的工具**（从发现中去除重复项） - **带编号的发现**，包含严重性、目标、工具、CVSS 分数、CVE 标识符、OWASP Top 10 类别、证据和补救指南 发现支持 `owasp_category` 字段，用于将漏洞映射到 OWASP Top 10（例如“A03:2021 Injection”）。 ## 输出解析器 每个安全工具都有一个结构化的输出解析器，用于从原始工具输出中提取关键数据： - **nmap** -- 带有 NSE 脚本提取的 XML 解析器（按 CVSS 排序的 vulners CVE） - **nuclei** -- 带有严重性过滤的 JSONL 解析器 - **nikto/feroxbuster/ffuf/masscan** -- 具有可配置结果上限的面向行的解析器 - **sqlmap** -- 注入类型和参数提取 - **testssl** -- 漏洞和证书发现提取 - **hydra/whatweb** -- 凭据和技术识别 - **subfinder/dnsrecon/dnsx** -- 子域名和 DNS 记录提取 - **httpx/katana** -- HTTP 指纹和爬取 endpoint 提取 - **dalfox/wpscan/enum4linux-ng/john** -- 结构化发现提取 所有解析器都返回 `Option`，并在解析失败时回退到原始输出。结果限制会根据当前活动的预算模式动态缩放。 ## 认证扫描 `http_request` 工具维护一个共享的 cookie jar，该 cookie jar 在会话内以及上下文清除后仍然持久存在（保存到磁盘）。外部子进程工具（sqlmap、nikto、feroxbuster 等）不共享此 jar —— 请通过每个工具的 `cookie` 参数传递 cookie。 ## 测试 跨 3 个 crate 的 314 个单元和集成测试： ``` cargo test --workspace ``` | Crate | 测试数 | |-------|-------| | raven-core | 88 | | raven-report | 54 | | raven-server | 162 | | 集成 | 10 | 还提供了一个基于 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, 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 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/USAGE.md) -- 工具安装、配置参考、完整参数文档 - [docs/LOCAL_AI_INTEGRATION.md](docs/LOCAL_AI_INTEGRATION.md) -- 将 Raven Nest 与本地模型（Ollama、LM Studio）配合使用 - [docs/METASPLOIT.md](docs/METASPLOIT.md) -- Metasploit Framework 集成设置与安全模型 - [docs/DATA_FLOW.md](docs/DATA_FLOW.md) -- 数据流和单一事实来源：哪个模块拥有每部分状态 - [CHANGELOG.md](CHANGELOG.md) -- 发布历史（当前版本：v0.2.0） ## License [Apache-2.0](LICENSE)

标签：MCP服务器, Rust, StruQ, XXE攻击, 事件响应, 人工智能, 可视化界面, 威胁模拟, 实时处理, 密码管理, 用户模式Hook绕过, 网络流量审计, 请求拦截, 通知系统