DefectDojo API v2 使用指南:安全风险管理自动化接口详解
什么是DefectDojo API v2
DefectDojo是一个开源的缺陷管理平台,其API v2版本基于Django Rest Framework构建,为安全团队和开发人员提供了自动化风险管理的能力。通过这套API,用户可以实现:
- 自动化上传安全检查报告
- 集成到CI/CD流水线中
- 批量管理缺陷数据
- 与其他安全工具集成
API文档访问与交互
DefectDojo安装后自带交互式API文档,访问路径为/api/v2/oa3/swagger-ui
。这份文档采用drf-spectacular生成,支持OpenAPI v3规范,具有以下特点:
- 可视化操作界面:文档界面直观展示所有可用端点
- 实时测试功能:可直接在界面上发起API调用
- 响应预览:显示请求URL、响应体、状态码和头部信息
- 自动授权:如果已登录Web UI,无需额外提供令牌
认证机制详解
API v2采用基于令牌的认证方式,开发者需要:
- 访问
/api/key-v2
生成API密钥 - 在请求头部添加认证信息:
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:
- 请求方法:POST
- 请求地址:
http://your-dojo-instance/api/v2/import-scan/
- 头部设置:
Authorization: Token your_api_key_here
- 表单数据(以ZAP扫描为例):
engagement:3 verified:true active:true scan_type:ZAP Scan minimum_severity:Info
- 文件上传:添加文件参数并选择扫描报告
客户端库与集成方案
DefectDojo社区提供了多种语言的客户端库:
- Python专用封装:功能完整,包含CI/CD上传脚本
- Java客户端:由SecureCodeBox团队维护,稳定性高
- .NET/C#库:通过NuGet分发,适合.NET生态系统
- dd-import工具:简化CI/CD流水线中的扫描结果导入
最佳实践建议
- 自动化集成:将API调用集成到CI/CD流程中,实现安全左移
- 令牌管理:定期轮换API密钥,避免长期使用同一令牌
- 错误处理:实现健壮的错误处理逻辑,特别是网络请求和响应解析
- 性能考虑:对于大批量操作,考虑使用分页和异步处理
- 测试策略:先在小规模环境测试API调用,再应用到生产环境
通过合理利用DefectDojo API v2,安全团队可以显著提升风险管理效率,实现安全流程的自动化与标准化。
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考