## 工具 涵盖完整授权测试工作流的七个工具 — 从初始范围界定到响应分析和 payload 生成： | 工具 | 描述 | |:-----|:------------| | `pentest_guide` | 返回针对给定攻击向量的分步方法论手册，范围限定于授权测试。每个阶段涵盖需要关注的内容、工具、防御者的检测指标和缓解措施。 | | `pentest_analyze_response` | 分析来自授权探测的原始服务器响应（标头 + 主体），以发现信息泄露、指纹信号和漏洞利用机会 — 每个发现都配有修复建议。 | | `pentest_lookup_technique` | 通过 ID 或关键字查找 MITRE ATT&CK 技术。返回描述、战术、检测数据源、行为指标、缓解措施和真实世界的操作示例。 | | `pentest_lookup_group` | 通过 ID 或名称查找 MITRE ATT&CK 威胁组织或软件条目。返回别名、类型（组织还是软件）、描述，以及其使用的带有操作上下文的技术。 | | `pentest_map_techniques` | 给定目标配置文件（技术栈、服务、认证类型、OS），返回与该授权测试最相关的、排名靠前的 ATT&CK 技术和 OWASP 测试用例。 | | `pentest_generate_payloads` | 生成用于授权测试的带注释的 payload 模板。每个模板都包含其在注入上下文中起效的原因、检测特征和缓解措施。 | | `pentest_encode` | 对 payload 字符串应用编码链（URL、双重 URL、HTML 实体、Unicode、十六进制、Base64 等）。返回分步解码说明和绕过理由。 | ### `pentest_guide` 指令工具。返回针对给定向量和可选目标上下文的结构化攻击方法论手册。 - 通过单个 `vector` 枚举支持十五种攻击向量：`auth_bypass`, `idor`, `ssrf`, `xss`, `sqli`, `xxe`, `path_traversal`, `cors`, `csrf`, `open_redirect`, `deserialization`, `race_condition`, `ssti`, `command_injection`, `jwt_attack` - 可选的 `target_context`（`stack`、`waf`、`recon_notes`）将手册缩小至特定技术栈的技术和具备 WAF 绕过意识的变体 - 阶段过滤：`all`、`recon`、`enumeration`、`exploitation`、`post_exploitation` - 每个技术条目都包含检测指标和建议的缓解措施 — 可用作蓝队的规划辅助 - `nextToolSuggestions` 预先填充了来自方法论上下文的 payload 生成器和 ATT&CK 查找调用 - `authorized_use_reminder` 字段作为每次响应的第一行呈现，以便所有客户端都能接收到该框架设定 - 包含 OWASP 测试指南的测试用例 ID 和 ATT&CK 技术 ID，以便交叉引用 ### `pentest_analyze_response` 桥接工具。粘贴来自授权探测的原始 HTTP 输出；获取结构化的发现。 - 接受 `response_headers`（原始 HTTP 标头）、`response_body`（最多 10,000 个字符）、`status_code` 和自由格式的 `context` - 检测：版本披露、堆栈跟踪、内部路径、调试标头、技术指纹、认证模式、CORS 配置错误、缺失的安全标头、感兴趣的字段、错误消息 - 每个发现包含：类别、严重性（`info`/`low`/`medium`/`high`）、检测到什么、为何重要、防御者将如何检测漏洞利用以及修复方案 - 技术指纹摘要（`server_software`、`framework`、`language`、`database`、`cloud_provider`）可直接在 `pentest_guide` 或 `pentest_map_techniques` 中用作 `target_context` - `nextToolSuggestions` 根据指纹和发现预先填充 ### `pentest_lookup_technique` 单记录 ATT&CK 查找。接受精确 ID（`T1190`、`T1059.001`）或关键字搜索。 - 完整的技术记录：名称、战术、描述、目标平台 - 检测上下文：摘要、ATT&CK 数据源（日志源、传感器）、具体的行为指标 - 缓解措施：ATT&CK 缓解措施 ID、名称和描述 - 来自公开威胁情报报告的真实操作示例 - 子技术包含开关（`include_subtechniques`，默认为 `true`） - 每次响应中都包含 ATT&CK 数据集版本字符串，以便调用者了解数据的新鲜度 ### `pentest_lookup_group` ATT&CK 威胁组织和软件查找。接受精确 ID（`G0007`、`S0002`）或名称/关键字搜索（`APT28`、`Mimikatz`）。 - 同时涵盖入侵集合（威胁组织，G 前缀）和软件条目（恶意软件和工具，S 前缀） - 返回：名称、类型（`group` 或 `software`）、别名、描述，以及最多 20 项带有操作级别上下文的使用技术 - 技术条目直接链接到 `pentest_lookup_technique`，以获取完整的检测和缓解上下文 - 对于围绕特定对手传统技术构建检测覆盖范围的防御者同样有用 ### `pentest_map_techniques` 发现和排名工具。输入目标配置文件，返回已确定优先级的测试范围。 - 配置文件输入：`stack`（组件数组）、`services`（暴露的接口）、`auth_type`（jwt/session\_cookie/api\_key/oauth2/basic\_auth/ntlm/kerberos/none/unknown）、`os`（linux/windows/macos/unknown） - 透明的相关性评分：每个匹配的平台得 1 分，每个匹配的服务得 2 分，匹配的认证类型得 2 分 — 标准记录在每一行结果中，因此排名是可验证的 - 每项排名的技术包括：相关性理由、检测机会、缓解摘要，以及用于后续跟进的 `pentest_guide` 向量 - 将 OWASP 测试用例与 ATT&CK 技术一起映射到配置文件 - 可配置的结果数量（1–50，默认 15） ### `pentest_encode` 纯转换实用程序。将有序的编码链应用于 payload 字符串。 - 十种编码类型：`url`、`double_url`、`html_entity`、`unicode`、`hex`、`base64`、`js_escape`、`null_byte`、`mixed_case`、`comment_break` - 链接最多 6 个从左到右应用的步骤；返回中间值以供追踪 - 可选的分步解码说明（`explain`，默认为 `true`）：WAF 或服务器将如何反转每一层 - 绕过原理：为什么该编码组合可能会规避常见的过滤模式 - 每次响应中都包含 `detection_note` — 防御者如何检测编码的 payload 变体 — 从而保持双重受众定位 - 无实时探测 — 仅进行数学确定性的转换 ## 功能 - 声明式工具定义 — 每个工具一个文件，由框架负责注册和验证 - 统一的错误处理 — 处理程序抛出异常，由框架捕获、分类和格式化 - 带有可选 OpenTelemetry 追踪的结构化日志记录 - STDIO 和 Streamable HTTP 传输 渗透测试专属功能： - **运行时完全离线** — 无外部 API 调用，无需凭据。所有数据在启动时从内置模块加载；在处理请求期间零 I/O 操作 - **MITRE ATT&CK Enterprise** 在构建时通过 `scripts/refresh-attack.ts` 内置；启动时在内存中按 ID 和关键字进行索引。如果数据文件丢失，将快速失败并显示明确的提示信息 - **OWASP 测试指南方法论** 被精心整理为结构化的 TypeScript 模块，涵盖从侦察到后渗透阶段 - **Payload 模板库** 经过精心整理和注释的 TypeScript 模块，每个漏洞类别一个文件，适用于注入上下文 - **WAF 绕过知识** 以 WAF 产品和攻击向量为键，参考公开的研究 - **编码链引擎** — 纯 TypeScript 转换，带有完整的解码路径追踪 - 所有工具均被标注为 `readOnlyHint: true`、`openWorldHint: false` — 从有界的内置数据集中产生确定性输出 Agent 友好型输出： - `authorized_use_reminder` 作为每个 guide/payload/encoding 响应的 `content[]` 的第一行呈现 — 无论客户端转发的是哪个界面（结构化界面或文本界面），在所有 MCP 客户端中保持一致的框架设定 - 每个技术、发现和 payload 上都需要提供 `detection_note` 和 `mitigation` 字段 — 绝非可选 — 这样防御者总能与攻击技术一起获得可用的上下文 - 在 `pentest_map_techniques` 中进行透明的相关性评分 — 记录在案的标准，没有不透明的复合分数 - `nextToolSuggestions` 使用当前方法论上下文中的参数预先填充 — 减少了 agent 的规划开销 - 每个技术结果上都附有 ATT&CK 数据集版本字符串 — 调用者可以推断数据的新鲜度 ## 构建时的数据步骤 服务器内置了由一次性脚本获取的 MITRE ATT&CK Enterprise 数据（约 20 MB JSON），存放在一个 gitignored 路径中。**自托管者和 Docker 构建者必须在服务器启动前运行此步骤：** ``` bun run scripts/refresh-attack.ts ``` **Dockerfile 会自动处理这一过程** — 构建阶段会在 TypeScript 编译之前运行 `scripts/refresh-attack.ts`，因此 `docker build` 会生成一个独立的镜像。 如果您克隆了仓库并跳过了这一步，`attack-service` 将在启动时快速失败，并显示指向 `scripts/refresh-attack.ts` 的可操作错误消息。 每季度（或在每次发布之前）运行此脚本以拉取最新的 ATT&CK 版本。 ## 快速入门 ### 公共托管实例 公共实例可在 `https://pentest.caseyjhand.com/mcp` 找到 — 无需安装。通过 Streamable HTTP 将任何 MCP 客户端指向它： ``` { "mcpServers": { "pentest-mcp-server": { "type": "streamable-http", "url": "https://pentest.caseyjhand.com/mcp" } } } ``` ### 自托管 / 本地 将以下内容添加到您的 MCP 客户端配置文件中。 ``` { "mcpServers": { "pentest-mcp-server": { "type": "stdio", "command": "bunx", "args": ["@cyanheads/pentest-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info" } } } } ``` 或者使用 npx（不需要 Bun）： ``` { "mcpServers": { "pentest-mcp-server": { "type": "stdio", "command": "npx", "args": ["-y", "@cyanheads/pentest-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info" } } } } ``` 或者使用 Docker： ``` { "mcpServers": { "pentest-mcp-server": { "type": "stdio", "command": "docker", "args": [ "run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/pentest-mcp-server:latest" ] } } } ``` 对于 Streamable HTTP，请设置传输方式并启动服务器： ``` MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http # 服务器监听于 http://localhost:3010/mcp ``` ### 前置条件 - [Bun v1.3.0](https://bun.sh/) 或更高版本（或 Node.js v24+）。 - ATT&CK 数据已植入 — 克隆后运行一次 `bun run scripts/refresh-attack.ts`（Docker 构建会自动处理此步骤）。 ### 安装说明 1. **克隆代码库：** 2. **进入目录：** ``` cd pentest-mcp-server ``` 3. **安装依赖：** ``` bun install ``` 4. **植入 ATT&CK 数据：** ``` bun run scripts/refresh-attack.ts ``` 5. **配置环境：** ``` cp .env.example .env # 如有需要请编辑 .env — 除 transport 默认值外无必需变量 ``` ## 配置 无需 API 密钥。该服务器在运行时完全处于离线状态。 | 变量 | 描述 | 默认值 | |:---------|:------------|:--------| | `MCP_TRANSPORT_TYPE` | 传输方式：`stdio` 或 `http`。 | `stdio` | | `MCP_HTTP_PORT` | HTTP 服务器的端口。 | `3010` | | `MCP_AUTH_MODE` | 认证模式：`none`、`jwt` 或 `oauth`。 | `none` | | `MCP_LOG_LEVEL` | 日志级别：`debug`、`info`、`notice`、`warning`、`error`。 | `info` | | `LOGS_DIR` | 存放日志文件的目录（仅限 Node.js）。 | `/logs` | | `OTEL_ENABLED` | 启用 OpenTelemetry 监控（spans、metrics、completion logs）。 | `false` | 有关可选覆盖项的完整列表，请参见 [`.env.example`](./.env.example)。 ## 运行服务器 ### 本地开发 - **构建并运行：** # 植入 ATT&CK 数据（第一次运行，或用于更新） bun run scripts/refresh-attack.ts # 构建 bun run rebuild # 运行 bun run start:stdio # 或者 bun start:http - **运行检查和测试：** bun run devcheck # Lint、格式化、类型检查、安全审计 bun run test # Vitest 测试套件 bun run lint:mcp # 验证 MCP 定义 ### Docker ``` # 构建 — ATT&CK 数据将在 build 阶段获取 docker build -t pentest-mcp-server . docker run --rm -p 3010:3010 pentest-mcp-server ``` Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志输出到 `/var/log/pentest-mcp-server`。默认安装 OpenTelemetry 对等依赖项 — 使用 `--build-arg OTEL_ENABLED=false` 进行构建可忽略它们。ATT&CK 数据刷新会在构建阶段自动运行。 ## 项目结构 | 目录 / 文件 | 用途 | |:-----------------|:--------| | `src/index.ts` | `createApp()` 入口点 — 注册工具并初始化服务。 | | `src/services/attack/` | MITRE ATT&CK 服务 — 在启动时加载并索引内置的 enterprise JSON。 | | `src/services/methodology/` | OWASP 测试指南方法论服务 — 为 `pentest_guide` 提供向量分支。 | | `src/services/payload/` | Payload 模板服务 — 以类别和注入上下文为键。 | | `src/services/encoding/` | 编码链执行器 — 纯 TypeScript 转换。 | | `src/services/response-analysis/` | 用于信息泄露和指纹检测的模式库。 | | `src/mcp-server/tools/definitions/` | 工具定义（`*.tool.ts`） — 每个工具一个文件。 | | `src/data/attack/` | `enterprise.json`（已被 gitignore，由 `scripts/refresh-attack.ts` 获取） + 已提交的 `version.ts`。 | | `src/data/owasp/` | 以 TypeScript 模块形式整理的 OWASP TG v4.2 方法论内容。 | | `src/data/payloads/` | 按漏洞类别分类的带注释的 payload 模板。 | | `src/data/waf-bypass/` | 以产品和攻击向量为键的 WAF 绕过变体。 | | `src/data/encodings/` | 编码转换函数。 | | `src/data/patterns/` | 用于响应泄露检测的正则表达式模式和元数据。 | | `scripts/refresh-attack.ts` | 下载 ATT&CK Enterprise JSON 并更新版本字符串。克隆后运行一次，之后每季度运行一次。 | | `tests/` | 与 `src/` 对应的单元和集成测试。 | | `docs/design.md` | 设计文档 — 工具表面、数据策略和架构决策。 | ## 开发指南 有关开发指南和架构规则，请参见 [`CLAUDE.md`](./CLAUDE.md)。简短版本如下： - 处理程序抛出异常，由框架捕获 — 工具逻辑中不需要 `try/catch` - 使用 `ctx.log` 进行请求范围的日志记录，使用 `ctx.state` 进行租户范围的存储 - 通过 `src/mcp-server/tools/definitions/index.ts` 中的 barrel 文件注册新工具 - `authorized_use_reminder` 是每个生成方法论或 payload 内容的工具上必需的输出字段 — 请在 `format()` 中将其作为每个 `content[]` 响应的第一行呈现 - 每个技术、发现和 payload 对象都有必需的（非可选的）`detection` 和 `mitigation` 字段 — 这是一个模式契约，而不是文档指南 ## 许可证 Apache-2.0 — 有关详细信息，请参见 [LICENSE](LICENSE)。

标签：CISA项目, MCP, MITM代理, 用户代理, 自动化攻击, 请求拦截