DefectDojo MCP 服务器

<!-- 如果/当发布到 PyPI 时添加此徽章 -->

该项目提供了一个针对 DefectDojo 的 Model Context Protocol (MCP) 服务器实现。DefectDojo 是一个流行的开源漏洞管理工具。它允许 AI 代理和其他 MCP 客户端通过编程方式与 DefectDojo API 进行交互。

功能

此 MCP 服务器提供了用于管理关键 DefectDojo 实体的工具：

• 发现（Findings）: 获取、搜索、创建、更新状态和添加注释。
• 产品（Products）: 列出可用的产品。
• 参与（Engagements）: 列出、检索详细信息、创建、更新和关闭参与。

安装及运行

有几种方法可以运行此服务器：

使用 uvx（推荐）

uvx 在临时虚拟环境中执行 Python 应用程序，并自动安装依赖项。

uvx defectdojo-mcp

使用 pip

您可以使用 pip 将包安装到您的 Python 环境中。

# 直接从克隆的源代码目录安装
pip install .

# 或者，如果该包已发布在 PyPI 上
pip install defectdojo-mcp

通过 pip 安装后，使用以下命令运行服务器：

defectdojo-mcp

配置

服务器需要以下环境变量来连接到您的 DefectDojo 实例：

• DEFECTDOJO_API_TOKEN（必需）：您的 DefectDojo API 令牌，用于身份验证。
• DEFECTDOJO_API_BASE（必需）：您的 DefectDojo 实例的基本 URL（例如，https://your-defectdojo-instance.com）。

您可以在 MCP 客户端的设置文件中配置这些变量。这里是一个使用 uvx 命令的例子：

{
  "mcpServers": {
    "defectdojo": {
      "command": "uvx",
      "args": ["defectdojo-mcp"],
      "env": {
        "DEFECTDOJO_API_TOKEN": "YOUR_API_TOKEN_HERE",
        "DEFECTDOJO_API_BASE": "https://your-defectdojo-instance.com"
      }
    }
  }
}

如果您是通过 pip 安装的包，配置如下所示：

{
  "mcpServers": {
    "defectdojo": {
      "command": "defectdojo-mcp",
      "args": [],
      "env": {
        "DEFECTDOJO_API_TOKEN": "YOUR_API_TOKEN_HERE",
        "DEFECTDOJO_API_BASE": "https://your-defectdojo-instance.com"
      }
    }
  }
}

可用工具

以下工具可通过 MCP 接口获得：

• get_findings: 检索发现（过滤条件：产品名称、状态、严重性），并支持分页（限制、偏移量）。
• search_findings: 使用文本查询搜索发现，支持过滤和分页。
• update_finding_status: 更改特定发现的状态（例如，活动、已验证、误报）。
• add_finding_note: 向发现添加文本注释。
• create_finding: 创建一个新的与测试相关的发现。
• list_products: 列出产品（过滤条件：名称、类型），并支持分页。
• list_engagements: 列出参与（过滤条件：产品ID、状态、名称），并支持分页。
• get_engagement: 根据其ID获取特定参与的详细信息。
• create_engagement: 为产品创建新的参与。
• update_engagement: 修改现有参与的详细信息。
• close_engagement: 标记参与已完成。

(参见下方原始README内容以获取每个工具的详细使用示例)

使用示例

(注意：这些示例假设有一个能够调用 use_mcp_tool 的 MCP 客户端环境)

获取发现

# 获取活动且高严重性的发现（限制10个）
result = await use_mcp_tool("defectdojo", "get_findings", {
    "status": "Active",
    "severity": "High",
    "limit": 10
})

搜索发现

# 搜索包含 'SQL 注入' 的发现
result = await use_mcp_tool("defectdojo", "search_findings", {
    "query": "SQL 注入"
})

更新发现状态

# 将发现 123 标记为已验证
result = await use_mcp_tool("defectdojo", "update_finding_status", {
    "finding_id": 123,
    "status": "已验证"
})

添加发现注释

result = await use_mcp_tool("defectdojo", "add_finding_note", {
    "finding_id": 123,
    "note": "确认了在测试服务器上的漏洞。"
})

创建发现

result = await use_mcp_tool("defectdojo", "create_finding", {
    "title": "搜索结果中的反射型XSS",
    "test_id": 55, # 关联测试的ID
    "severity": "中等",
    "description": "搜索中的用户输入未被正确清理，导致XSS。",
    "cwe": 79
})

列出产品

# 列出名称中包含 'Web App' 的产品
result = await use_mcp_tool("defectdojo", "list_products", {
    "name": "Web App",
    "limit": 10
})

列出参与

# 列出产品ID 42 的 '进行中' 状态的参与
result = await use_mcp_tool("defectdojo", "list_engagements", {
    "product_id": 42,
    "status": "进行中"
})

获取参与

result = await use_mcp_tool("defectdojo", "get_engagement", {
    "engagement_id": 101
})

创建参与

result = await use_mcp_tool("defectdojo", "create_engagement", {
    "product_id": 42,
    "name": "Q2安全扫描",
    "target_start": "2025-04-01",
    "target_end": "2025-04-15",
    "status": "未开始"
})

更新参与

result = await use_mcp_tool("defectdojo", "update_engagement", {
    "engagement_id": 101,
    "status": "进行中",
    "description": "扫描已启动。"
})

关闭参与

result = await use_mcp_tool("defectdojo", "close_engagement", {
    "engagement_id": 101
})

开发

设置

1. 克隆仓库。
2. 建议使用虚拟环境：

   python -m venv .venv
   source .venv/bin/activate # 在 Windows 上使用 `.venv\Scripts\activate`
   

3. 安装依赖项，包括开发依赖项：

   pip install -e ".[dev]"
   

许可证

本项目根据 MIT 许可证发布 - 详情请参阅 LICENSE 文件。

贡献

欢迎贡献！请随时打开一个问题报告错误、功能请求或问题。如果您想贡献代码，请先打开一个问题讨论拟议的更改。