defectdojo

DefectDojo 技能

概述

DefectDojo 是一个开源的 DevSecOps、应用安全态势管理（ASPM）和漏洞管理平台。它可编排端到端的安全测试、漏洞跟踪、去重、修复和报告。

主要功能：

• 统一管理 200 多种安全工具发现的漏洞
• 自动导入扫描结果并进行去重
• 集成 CI/CD 流水线
• 双向 JIRA 集成
• 基于角色的访问控制
• SLA 跟踪和报告
• 用于自动化的 REST API v2
• 用于集成 Claude Code 的 MCP 工具

官方资源：

• 文档：https://docs.defectdojo.com/
• GitHub：https://github.com/DefectDojo/django-DefectDojo
• 演示：https://demo.defectdojo.org（admin / 1Defectdojo@demo#appsec）

MCP 工具（主要接口）

此技能提供 12 个 MCP 工具，可直接与 DefectDojo API 交互。请使用这些工具，而非手动调用 API。

读取操作

工具	描述	关键参数
defectdojo_list_products	列出并搜索产品	name_contains、prod_type、limit
defectdojo_get_product	获取产品详细信息	product_id（必填）
defectdojo_list_engagements	按筛选条件列出参与项	product_id、status、engagement_type
defectdojo_list_tests	列出参与项中的测试	engagement_id、test_type
defectdojo_list_findings	主要工具 - 搜索发现项	severity、active、product_id、cwe
defectdojo_get_finding	获取发现项详情	finding_id（必填）
defectdojo_get_statistics	漏洞统计信息	product_id、engagement_id
defectdojo_list_endpoints	列出产品端点	product_id、host、protocol
defectdojo_list_test_types	列出扫描器类型	name_contains

写入操作

工具	描述	关键参数
defectdojo_create_engagement	创建新的参与项	product_id、name、engagement_type
defectdojo_update_finding	更新发现项状态	finding_id、active、verified、false_p
defectdojo_close_engagement	关闭参与项	engagement_id

使用示例

列出所有严重级别的活动发现项：

Use defectdojo_list_findings with:
- severity: "Critical"
- active: true

获取产品的漏洞统计信息：

Use defectdojo_get_statistics with:
- product_id: 1

搜索 SQL 注入发现项：

Use defectdojo_list_findings with:
- cwe: 89
- active: true

将发现项标记为误报：

Use defectdojo_update_finding with:
- finding_id: 123
- false_p: true
- active: false

创建 CI/CD 参与项：

Use defectdojo_create_engagement with:
- product_id: 1
- name: "Pipeline Security Scan"
- engagement_type: "CI/CD"

响应格式

所有工具均通过 response_format 参数支持两种输出格式：

• markdown（默认）- 易于阅读的格式化输出
• json - 用于程序化处理的原始 JSON

MCP 服务配置

MCP 服务在 .mcp.json 中配置：

{
  "mcpServers": {
    "defectdojo": {
      "command": "python",
      "args": [".claude/mcp-servers/defectdojo-mcp/defectdojo_mcp.py"],
      "env": {
        "DEFECTDOJO_URL": "https://defectdojo.dev.example.com",
        "DEFECTDOJO_API_TOKEN": "${DEFECTDOJO_API_TOKEN}"
      }
    }
  }
}

环境变量：

• DEFECTDOJO_URL - 你的 DefectDojo 实例 URL
• DEFECTDOJO_API_TOKEN - 来自 /api/key-v2 的 API 令牌

数据模型（产品层级结构）

DefectDojo 使用五种相互关联的数据类别来组织安全工作：

Product Type
    └── Product
        └── Engagement (CI/CD or Interactive)
            └── Test
                └── Finding
                    └── Endpoint

产品类型

最高层级的组织结构，按业务领域、团队或安全区域对产品进行分类。可在类别级别启用基于角色的访问控制。

产品

正在接受安全测试的独立应用或系统。每个产品都维护：

• 自身的测试历史记录
• 去重范围（发现项在产品内去重）
• SLA 配置
• 团队分配

参与项

包含一个或多个测试的计划测试周期。分为两种类型：

类型	用途	使用场景
CI/CD	自动化流水线集成	每次构建/提交时执行自动扫描
Interactive	工程师手动测试	渗透测试、手动审查

测试

按工具类型分组的独立安全扫描。测试支持：

• 重新导入（将发现项添加到现有测试中）
• 环境标记
• 版本跟踪

