DefectDojo MCP 服务器

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

本项目为流行的开源漏洞管理工具 DefectDojo 提供了一个 模型上下文协议 (MCP) 服务器实现。它允许 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: 检索具有过滤 (product_name, status, severity) 和分页 (limit, offset) 的发现项。
• search_findings: 使用文本查询搜索发现项，具有过滤和分页功能。
• update_finding_status: 更改特定发现项的状态 (例如，Active, Verified, False Positive)。
• add_finding_note: 向发现项添加文本注释。
• create_finding: 创建与测试关联的新发现项。
• list_products: 列出具有过滤 (name, prod_type) 和分页的产品。
• list_engagements: 列出具有过滤 (product_id, status, name) 和分页的活动。
• get_engagement: 按 ID 获取特定活动的详细信息。
• create_engagement: 为产品创建新的活动。
• update_engagement: 修改现有活动的详细信息。
• close_engagement: 将活动标记为已完成。

(有关每个工具的详细使用示例，请参见下面的原始 README 内容)

使用示例

(注意：这些示例假定 MCP 客户端环境能够调用 use_mcp_tool)

获取发现项

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

搜索发现项

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

更新发现项状态

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

向发现项添加注释

result = await use_mcp_tool("defectdojo", "add_finding_note", {
    "finding_id": 123,
    "note": "Confirmed vulnerability on staging server."
})

创建发现项

result = await use_mcp_tool("defectdojo", "create_finding", {
    "title": "Reflected XSS in Search Results",
    "test_id": 55, # 关联测试的 ID
    "severity": "Medium",
    "description": "User input in search is not properly sanitized, leading to XSS.",
    "cwe": 79
})

列出产品

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

列出活动

# 列出产品 ID 为 42 的 'In Progress' 活动
result = await use_mcp_tool("defectdojo", "list_engagements", {
    "product_id": 42,
    "status": "In Progress"
})

获取活动

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

创建活动

result = await use_mcp_tool("defectdojo", "create_engagement", {
    "product_id": 42,
    "name": "Q2 Security Scan",
    "target_start": "2025-04-01",
    "target_end": "2025-04-15",
    "status": "Not Started"
})

更新活动

result = await use_mcp_tool("defectdojo", "update_engagement", {
    "engagement_id": 101,
    "status": "In Progress",
    "description": "Scan initiated."
})

关闭活动

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 文件。

贡献

欢迎贡献！请随时提出关于错误、功能请求或问题的 issue。如果您想贡献代码，请先打开一个 issue 来讨论建议的更改。