DefectDojo Intelligence MCP Server

一个基于 DefectDojo OSS v2.58.4 REST API v2 的保留权限的 Model Context Protocol 服务器。它与官方 DefectDojo Pro 内置 MCP 服务器实现 1:1 能力对等（12 个读取工具 + 一个 Security Landscape 提示词），并增加了一个确定性的分析/报告功能超集；它实现为外部适配器，因为内置的 Pro MCP 需要 Pro 版且实例版本需 v2.51.2+，并且在 OSS 2.58.4 主机上不可用。

每次调用都使用调用者自己的 DefectDojo API 令牌，因此可见性由 DefectDojo 决定。令牌仅保存在内存中，从不记录日志，从不发送给 LLM。

• 状态： 阶段 0–4 已完成、加固并完成容器化。140 个测试，ruff 零告警。

• 部署： 容器化 https://dojo.example.com/mcp/ 方案见 deploy/DEPLOY.md。注意：该部署启用了写入和 DB 历史工具组（见 安全模型 和 DEPLOY.md）。规格见 PRD.md。

工具

26 个工具 — 默认开启 20 个（14 个读取 + 6 个分析/报告），默认关闭 6 个。另有 1 个 MCP 提示词原语。

分析工具在服务器端确定性计算（无 LLM，无编造数据——每个数字都可追溯到 findings-API 查询）并返回类型化、结构化输出。SLA 使用 DefectDojo 自己的 outside_of_sla 过滤器；优先级排序使用真实的 KEV/EPSS/SLA 信号。

Related MCP server: mcp-vulbox-agent

与 Pro 的能力对等

安全模型

• 令牌： Authorization: Token <token>（不是 Bearer）。HTTP 按请求从入站请求头中读取（即调用者自己的令牌）；stdio 读取 DD_API_TOKEN。在 streamable-http 上，环境变量回退被禁用——无 Authorization 头或请求头损坏的请求会被拒绝，绝不会静默以服务器的环境变量令牌运行。

• 池化下的令牌隔离： 共享连接池使用 no-store cookie jar，因此上游的 Set-Cookie 绝不会在不同调用者令牌之间重放。认证鉴权仅在每个请求内生效。

• 校验： 令牌在首次工具调用前按 TTL 校验一次（缓存基于 128 位指纹，绝不缓存令牌本身；缓存有界）。

• 脱敏： 当设置了 redact_secrets/treat_finding_text_as_untrusted 时，对所有工具的输出统一应用——清除秘密（包括 URL 中内嵌的凭据），设置 omit_user_pii 时剥离 PII，自由文本截断为 max_evidence_chars。

• 错误： 失败（401/403/404/超时/……）以 MCP 工具错误（isError）形式呈现，而不是成功载荷，因此客户端不会把拒绝误认为数据。

• 写入： 默认关闭；启用后，每次写入都要求非空原因 + 显式 confirm=true（否则为无操作预览），并带有写前后状态哈希审计。仅限 REST API —— 绝不直接写数据库。

• DB 历史： 默认关闭；每个工具先通过 REST 授权对象，然后只读取允许列表中的只读视图（绝无任意 SQL）。

• 传输： streamable-http 从 mcp.allowed_hosts/allowed_origins 获得显式的 TransportSecuritySettings（DNS 重绑定/Origin 保护）；环回地址始终对健康检查开放。

• 已弃用端点（credentials、credential_mappings、stub_findings）被阻止；注册时对不允许工具列表进行断言。

• 审计： 每次工具调用输出一条结构化 JSON 事件，写入 stderr（stdout 是 MCP 流）。

加固

对瞬态 GET 失败（429/502/503/504/超时；遵循 Retry-After，包括 HTTP-date 格式；从不重试写入或 4xx）进行有界重试/退避 · 进程级并发 Semaphore · 共享池化 httpx 客户端（按请求鉴权，在 lifespan 关闭时关闭） · 按令牌的角色 TTL 缓存。见 tests/test_hardening.py。

生产部署（容器化，/mcp/）

完整指南：deploy/DEPLOY.md。简单来说：

