pentest-mcp-server

---

仅限授权使用。 此服务专为渗透测试人员、红队成员、CTF 参与者、安全研究人员和学生设计，供其测试自有系统或已获得明确书面授权的系统。用户须自行负责确保测试合法且范围适当。未经授权访问计算机系统属于违法行为——此服务不会、也无法代替你验证授权。

双重受众设计。 每种攻击技术都配有检测指标和缓解措施。蓝队成员、开发人员以及任何构建检测覆盖能力的人，都能发现其中的方法论和 ATT&CK 数据与红队工作流同样有用。

---

概述

这是一款面向授权渗透测试、CTF 和安全研究的离线方法论引擎，基于 MITRE ATT&CK、OWASP 测试指南和附注载荷模板构建。生成分阶段测试计划、将技术映射到目标、分析 HTTP 响应以查找信息泄露，并生成或编码载荷；每项功能都附有检测和缓解说明。

工具

工具	描述
pentest_get_guide	针对所选攻击向量的授权测试方法指南，按阶段筛选，并为每种技术提供检测和缓解措施。
pentest_analyze_response	分析授权探测获取的原始 HTTP 响应标头/正文，检查信息泄露、指纹识别和配置错误。
pentest_lookup_technique	按 ID 或关键词查询 MITRE ATT&CK 技术，并提供检测数据、缓解措施和操作示例。
pentest_lookup_group	按 ID 或名称查询 MITRE ATT&CK 威胁组织或软件条目，并提供别名和技术使用情况。
pentest_map_techniques	根据目标配置（技术栈、服务、身份验证类型、操作系统）对 ATT&CK 技术和 OWASP 测试用例进行排序。
pentest_generate_payloads	为漏洞类别和注入上下文生成带注释的载荷模板，并可选提供 WAF 绕过变体和编码。
pentest_encode_payload	对载荷字符串按顺序应用编码链，并跟踪解码路径。

功能参考

pentest_get_guide _tool

• vector：auth_bypass、idor、ssrf、xss、sqli、xxe、path_traversal、cors、csrf、open_redirect、deserialization、race_condition、ssti、command_injection 或 jwt_attack；phase：all（默认）、recon、enumeration、exploitation 或 post_exploitation
• 指南中的技术包含 detection 和 mitigation，以及 owasp_references、attack_technique_ids 和基于上下文的 nextToolSuggestions
• 可选的 target_context（stack、waf、recon_notes）可缩小指南范围

---

pentest_analyze_response _tool

• 提供 response_headers（≤20,000 个字符）、response_body（≤10,000 个字符）或两者；可选提供 status_code（100–599）和 context（≤2,000 个字符）。如果两个响应字段都缺失，则返回 no_input
• 发现结果包含 category、severity（info/low/medium/high）、detection 和 remediation，并按严重程度降序排列
• fingerprints（server_software、framework、language、database、cloud_provider、other）和 nextToolSuggestions 支持后续调用

---

pentest_lookup_technique _tool

• 提供 ATT&CK ID（T1190、T1059.001）或关键词；include_subtechniques 默认为 true
• 返回战术、平台、描述、detection（summary、data_sources、indicators）、缓解措施、操作示例和 attack_version
• 如果 ID 或关键词无法匹配任何结果，则返回 no_match

---

pentest_lookup_group _tool

• 提供 ATT&CK 组织 ID（G0007）、软件 ID（S0002）或名称/关键词；如果无法匹配任何结果，则返回 no_match
• type 用于区分 group 和 software；结果包含 aliases、description（≤800 个字符）和 attack_version
• techniques_used 最多返回 20 项技术，包含操作上下文，以及供 pentest_lookup_technique 使用的 technique_id

---

pentest_map_techniques _tool

• 至少提供 stack、services、auth_type（jwt/session_cookie/api_key/oauth2/basic_auth/ntlm/kerberos/none/unknown）或 os（linux/windows/macos/unknown）中的一项；否则返回 no_profile
• ranked_techniques 包含 relevance_score、relevance_rationale、detection_opportunity、mitigation_summary 和可选的 pentest_guide_vector；owasp_test_cases 最多返回 10 项用例
• limit 将技术数量限制为 1–50 项（默认 15）；补充信息（truncated、shown、cap）会说明上限

---

pentest_generate_payloads _工具

• category：xss、sqli、ssrf、xxe、path_traversal、ssti、command_injection、open_redirect、csrf、deserialization、jwt、ldap_injection、nosql_injection 或 http_header；injection_context：html_attribute、html_body、js_string、js_template、js_script_block、url_parameter、url_path、sql_where、sql_integer、xml_element、xml_attribute、http_header、json_value、cookie_value、file_name 或 generic
• count 将模板数量限制为 1–20（默认值为 5）；每个模板都包含 detection_signature 和 mitigation，还可选择将 encoding 应用于每个模板
• waf_profile：cloudflare、aws_waf、modsecurity_crs、imperva、akamai、f5_bigip_asm、nginx_modsecurity、fortinet_fortiWAF、none（默认值）或 unknown；除 none 外的配置会添加 waf_bypass_note

---

pentest_encode_payload _工具

