pb3ck/modus

# Modus [](https://github.com/pb3ck/modus/actions/workflows/ci.yml) [](./LICENSE) [](./pyproject.toml) Modus 是一个用于授权漏洞赏金和渗透测试工作的自主攻击性安全 Agent。该 Agent 基于 Quarry 语料库进行推理，针对范围内的目标提出类型化的 action，在执行前对每个 action 进行形式化验证，并将其发现作为 Candidate 写入语料库。Modus 作为一个 **MCP server** 交付：操作员可以通过任何支持 MCP 的宿主环境（Claude Desktop、Claude Code、Cursor 以及任何支持 Model Context Protocol 的环境）来驱动它。Agent 的自主循环在 Modus 内部端到端运行——宿主环境只需启动它并读取结果。自主循环在语料库内闭环处理 Candidate→Finding 生命周期：严重程度为中等及以上的 Candidate 会通过 `corpus.promote_finding` 自动提升为 Finding，该操作由 Quarry 的 MCP `finding_promote` 写入工具提供支持。唯一的一道硬性人工关卡在于漏洞赏金提交：**Modus 绝不向赏金计划提交。** 注册表中不存在 `submit`、`publish`、`post`、`report-to-h1` 或任何等效工具，且添加此类工具是被严格禁止的。向计划提交 Finding 是操作员的职责，需在 Modus 之外执行。 ## 这是什么 - **一个带有开放工具注册表的自主 Agent。** 操作员将其 MCP 宿主环境指向 Modus 并调用 autonomous-session 工具。Modus 在内部运行 propose-prune-rank-execute 循环，调用操作员注册的所有工具：侦察 shell（`amass`、`nuclei`）、类型化 action 表面（`probe`、`request`、`compare`、`differential`、`annotate`、`hypothesize`）、Quarry 的语料库工具、宿主端的 MCP server，以及操作员在其范围文件的 `tools` 块中声明的任何自定义 shell 或 MCP 工具。Agent 不受封闭语法的限制；它受限于注册表所暴露的内容。（有关从封闭的 v0.1 词汇表转型的信息，请参见 ADR-0004。） - **在交付形式上，是一个 MCP server。** 完整的工具表面——类型化 action、通用 `tool` 调度、Quarry 透传、autonomous-session 控制（start / poll / cancel / run / propose）——均注册为 MCP 工具。希望获得完全透明度的操作员可以从宿主端逐步驱动各个工具；希望获得自主性的操作员可以调用 `start_autonomous_session` 并让循环自行运行。 - **感知 Quarry，但非 Quarry 原生。** Quarry 的分析模块和读取表面是一等公民级别的工具注册（`corpus.search`、`analyze_jsdelta` 等，通过 Modus 的 MCP server 进行代理）。Quarry 是默认的存储后端和跨项目记忆库；Modus 依赖于它，但不从属于其数据模型。其他工具的观察结果与 Quarry 的记录行并列存在于同一个会话内池中。 - **由注册表成员资格强制执行的提交防火墙。** 默认注册表中没有注册任何 `submit`、`report`、`publish`、`post` 或 `report-to-h1` 工具，并且添加此类工具在项目策略中是被严格禁止的。Agent 可以发出具有任何名称的 `Tool` action，但如果该名称不在注册表中，一致性层将以 `tool_registered:` 拒绝执行。该防火墙涵盖的是*外部提交*（至漏洞赏金平台），而不是内部晋升：`corpus.promote_finding` 内置工具在本地语料库内，针对严重程度为中等及以上的 Candidate 闭环了 Candidate→Finding 生命周期，这是语料库内部操作，而不是出站 action。向赏金计划提交 Finding 是操作员的职责，需在 Modus 之外执行。 ## 这不是什么 - 不是扫描器。Modus 根据当前语料库的状态推理下一步该做什么，并且它可以将扫描器作为已注册的工具（`nuclei.scan`、`amass.enum` 以及任何操作员声明的工具）来驱动。扫描器是*肌肉*；Modus 的自主循环是*方向*。没有这个循环，扫描器只会产生噪音。 - 不是语料库。Quarry 是默认的存储后端；Modus 的会话内观察池会刷新到 Quarry 以实现跨会话记忆。Modus 不重复 Quarry 的数据摄入或其 Finding 生命周期。 - 不是模型包装器。Modus 为其自主循环配备了专属的 LLM 提供商，但它是提供商可移植的：支持直接 API（Anthropic、OpenAI）、OpenAI 兼容接口（通过 `base_url` 的 Ollama、vLLM、OpenRouter）、MCP 宿主采样（当宿主支持时）或 `claude-cli`——一种按订阅计费的路径，它通过 shell 调用 Claude Code 的 `claude --print`，这样拥有 Claude Pro/Max 订阅的操作员就无需按 token 付费。宿主的 LLM 和 Modus 的 LLM 是独立的，由操作员分别做出选择。 - 不是聊天机器人。Modus 的自主工具返回的是结构化的 Candidate 批次，而不是叙述性回复。宿主的对话发生在操作员与宿主的 LLM 之间；Modus 是外挂在一旁的攻击引擎。 - 不是提交器。永远不是。观察与推荐之间的界限是由存储层而非 prompt 强制执行的：Modus 中没有“发布”路径，而且永远不会有。 ## 为什么存在 自主攻击工具领域已经收敛出一种形态：处于自由形式 ReAct 循环中的 LLM、shell 字符串工具调度、会话范围的记忆、作为审计表面的思维链追踪，以及以逐步操作员审批作为安全关卡。这种形态在演示中表现良好。但它无法与专业操作员的纪律相组合，因为 Agent 的推理被锁定在模型内部，记录系统是一个扁平的日志文件，而安全关卡正是 Agent 旨在倍增其注意力的同一个人。 Modus 押注了一条不同的道路，分为五个部分。 - Action 表面是一个**类型化的注册表**。Agent 发出的每个 action 都是经过 Pydantic 验证的 `Tool(name, args)`（或类型化 action 的快捷方式——`Probe`、`Request` 等）。注册表声明了哪些 `name` 值是可调度的，以及每个工具的 `args` 形状是怎样的；添加新功能只需操作员在范围文件的 `tools` 块中编写一个条目。封闭的 v0.1 词汇表已经不复存在；信任边界就是注册表的内容。 - 一致性检查是**形式化且针对每个工具的**。每个拟定的 action 在产生任何副作用之前，都会通过 SMT solver 根据范围和语料库状态进行验证。每个工具规范都声明了自己的前置条件函数（注册表是 Z3 的调度表）；内置工具附带了范围限制前置条件（`amass.enum` 要求域名在范围内，`nuclei.scan` 要求 URL 的 `(host, port, tls)` 位于 `allowed_endpoints` 中）。自主循环将 Z3 用作*采样提议的修剪器*。 - 语料库是 **Quarry**。跨项目记忆、结构化存储和分析模块（`analyze_regression` / `analyze_jsdelta` / `analyze_interesting`）都位于 Quarry 中，并通过 Modus 的工具注册表作为 `corpus.*` 条目暴露出来。审查 Modus 的操作可以通过 `quarry session show` 或 SQLite 查询完成，而不是通过抓取日志。 - Agent **通过 MCP 交付**。操作员选择宿主环境（Claude Desktop、Claude Code、Cursor 或任何感知 MCP 的宿主）；宿主选择其运行的模型。Modus 自身的内部 LLM（由自主循环使用）是操作员通过环境变量做出的独立且提供商可移植的选择。Modus 在任何一侧都不锁定于特定提供商。 - 提交边界是**结构性的**。默认注册表中没有注册任何 `submit`、`publish`、`post`、`report` 或 `report-to-h1` 工具，并且添加此类工具在项目策略中是被严格禁止的。Agent 可以发出具有任何名称的 `Tool` action，但如果它不在注册表中，一致性层将以 `tool_registered:` 拒绝。该防火墙涵盖的是*外部提交*（至漏洞赏金平台），而不是内部晋升：Candidate→Finding 的晋升是语料库内部的，并且自主循环会通过 `corpus.promote_finding` 对严重程度为中等及以上的 Candidate 闭环此过程。向赏金计划提交是操作员的事，需在 Modus 之外执行。 这五项承诺是不变量。特定的 MCP 宿主、特定的 LLM 提供商、特定的 Z3 编码、v0.1 范围内的漏洞类别——所有这些都可能发生变化。但不变量不会。 ## 它如何运作 ``` operator │ ▼ ┌────────────────────┐ ┌─────────────────────────┐ │ MCP host │ │ modus-side LLM │ │ (Claude Desktop, │ │ (Anthropic API, │ │ Claude Code, │ │ OpenAI API, │ │ Cursor, ...) │ │ OpenAI-compat: Ollama,│ │ │ │ vLLM, OpenRouter, │ │ │ │ Claude Code │ │ │ │ subscription) │ └────────┬───────────┘ └────────▲────────────────┘ │ │ │ MCP (stdio, JSON-RPC) │ used inside ▼ │ autonomous loop ┌────────────────────────────────────────┴─────────┐ │ modus mcp │ │ │ │ autonomous-session tools typed-action │ │ (start / poll / cancel / run / surface + │ │ propose) generic tool │ │ │ │ │ │ ▼ ▼ │ │ ┌────────────────────────────────────┐ │ │ │ Z3 consistency check ──┐ │ │ │ │ (per-tool preconds) ▼ │ │ │ │ ┌──────────────┐ │ │ │ │ │ ToolRegistry │ │ │ │ │ └──────┬───────┘ │ │ │ └─────────────────────────┼──────────┘ │ │ ▼ │ │ ┌─────────────────┐ │ │ │ ToolExecutor │ │ │ └─┬──────┬──────┬─┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ shell builtin mcp │ │ (amass, nuclei, …) (request, hypoth) (host MCP) └───────────────┬──────────────────┬───────────────┘ ▼ ▼ in-scope target quarry mcp │ ▼ Quarry corpus (SQLite) │ ▼ Candidates │ ▼ corpus.promote_finding (severity ≥ medium, in-loop) │ ▼ Findings │ ▼ (operator submits to programme — outside Modus) ``` 每一个 action——类型化 action 快捷方式或通用 `tool` 调度——都流经同一个注册表驱动的 Z3 检查，然后流经 `ToolExecutor`，最后到达三个后端之一。Quarry 是众多后端之一（针对 `corpus.*` 注册表条目的 `builtin` 调用）；侦察 shell（`amass`、`nuclei`）以及任何操作员声明的工具共享此路径。ADR-0004 记录了从封闭的 v0.1 词汇表向此形态的转型。 操作员在其宿主的设置中将 Modus 配置为 MCP server。两种常见配置如下： ``` // Per-token API billing (any MCP host) { "mcpServers": { "modus": { "command": "modus", "args": ["mcp", "--scope", "/path/to/scope.json"], "env": { "QUARRY_HOME": "/path/to/quarry/home", "MODUS_LLM_PROVIDER": "anthropic", "ANTHROPIC_API_KEY": "sk-ant-..." } } } } ``` ``` // Subscription billing via Claude Pro/Max (requires Claude Code installed) { "mcpServers": { "modus": { "command": "modus", "args": ["mcp", "--scope", "/path/to/scope.json"], "env": { "QUARRY_HOME": "/path/to/quarry/home", "MODUS_LLM_PROVIDER": "claude-cli", "MODUS_LLM_BASE_URL": "/path/to/claude" } } } } ``` `claude-cli` 提供商通过 shell 调用 `claude --print` 处理每次 proposer 调用。这会在每步增加约 3 秒的 Node 启动开销，但费用计入 Claude Pro/Max 订阅，而不是按 API token 计费。这是针对尚未实现 `sampling/createMessage` 功能的 MCP 宿主的变通方法——截至 2026-05-08，Anthropic 的客户端（Claude Desktop 和 Claude Code）都属于此类。 随后，宿主将看到 Modus 的工具表面——autonomous-session 工具和经过验证的 action 工具——操作员可以通过普通的宿主对话进行驱动。完整设置请参见 [`docs/mcp-host-integration.md`](./docs/mcp-host-integration.md)。 ## 操作员工具 除了 MCP server 之外，Modus 还提供了一个小型 CLI，用于处理不属于 Agent 循环内部的操作员准备工作： - `modus action validate ` —— 针对静态 action + 状态规范运行一致性层；打印每个 action 的判定结果。适用于离线测试范围策略。 - `modus corpus status` —— 健全性检查，确认 Modus 可以连接到 Quarry 二进制文件并且语料库处于健康状态。 - `modus partition --input --output-dir ` —— 使用已维护的 DO-NOT-TOUCH（禁止触碰）令牌列表（作战司令部、ITAR、`.gov.`、PIV/CAC 部署前缀），将侦察主机名分类为 Tier A/B/C。操作员需根据 `tier-a.txt` 手动编写 `allowed_assets`；这是一个推荐工具，不能替代一致性层的允许列表。闭环了在连续两次项目中暴露的分区错误类 bug。 - `modus mcp --scope ` —— 启动 MCP server（这是宿主通过 `mcpServers.modus.command` 启动的命令）。 对任何子命令使用 `--help` 获取完整的选项列表。 ## 范围 ### 漏洞类别 Modus 的证据模式库涵盖了八类漏洞，带有标准的识别模板和严重性默认值： `auth_bypass`、`idor`、`info_disclosure`、`sqli`、`ssrf`、`xss`、`csrf`、`business_logic`。当 LLM 持续放弃推理时，模式回退 proposer 会对前四类漏洞触发；当操作员将 `bug_classes` 传递给 `run_autonomous_session` 时，prompt 模板会为所有八类漏洞进行渲染。Modus 仅限于 Web 领域——不涉及二进制漏洞利用、不涉及权限提升、不涉及智能合约。 ### v0.1 MCP 宿主 Claude Desktop 是主要的宿主目标——这是 Modus 设计时所针对的形态。任何其他感知 MCP 的宿主（Claude Code、Cursor、Continue、Zed）只要实现了标准的 MCP stdio 传输协议，都可以正常工作。常见宿主的配置片段请参见 [`docs/mcp-host-integration.md`](./docs/mcp-host-integration.md)。 ### LLM 提供商（Modus 内部，用于自主会话） 通过 `MODUS_LLM_PROVIDER` 提供的五种提供商模式： - `anthropic` —— 直接使用 Anthropic API。按 token 计费。推荐拥有 API key 和项目预算的操作员作为默认选项。 - `openai` / `openai-compatible` —— 涵盖 OpenAI 本身通过 `base_url` 连接的任何 OpenAI 兼容端点（Ollama、vLLM、OpenRouter）。本地模型操作员使用此模式指向 Ollama；M7 模式回退 proposer 弥补了中等规模开源权重模型在多步推理中遇到的决断力不足问题。 - `host` —— 通过 `sampling/createMessage` 将每次 proposer 调用委托给 MCP 宿主的 LLM。原则上按订阅计费。目前通过 Anthropic 客户端不可行（已验证 2026-05-08：Claude Desktop 和 Claude Code v2.1.136 均返回 JSON-RPC `-32601 "Method not found"`）；当支持采样的 MCP 宿主可用时才可使用。 - `claude-cli` —— 针对 `host` 模式空白的子进程变通方案。每次 proposer 调用都通过 shell 调用 `claude --print`，利用 Claude Code 的 OAuth/钥匙串认证进行订阅计费。每步增加约 3 秒的 Node 启动开销，但统一按 Claude Pro/Max 订阅计费。 提供商可移植的 proposer 是 Modus 唯一的内部 LLM 选择；宿主的 LLM 选择是独立的，不受 Modus 控制。 ### v0.1 语料库 任何实现了已文档化语料库接口的 MCP server。参考依赖是 Quarry；Modus 消费的确切工具表面请参见 [`docs/corpus-interface.md`](./docs/corpus-interface.md)。 ## 非目标 - 在基准测试分数上与商业自主渗透测试工具竞争。Modus 押注的是 Agent 的*形态*，而不是原始的召回率。 - 自动将 Findings 提交给漏洞赏金计划。永远不。在任何里程碑下。在任何标志下。注册表中不存在 `submit`、`publish`、`post`、`report` 或 `report-to-h1` 工具，并且永远不会添加。提交边界是*外部的*——Modus 在本地语料库内对严重程度为中等及以上的 Candidate 闭环了 Candidate→Finding 生命周期，但向计划提交 Finding 是操作员的事，需在 Modus 之外执行。 - 在未经操作员审查的情况下生成完成、可提交的报告文本。Findings 包含供操作员进行分诊的结构化基本原理；将分诊后的集合转换为面向赏金计划的提交包是操作员的工作。 - 在操作员定义的范围之外运行。范围被编码为一致性层中的前置条件；Agent 无法针对范围外的资产提出提议，更不用说执行了。 - 取代 Quarry。Modus 依赖于 Quarry；它不重复其数据摄入、检索、分析模块或 Finding 生命周期。 - 取代宿主。Modus 不实现聊天 UI、审批提示 UX 或模型选择菜单。那是宿主的工作。 ## 状态与路线图 v0.1 的骨架正在搭建中。Action 词汇表、一致性层、MCP corpus 客户端和 proposer 抽象正在陆续落地；MCP server 和 autonomous-session 工具将闭环此流程。里程碑规划请参见 [`ROADMAP.md`](./ROADMAP.md)，促成此阶段的各种架构决策请参见 [`docs/adr/`](./docs/adr/)。 ## 许可证 AGPL-3.0-or-later。参见 [`LICENSE`](./LICENSE)。 选择 AGPL 是深思熟虑的：Modus 是攻击性安全基础设施，作为服务部署的修改版本应回馈社区。Modus 是纯 FOSS——没有双许可模式，也没有商业许可选项。 ## 贡献 暂未开放。该仓库尚处于初始布局阶段；一旦 v0.1 拥有了可用的基线，将欢迎提交 PR。在此期间，欢迎提出 Issues 和进行设计讨论。参见 [`CONTRIBUTING.md`](./CONTRIBUTING.md)。 ## 仅限授权使用 Modus 专为授权的安全测试而构建——具有书面安全港条款的漏洞赏金计划、具有书面授权的渗透测试，以及您自己的基础设施。在大多数司法管辖区，针对您没有明确测试许可的系统使用 Modus 是非法的，本项目不提供任何支持。

标签：amass, Bug Bounty, Claude Code, MCP, nuclei, Petitpotam, Python, Quarry, Recon, Ruby, TIP, Windows内核, 可自定义解析器, 安全合规, 实时处理, 密码管理, 形式化验证, 插件系统, 数据展示, 无后门, 模型上下文协议, 漏洞报告, 白帽子, 知识库, 红队, 网络代理, 网络安全, 自主智能体, 订阅计费, 资产收集, 逆向工具, 隐私保护