cd deploy
# Optional: set DOJO_NETWORK / DD_URL / DD_MCP_REPORTING_DB_DSN in a deploy/.env
# (docker compose reads ${...} env defaults; there is no committed .env template —
#  config lives in deploy/config.prod.yaml, bind-mounted at /app/config.yaml).
docker compose up -d --build
curl -s http://127.0.0.1:9900/healthz   # -> {"status":"ok","transport":"streamable-http"}

然后把 deploy/nginx-mcp.conf 中的 location ~ ^/(mcp|sse|messages) 块添加到主机 nginx 并重新加载。客户端使用自己的 Authorization: Token <token>（通过 mcp-remote）连接到 https://dojo.example.com/mcp/。容器在容器内部绑定 0.0.0.0:9000，仅在主机上以 127.0.0.1:9900 发布，并在内部通过 http://nginx:8080 访问 DefectDojo。生产配置启用了写入和 DB 历史工具组（enable_write_tools / enable_db_tools）；写入仍以确认门控，DB 工具先进行 API 授权——见 DEPLOY.md。

本地开发

阶段 0 — 首先验证真实 schema

DD_URL=https://dojo.internal DD_API_TOKEN=xxxx ./scripts/check_schema.sh

确认所需的 collection 端点存在并标出已弃用端点。src/defectdojo_mcp/tools/* 中的 DRF filter lookups 已对照 DefectDojo 2.58.4 源码验证——请在此针对你的真实 schema 重新确认。

安装与运行

pip install -e ".[dev]"
cp config.example.yaml config.yaml          # edit base_url
# stdio reads the token from the DD_API_TOKEN env var (and DD_URL) directly — no .env file.

# stdio (single user / desktop client)
DD_URL=https://dojo.internal DD_API_TOKEN=xxxx DD_MCP_CONFIG=config.yaml defectdojo-mcp

# streamable-http (multi-user; token per-request). Set mcp.allowed_hosts for a 0.0.0.0 bind.
DD_MCP_TRANSPORT=streamable-http DD_MCP_HOST=0.0.0.0 DD_MCP_PORT=9000 defectdojo-mcp
# endpoint: http://<host>:9000/mcp   health: http://<host>:9000/healthz

Claude Desktop (stdio)

{
  "mcpServers": {
    "defectdojo": {
      "command": "defectdojo-mcp",
      "env": {
        "DD_URL": "https://dojo.internal",
        "DD_API_TOKEN": "your-token",
        "DD_MCP_CONFIG": "/path/to/config.yaml"
      }
    }
  }
}

测试

pytest          # 140 tests: redaction/sanitize, params, paging, auth+validator, context,
                # server gating, intelligence scoring, source resolution, writes, history,
                # hardening (retry/pool/semaphore/cache)
ruff check .

配置

关键 config.yaml 配置项（见 config.example.yaml / deploy/config.prod.yaml）：

• mcp.transport（stdio | streamable-http）、mcp.host/port

• mcp.enable_write_tools, mcp.enable_db_tools — 控制默认关闭的工具组

• mcp.enable_dns_rebinding_protection, mcp.allowed_hosts, mcp.allowed_origins

• security.redact_secrets, omit_user_pii, require_confirmation_for_writes

• limits.max_concurrent_api_calls, max_retries, max_evidence_chars, roles_cache_ttl_seconds

• database.enabled, dsn_env, allowed_views（阶段 3 报告数据库）

可发现性与可扩展性

每个工具都带有 ToolAnnotations（readOnlyHint/idempotentHint/title）；枚举参数发布枚举；列表工具声明类型化的 Page 输出 schema；服务器对外发布 instructions；提示词包含标题和带文档的参数。工具通过 server.py 中的 (module, predicate) 注册表注册（每个可选组只有一个默认关闭的开关）；ServerContext.execute() / execute_db_gated() / execute_write() 是令牌校验、统一出口转换、审计和错误映射的关键点。

许可证

GNU Affero General Public License v3.0 only（AGPL-3.0-only）。完整文本见 LICENSE。

版权（C）2026 Zeeshan Sultan。

安全

请私下报告漏洞——见 SECURITY.md。不要为安全问题公开 issue。

相关项目

与 ShadowDSO 一同构建，这是一个以 DefectDojo 作为记录系统的带外安全扫描平台。本服务器独立存在，不依赖它。