DefectDojo API v2 使用指南：安全风险管理自动化接口详解

DefectDojo API v2 使用指南：安全风险管理自动化接口详解

django-DefectDojo ASPM, DevSecOps, Vulnerability Management. All on one platform. 项目地址: https://gitcode.com/gh_mirrors/dj/django-DefectDojo

什么是DefectDojo API v2

DefectDojo是一个开源的缺陷管理平台，其API v2版本基于Django Rest Framework构建，为安全团队和开发人员提供了自动化风险管理的能力。通过这套API，用户可以实现：

• 自动化上传安全检查报告
• 集成到CI/CD流水线中
• 批量管理缺陷数据
• 与其他安全工具集成

API文档访问与交互

DefectDojo安装后自带交互式API文档，访问路径为/api/v2/oa3/swagger-ui。这份文档采用drf-spectacular生成，支持OpenAPI v3规范，具有以下特点：

1. 可视化操作界面：文档界面直观展示所有可用端点
2. 实时测试功能：可直接在界面上发起API调用
3. 响应预览：显示请求URL、响应体、状态码和头部信息
4. 自动授权：如果已登录Web UI，无需额外提供令牌

认证机制详解

API v2采用基于令牌的认证方式，开发者需要：

1. 访问/api/key-v2生成API密钥
2. 在请求头部添加认证信息：

   Authorization: Token <your_api_key>
   

认证配置选项

对于使用SSO等替代认证方案的环境，可以通过以下环境变量控制API令牌：

• DD_API_TOKENS_ENABLED=False：完全禁用API令牌
• DD_API_TOKEN_AUTH_ENDPOINT_ENABLED=False：仅禁用令牌认证端点

实战代码示例

基础用户查询

import requests

url = 'http://your-dojo-instance/api/v2/users'
headers = {
    'content-type': 'application/json',
    'Authorization': 'Token your_api_key_here'
}
response = requests.get(url, headers=headers, verify=True)

# 处理响应数据
users = response.json()
for user in users:
    print(f"用户ID: {user['id']}, 用户名: {user['username']}")

带过滤条件的查询

import requests

url = 'http://your-dojo-instance/api/v2/users/?username__contains=admin'
headers = {
    'content-type': 'application/json',
    'Authorization': 'Token your_api_key_here'
}
response = requests.get(url, headers=headers, verify=True)

# 处理过滤后的用户数据
admin_users = response.json()

使用Postman测试API

对于手动测试API，可以按照以下步骤配置Postman：

1. 请求方法：POST
2. 请求地址：http://your-dojo-instance/api/v2/import-scan/
3. 头部设置：
   • Authorization: Token your_api_key_here
4. 表单数据（以ZAP扫描为例）：

   engagement:3
   verified:true
   active:true
   scan_type:ZAP Scan
   minimum_severity:Info
   

5. 文件上传：添加文件参数并选择扫描报告

客户端库与集成方案

DefectDojo社区提供了多种语言的客户端库：

1. Python专用封装：功能完整，包含CI/CD上传脚本
2. Java客户端：由SecureCodeBox团队维护，稳定性高
3. .NET/C#库：通过NuGet分发，适合.NET生态系统
4. dd-import工具：简化CI/CD流水线中的扫描结果导入

最佳实践建议

1. 自动化集成：将API调用集成到CI/CD流程中，实现安全左移
2. 令牌管理：定期轮换API密钥，避免长期使用同一令牌
3. 错误处理：实现健壮的错误处理逻辑，特别是网络请求和响应解析
4. 性能考虑：对于大批量操作，考虑使用分页和异步处理
5. 测试策略：先在小规模环境测试API调用，再应用到生产环境

通过合理利用DefectDojo API v2，安全团队可以显著提升风险管理效率，实现安全流程的自动化与标准化。

django-DefectDojo ASPM, DevSecOps, Vulnerability Management. All on one platform. 项目地址: https://gitcode.com/gh_mirrors/dj/django-DefectDojo