/vuln-defectdojo

name: vuln-defectdojo
description: >
  Vulnerability management and findings aggregation using DefectDojo. Centralizes
  security findings from all SecOpsAgentKit scanners (Semgrep, Bandit, ZAP, Trivy,
  Grype, Gitleaks, Nuclei, Checkov, Horusec) into a unified platform with automatic
  deduplication, SLA tracking, risk-based prioritization, and compliance reporting.
  Use when: (1) Aggregating findings from multiple scanners across products and
  pipelines, (2) Tracking remediation status and SLA compliance against policy
  thresholds, (3) Deduplicating overlapping findings across security tools,
  (4) Generating vulnerability reports for compliance audits (SOC2, PCI-DSS, GDPR),
  (5) Managing security debt and vulnerability backlog across teams and applications.
version: 0.1.0
maintainer: SirAppSec
category: devsecops
tags: [vulnerability-management, defectdojo, findings-aggregation, deduplication, sla-tracking, risk-management, compliance-reporting]
frameworks: [OWASP, CWE, NIST, SOC2, PCI-DSS, GDPR]
dependencies:
  python: ">=3.9"
  packages: [requests]
  tools: [docker]
references:
  - https://defectdojo.github.io/django-DefectDojo/
  - https://github.com/DefectDojo/django-DefectDojo
  - https://owasp.org/www-project-defectdojo/

Vulnerability Management with DefectDojo

Overview

DefectDojo aggregates findings from every SecOpsAgentKit scanner into one platform—deduplicating across tools, tracking SLA compliance, and producing compliance-ready reports. It transforms isolated scanner outputs into a managed vulnerability backlog with ownership and remediation history.

Key concepts:

• **Product**: An application or system being tracked
• **Engagement**: A time-boxed security activity (sprint, assessment, CI/CD pipeline)
• **Test**: A scanner run within an engagement
• **Finding**: A deduplicated security issue with full lifecycle (Active → Mitigated → Closed)

Quick Start

Start DefectDojo locally:

git clone https://github.com/DefectDojo/django-DefectDojo.git
cd django-DefectDojo && docker compose up -d
# Access at http://localhost:8080 — change admin/admin password immediately

Import the first scan result:

pip install requests
./scripts/import_findings.py \
  --host http://localhost:8080 \
  --api-key <your-api-key> \
  --engagement-id 1 \
  --scan-type "Semgrep JSON Report" \
  semgrep-results.json

Retrieve your API key: **DefectDojo UI → User (top-right) → API v2 Key**.

Core Workflow

1. Setup: Products and Engagements

Create a Product (once per application) and an Engagement (once per sprint or pipeline):

# Create product
curl -s -X POST "$DD_HOST/api/v2/products/" \
  -H "Authorization: Token $DD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My App", "description": "Main application", "prod_type": 1}'

# Create engagement — use template for full options
curl -s -X POST "$DD_HOST/api/v2/engagements/" \
  -H "Authorization: Token $DD_API_KEY" \
  -H "Content-Type: application/json" \
  -d @assets/defectdojo-engagement-template.json

See [assets/defectdojo-engagement-template.json](assets/defectdojo-engagement-template.json) for a full CI/CD engagement template.

2. Import Scanner Findings

# Semgrep (SAST)
./scripts/import_findings.py --host $DD_HOST --api-key $DD_API_KEY \
  --engagement-id $EID --scan-type "Semgrep JSON Report" semgrep.json

# Trivy (containers/filesystem)
./scripts/import_findings.py --host $DD_HOST --api-key $DD_API_KEY \
  --engagement-id $EID --scan-type "Trivy Scan" trivy.json

# Gitleaks (secrets)
./scripts/import_findings.py --host $DD_HOST --api-key $DD_API_KEY \
  --engagement-id $EID --scan-type "Gitleaks Scan" gitleaks.json

# Re-import after fixes — auto-closes resolved findings
./scripts/import_findings.py --reimport --host $DD_HOST --api-key $DD_API_KEY \
  --engagement-id $EID --scan-type "Trivy Scan" trivy-new.json

For the complete mapping of every SecOpsAgentKit tool to its DefectDojo parser name and required output format, see [references/tool-parser-map.md](references/tool-parser-map.md).

3. CI/CD Pipeline Integration

Add an import step after each scanner in any pipeline:

# GitHub Actions — add after each scanner step
- name: Import findings to DefectDojo
  env:
    DD_HOST: ${{ secrets.DD_HOST }}
    DD_API_KEY: ${{ secrets.DD_API_KEY }}
    DD_ENGAGEMENT_ID: ${{ secrets.DD_ENGAGEMENT_ID }}
  run: |
    pip install requests
    ./scripts/import_findings.py \
      --host "$DD_HOST" \
      --api-key "$DD_API_KEY" \
      --engagement-id "$DD_ENGAGEMENT_ID" \
      --scan-type "Semgrep JSON Report" \
      semgrep-results.json

4. Full Aggregation Workflow

Progress: [ ] 1. Run all applicable scanners; save JSON output for each [ ] 2. Import each result file with correct `--scan-type` (see references/tool-parser-map.md) [ ] 3. Review deduplicated findings in DefectDojo UI: **Engagements → Tests → Findings** [ ] 4. Triage: set severity, assign owner, and set SLA due dates [ ] 5. Risk-accept findings with business justification (required for SOC2/PCI-DSS evidence) [ ] 6. Re-run scanners after fixes; `--reimport` to auto-close resolved findings [ ] 7. Export compliance report: **Reports → Generate Report**

Work through each step systematically. Check off completed items.

5. Triage and Prioritization

After import in the DefectDojo UI:

1. **Filter** by severity: Critical → High → Medium 2. **Verify deduplication**: DefectDojo auto-deduplicates across scans. Review grouped duplicates before accepting. 3. **Assign** findings to engineers with SLA due dates 4. **Risk Accept**: Document business justification for accepted risks 5. **Tag** findings by component or compliance requirement (e.g., `pci-req-6.3`)

Security Considerations

• **Sensitive Data Handling**: DefectDojo stores vulnerability details that reveal application internals. Restrict access by role. Enable HTTPS and use SSO/LDAP for authentication in produc