• payload 最多接受 10,000 个字符；chain 从左到右应用 1–6 个步骤，可选项为 url、double_url、html_entity、unicode、hex、base64、js_escape、null_byte、mixed_case 或 comment_break
• 返回 intermediate_steps 和 detection_note；explain（默认值为 true）会添加 decode_path 和 bypass_rationale
• 转换失败时返回 encoding_error

---

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

特定于方法论的功能：

• 运行时完全离线——不调用外部 API，无需凭据；所有数据均在启动时加载，请求处理期间不进行任何 I/O
• 在构建时通过 scripts/refresh-attack.ts 嵌入 MITRE ATT&CK Enterprise 数据，并按 ID/关键词建立内存索引；若缺少数据文件，则会立即报错并提供可操作的提示
• OWASP Testing Guide 方法论和载荷模板库以结构化 TypeScript 模块的形式整理，每个向量/类别对应一个模块
• 按 WAF 产品和攻击向量索引 WAF 绕过变体，并引用公开研究
• 所有工具均标注 readOnlyHint: true、openWorldHint: false——基于范围有限的内嵌数据集生成确定性输出

面向 Agent 的输出：

• 每个指南/载荷/编码响应的 content[] 首行都会显示 authorized_use_reminder——无论客户端转发哪个界面中的内容，提示格式都保持一致
• 技术和载荷需要包含检测与缓解背景；响应发现结果需要包含 detection 和 remediation
• 每个由 ATT&CK 支持的响应都会回传 attack_version，便于调用方了解数据版本
• nextToolSuggestions 会预先填入根据当前上下文生成的参数，减少 Agent 的规划开销

---

构建时数据步骤

服务器会将 MITRE ATT&CK Enterprise 数据（约 20 MB 的 JSON）内嵌；数据由一次性脚本下载到 Git 忽略的路径。自托管用户和 Docker 构建者必须在服务器启动前运行此步骤：

bun run scripts/refresh-attack.ts

此操作会从 MITRE GitHub 发布端点下载最新的 ATT&CK Enterprise JSON，将其写入 src/data/attack/enterprise.json（Git 忽略），并使用类似 Enterprise v16.1 的版本字符串更新 src/data/attack/version.ts。版本文件会提交到仓库；JSON 不会提交（文件过大，不适合纳入 Git 历史记录）。

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
# Server listens at http://localhost:3010/mcp

先决条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 已填充 ATT&CK 数据 — 克隆后运行一次 bun run scripts/refresh-attack.ts（Docker 构建会自动处理）。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/pentest-mcp-server.git

2. 进入目录：

cd pentest-mcp-server

3. 安装依赖项：

bun install

4. 填充 ATT&CK 数据：

bun run scripts/refresh-attack.ts

5. 配置环境：

cp .env.example .env
# edit .env if needed — no required vars beyond transport defaults

---

配置

无需 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
PENTEST_ENABLE_PAYLOAD_GENERATION	启用 pentest_generate_payloads 和 pentest_encode_payload；设为 false 时，这些工具将对客户端隐藏。	true
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
OTEL_ENABLED	启用 OpenTelemetry 检测（跨度、指标、完成日志）。	false
LOG_TOOL_FAILURE_PAYLOADS	记录调用失败时的参数和结果（键名会被隐藏；自由格式的值仍可能包含机密）。	false
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	OTLP 日志导出目标。	—

完整的可选覆盖项列表请参阅 .env.example。

设置 PENTEST_ENABLE_PAYLOAD_GENERATION=false 后，MCP 发现中将不包含这两个载荷工具，也无法调用它们。

---

运行服务

本地开发

• 构建并运行：

  # Seed ATT&CK data (first time, or to update)
  bun run scripts/refresh-attack.ts
  
  # Build
  bun run rebuild
  
  # Run
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security audit
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions
  

Docker

# Build — ATT&CK data is fetched during the build stage
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 服务 — 启动时加载并索引内嵌的企业版 JSON。
src/services/methodology/	OWASP Testing Guide 方法论服务 — 为 pentest_get_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（由 scripts/refresh-attack.ts 获取并被 git 忽略）+ 已提交的 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 并更新版本字符串。克隆后运行一次，之后每季度运行一次。
scripts/copy-attack.ts	编译后将预置的 ATT&CK 数据集复制到 dist/。
tests/	与 src/ 结构对应的单元测试和集成测试。
docs/design.md	设计文档 — 工具接口、数据策略和架构决策。

---

开发指南

请参阅 CLAUDE.md，了解开发指南和架构规则。简要说明：

• 处理器抛出异常，由框架捕获；仅在将自行负责的操作失败转换为已声明的 ctx.fail 契约时才捕获异常
• 使用 ctx.log 记录请求范围内的日志，并确保请求处理无状态且具有确定性
• 通过 src/mcp-server/tools/index.ts 中的汇总导出注册新工具
• 外部数据源边界：验证原始数据，将其规范化为领域类型，然后返回输出架构；绝不虚构缺失字段
• 每个生成方法论或 Payload 内容的工具都必须包含 authorized_use_reminder 输出字段 — 在 format() 中将其作为每个 content[] 响应的第一行
• 技术和 Payload 必须包含检测与缓解上下文；响应发现项必须包含 detection 和 remediation

---

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

---

许可证

Apache-2.0 — 详情请参阅 LICENSE。