发现项

测试期间发现的具体漏洞：

严重程度	描述
严重	需要立即处理
高	高优先级修复
中	标准优先级
低	低优先级
信息	仅供参考

发现项状态：

• 活动 / 非活动
• 已验证 / 未验证
• 重复
• 已缓解
• 误报
• 已接受风险
• 超出范围

端点

对受影响主机、URL 或系统的引用。可按基础设施组件跟踪漏洞。

API v2 参考

**注意：**对于大多数操作，请使用上方的 MCP 工具，而不要直接调用 API。仅在导入扫描或执行 MCP 工具未覆盖的操作时，才直接调用 API。

身份验证

在此处生成 API 令牌：<your-instance>/api/key-v2

# Header format
Authorization: Token <api_key>

环境变量：

• DD_API_TOKENS_ENABLED=False - 完全禁用 API 令牌
• DD_API_TOKEN_AUTH_ENDPOINT_ENABLED=False - 仅禁用令牌身份验证端点

核心端点

端点	方法	用途
/api/v2/import-scan/	POST	初次导入扫描
/api/v2/reimport-scan/	POST	后续导入（去重）
/api/v2/products/	GET/POST	管理产品
/api/v2/engagements/	GET/POST	管理项目
/api/v2/tests/	GET/POST	管理测试
/api/v2/findings/	GET/POST/PATCH	管理发现项
/api/v2/endpoints/	GET/POST	管理端点
/api/v2/users/	GET	列出用户

导入扫描参数

curl -X POST "https://defectdojo.example.com/api/v2/import-scan/" \
  -H "Authorization: Token <api-token>" \
  -F "scan_type=<scanner-type>" \
  -F "[email protected]" \
  -F "engagement=<engagement-id>" \
  -F "minimum_severity=Info" \
  -F "active=true" \
  -F "verified=false" \
  -F "scan_date=2024-01-15"

关键参数：

参数	描述
scan_type	扫描器标识符（例如，“Trivy Scan”、“Semgrep JSON Report”）
engagement	目标项目 ID
test_title	自定义测试名称
minimum_severity	筛选阈值（信息、低、中、高、严重）
active	将发现项标记为活动状态（布尔值）
verified	将发现项标记为已验证（布尔值）
scan_date	覆盖扫描完成日期
do_not_reactivate	防止重新打开已关闭的发现项
auto_create_context	缺少产品或项目时自动创建

重新导入扫描（去重）

curl -X POST "https://defectdojo.example.com/api/v2/reimport-scan/" \
  -H "Authorization: Token <api-token>" \
  -F "scan_type=Trivy Scan" \
  -F "[email protected]" \
  -F "test=<test-id>" \
  -F "do_not_reactivate=true"

重新导入端点会：

• 检测新发现项与现有发现项
• 更新现有发现项
• 关闭新扫描中不存在的发现项
• 在 auto_create_context=true 时自动创建上下文

交互式 API 文档

访问 Swagger UI：<your-instance>/api/v2/oa3/swagger-ui/

CI/CD 集成

流水线集成模式

# GitLab CI Example
stages:
  - security-scan
  - upload-results

trivy-scan:
  stage: security-scan
  script:
    - trivy image --format json -o trivy-results.json $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
  artifacts:
    paths:
      - trivy-results.json

upload-to-defectdojo:
  stage: upload-results
  script: |
    curl -X POST "${DEFECTDOJO_URL}/api/v2/reimport-scan/" \
      -H "Authorization: Token ${DEFECTDOJO_API_TOKEN}" \
      -F "scan_type=Trivy Scan" \
      -F "[email protected]" \
      -F "product_name=${CI_PROJECT_NAME}" \
      -F "engagement_name=CI/CD-${CI_PIPELINE_ID}" \
      -F "auto_create_context=true" \
      -F "minimum_severity=Low"

Jenkins 集成

从 https://plugins.jenkins.io/defectdojo/ 安装 DefectDojo Jenkins 插件。

流水线配置：

pipeline {
    agent any
    environment {
        DEFECTDOJO_URL = 'https://defectdojo.example.com'
        DEFECTDOJO_API_KEY = credentials('defectdojo-api-key')
    }
    stages {
        stage('Security Scan') {
            steps {
                sh 'trivy image --format json -o trivy.json myapp:latest'
            }
        }
        stage('Upload to DefectDojo') {
            steps {
                defectDojoPublisher(
                    artifact: 'trivy.json',
                    productName: 'MyApp',
                    scanType: 'Trivy Scan',
                    engagementName: "Build-${BUILD_NUMBER}"
                )
            }
        }
    }
}

GitHub Actions 集成

name: Security Scan
on: [push]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Trivy
        uses: aquasecurity/trivy-action@master
        with:
          scan-type: 'fs'
          format: 'json'
          output: 'trivy-results.json'

      - name: Upload to DefectDojo
        run: |
          curl -X POST "${{ secrets.DEFECTDOJO_URL }}/api/v2/reimport-scan/" \
            -H "Authorization: Token ${{ secrets.DEFECTDOJO_TOKEN }}" \
            -F "scan_type=Trivy Scan" \
            -F "[email protected]" \
            -F "product_name=${{ github.repository }}" \
            -F "engagement_name=GitHub-${{ github.run_id }}" \
            -F "auto_create_context=true"

Python API 示例

**提示：**对于 Claude Code 交互，请使用 MCP 工具（defectdojo_list_findings 等），而不要编写 Python 代码。以下示例适用于 CI/CD 脚本和外部集成。

基本 API 连接

import requests

class DefectDojoAPI:
    def __init__(self, url, api_token):
        self.url = url.rstrip('/')
        self.headers = {
            'Authorization': f'Token {api_token}',
            'Accept': 'application/json'
        }

    def get_products(self):
        response = requests.get(
            f'{self.url}/api/v2/products/',
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

    def import_scan(self, engagement_id, scan_type, file_path, **kwargs):
        with open(file_path, 'rb') as f:
            data = {
                'engagement': engagement_id,
                'scan_type': scan_type,
                'minimum_severity': kwargs.get('minimum_severity', 'Info'),
                'active': kwargs.get('active', True),
                'verified': kwargs.get('verified', False),
            }
            files = {'file': f}
            response = requests.post(
                f'{self.url}/api/v2/import-scan/',
                headers={'Authorization': self.headers['Authorization']},
                data=data,
                files=files
            )
        response.raise_for_status()
        return response.json()

# Usage
api = DefectDojoAPI('https://defectdojo.example.com', 'your-api-token')
products = api.get_products()

创建产品和项目

def create_product(api, name, prod_type_id, description=''):
    response = requests.post(
        f'{api.url}/api/v2/products/',
        headers=api.headers,
        json={
            'name': name,
            'prod_type': prod_type_id,
            'description': description
        }
    )
    response.raise_for_status()
    return response.json()

def create_engagement(api, product_id, name, target_start, target_end,
                      engagement_type='CI/CD'):
    response = requests.post(
        f'{api.url}/api/v2/engagements/',
        headers=api.headers,
        json={
            'name': name,
            'product': product_id,
            'target_start': target_start,
            'target_end': target_end,
            'engagement_type': engagement_type,
            'status': 'In Progress'
        }
    )
    response.raise_for_status()
    return response.json()

查询发现项

def get_findings(api, product_id=None, severity=None, active=True):
    params = {'active': active}
    if product_id:
        params['test__engagement__product'] = product_id
    if severity:
        params['severity'] = severity

    response = requests.get(
        f'{api.url}/api/v2/findings/',
        headers=api.headers,
        params=params
    )
    response.raise_for_status()
    return response.json()

# Get all critical findings
critical = get_findings(api, severity='Critical')

支持的安全工具（200+）

SAST / 代码分析

• Bandit、Checkmarx、Fortify、SonarQube、Semgrep
• CodeQL、Horusec、Brakeman、SpotBugs

依赖项 / SCA

• Snyk、OWASP Dependency-Check、Dependency-Track
• npm Audit、pip-audit、Trivy、Safety

DAST / Web 扫描

• Burp Suite、OWASP ZAP、Nikto、Nessus
• Qualys、OpenVAS、Acunetix、AppScan

容器 / 基础设施

• Trivy、Aqua、Anchore、Wiz、NeuVector
• kube-bench、Kubescape、Prisma Cloud

密钥检测

• Gitleaks、Trufflehog、Detect-secrets
• GitHub Secret Scanning

云安全

• AWS Inspector、AWS Prowler、ScoutSuite
• Azure Security Center、Checkov

IaC 扫描

• Checkov、Terrascan、KICS、TFSec、Dockle

完整列表：https://docs.defectdojo.com/supported_tools/

JIRA 集成

配置

1. 在系统设置中启用：

   Configuration > System Settings > Enable JIRA Integration
   

2. 添加 JIRA 实例：

   Enterprise Settings > JIRA Instances > + New JIRA Instance
   

3. 配置 Webhook（双向同步）：

   • 在 JIRA 中创建 Webhook，指向： https://<defectdojo>/jira/webhook/<webhook-secret>
   • 在 DefectDojo 中启用：“Enable JIRA web hook”

环境变量

extraEnv:
  - name: DD_JIRA_URL
    value: "https://your-jira.atlassian.net"
  - name: DD_JIRA_MAX_RETRIES
    value: "3"

功能

• 将发现项作为问题推送到 JIRA
• 双向同步评论
• JIRA 问题关闭时自动关闭发现项
• 通过 JIRA 评论发送 SLA 通知

项目文件位置

文件类型	路径
ApplicationSet	infra-team/applicationset/defectdojo.yaml
Helm Values	argo-cd-helm-values/kube-addons/defectdojo/<cluster>/values.yaml
SecretProviderClass	argo-cd-helm-values/kube-addons/defectdojo/<cluster>/secretproviderclass.yaml

环境配置

集群	Key Vault	Azure AD 租户 ID
example-app-dev	kv-example-dev-hlg	<TENANT_ID>

Azure AD 应用注册

设置	值
应用程序（客户端）ID	<AZURE_AD_APP_ID>
租户 ID	<TENANT_ID>
重定向 URI	https://defectdojo.dev.example.com/complete/azuread-tenant-oauth2/

Azure AD SSO 配置

必需的环境变量

extraEnv:
  # Enable Azure AD OAuth2
  - name: DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_ENABLED
    value: "True"
  # Application (Client) ID
  - name: DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_KEY
    value: "<client-id>"
  # Directory (Tenant) ID
  - name: DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_TENANT_ID
    value: "<tenant-id>"
  # Client Secret (from Key Vault)
  - name: DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_SECRET
    valueFrom:
      secretKeyRef:
        name: defectdojo
        key: DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_SECRET

组同步

extraEnv:
  # Sync groups from Azure AD token
  - name: DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_GET_GROUPS
    value: "True"
  # Remove users from groups when removed in Azure AD
  - name: DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_CLEANUP_GROUPS
    value: "True"
  # Filter to only sync DefectDojo groups
  - name: DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_GROUPS_FILTER
    value: "^G-Usuarios-DefectDojo-.*"

必需的 Azure AD 权限（应用程序类型，需管理员同意）：

• Group.Read.All
• GroupMember.Read.All
• User.Read.All

有关 Azure AD SSO 的完整详情，请参阅 references/azure-ad-sso.md。

DefectDojo 角色

角色	权限
超级用户	完整的系统访问权限、管理用户、系统设置
所有者	删除产品、指定其他所有者
维护者	编辑产品、添加成员、删除发现项
撰写者	添加/编辑参与、测试、发现项
读者	仅查看、添加评论
API 导入者	为 CI/CD 管道提供有限的 API 访问权限

用于角色映射的 Azure AD 组

Azure AD 组	DefectDojo 角色
G-Usuarios-DefectDojo-Superuser	超级用户
G-Usuarios-DefectDojo-Owner	所有者
G-Usuarios-DefectDojo-Maintainer	维护者
G-Usuarios-DefectDojo-Writer	撰写者
G-Usuarios-DefectDojo-Reader	读者

Helm Chart 快速参考

关键值

# Host configuration
host: defectdojo.dev.example.com
siteUrl: https://defectdojo.dev.example.com

# Secrets (use CSI driver)
createSecret: false
disableHooks: true

# Django
django:
  replicas: 1
  ingress:
    enabled: true
    activateTLS: true
    className: nginx

# Celery (keep beat at 1 replica)
celery:
  beat:
    enabled: true
    replicas: 1
  worker:
    enabled: true
    replicas: 1

# Database
postgresql:
  enabled: true

# Cache
redis:
  enabled: true

有关 Helm 值的完整参考，请参阅 references/helm-values.md。

Kubernetes 部署

基本 Helm 安装

git clone https://github.com/DefectDojo/django-DefectDojo
cd django-DefectDojo

helm install defectdojo ./helm/defectdojo \
  -n defectdojo --create-namespace \
  --set django.ingress.enabled=true \
  --set django.ingress.activateTLS=false \
  --set createSecret=true \
  --set createRabbitMqSecret=true \
  --set createPostgresqlSecret=true

访问 DefectDojo

kubectl port-forward --namespace=defectdojo service/defectdojo-django 8080:80

密钥管理

密钥通过 Azure Key Vault CSI Driver 管理：

Key Vault 密钥	K8s 密钥键	用途
defectdojo-admin-password	DD_ADMIN_PASSWORD	管理员用户密码
defectdojo-secret-key	DD_SECRET_KEY	Django 密钥
defectdojo-credential-aes-key	DD_CREDENTIAL_AES_256_KEY	凭据加密
defectdojo-azuread-client-secret	DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_SECRET	Azure AD 客户端密钥

常见故障排除

SSO 登录后用户未加入组

现象： 用户通过 Azure AD 登录，但显示“未找到组成员”

解决方案：

1. 验证 DD_SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_GET_GROUPS=True
2. 检查 Azure AD API 权限（Group.Read.All 已获管理员同意）
3. 验证 Azure AD 令牌包含组声明（而非角色声明）
4. 用户必须先退出登录再重新登录，以同步组
5. 在 DefectDojo UI 中创建匹配的组

HTTPS 重定向 URI 不匹配（ADSTS50011）

错误：“请求中指定的重定向 URI 不匹配”

**解决方案：**确保设置以下内容：

- name: DD_SESSION_COOKIE_SECURE
  value: "True"
- name: DD_CSRF_COOKIE_SECURE
  value: "True"
- name: DD_SECURE_PROXY_SSL_HEADER
  value: "True"

ERR_TOO_MANY_REDIRECTS

原因： TLS 终止代理下设置了 DD_SECURE_SSL_REDIRECT=True

**解决方案：**在 NGINX Ingress 后方时，将 DD_SECURE_SSL_REDIRECT=False

紧急登录访问

如果 SSO 出现故障，可访问标准登录表单：

https://defectdojo.dev.example.com/login?force_login_form

完整的故障排查指南请参阅 references/troubleshooting.md。

实用命令

检查 Pod 状态

KUBECONFIG=~/.kube/aks-rg-example-dev-config kubectl get pods -n defectdojo

查看日志

KUBECONFIG=~/.kube/aks-rg-example-dev-config kubectl logs -n defectdojo -l app.kubernetes.io/name=defectdojo -c uwsgi

重启部署

KUBECONFIG=~/.kube/aks-rg-example-dev-config kubectl rollout restart deployment/defectdojo-django -n defectdojo

其他参考资料

MCP 服务

• MCP 服务 README - MCP 服务的设置和使用
• MCP 服务源代码 - 服务实现

技能参考资料

• Azure AD SSO 配置 - 完整的 SSO 设置指南
• Helm Values 参考 - 完整的 Helm chart 配置
• 故障排查指南 - 常见问题及解决方案
• API v2 参考 - 完整的 API 文档
• CI/CD 集成指南 - 流水线集成模式

外部资源

• 官方文档
• Swagger UI - 交互式 API 文档

---

注意事项

• 去重按产品进行，而非全局进行： 两个产品中的同一个 CVE 会被计数两次，导致产品组合指标虚高。如果需要全局计数，请通过 hash_code 算法配置跨产品去重。
• reimport-scan 会静默关闭缺失的发现项： 重新导入不完整的扫描结果（仅包含一个路径，而非完整扫描）时，所有未出现在新文件中的发现项都会自动关闭。请使用 do_not_reactivate=true 并谨慎限定测试范围。
• auto_create_context=true 遇到名称不一致时会创建重复产品： “MyApp”、“myapp”和“MyApp ”会生成三个产品。请在上游规范化 product_name，DefectDojo 不会进行模糊匹配。
• API 令牌的作用范围是用户，而非团队： 流水线令牌会继承创建者的全部权限。请创建专用的 CI 用户并授予 API Importer 角色，而不要重复使用个人令牌。
• 在 NGINX Ingress 后面设置 DD_SECURE_SSL_REDIRECT=True 会导致重定向循环： TLS 在 Ingress 处终止，随后 Django 又会将 HTTP 请求重定向到 HTTPS。请将其设为 False，并依靠 Ingress 强制执行 TLS。
• Azure AD 组同步仅在登录时触发： 将用户添加到 Azure AD 组不会自动同步现有用户；用户必须先退出再重新登录，DefectDojo 才能识别新的组成员身份。