Generic Findings Import Integration with DefectDojo

Generic Findings Import Integration with DefectDojo

Generic Findings Import is DefectDojo's own file format for bringing in findings from tools that don't have a dedicated parser. It accepts two layouts: a CSV file with a fixed set of column names, and a JSON document with a findings array plus optional report metadata. The format is defined and maintained by the DefectDojo project, and it maps directly onto DefectDojo's Finding fields, including severity, CWE, CVE and other vulnerability IDs, CVSS vectors, EPSS scores, endpoints, file locations, components, and tags.

Generic Findings Import Integration with DefectDojo

We use Generic Findings Import whenever a source of findings has no parser of its own: an in-house scanner, a custom script that checks cloud tagging policy, a spreadsheet from a manual review, or a niche tool that only exports raw data. A small conversion step turns that output into the generic JSON format, and from there the findings behave like any other in DefectDojo. They get deduplicated, assigned, measured against SLAs, and reimported on a schedule. It keeps the long tail of security signals from living in side spreadsheets.

Why Generic Findings Import Matters

Every security program has sources that no vendor parser will ever cover.

• It gives internal tools a supported path into DefectDojo without writing and maintaining a parser.
• The JSON format exposes most of the Finding model, so converted findings don't lose detail like file and line, component and version, or endpoint.
• A custom type creates a named Test Type per tool, so findings from different internal tools stay distinguishable in filters and metrics.
• CSV support makes it practical for analysts to load findings from a manual review or a spreadsheet without writing code.

Advantages of This Integration

What we gained by standardizing odd sources on the generic format:

• Same lifecycle as first-class parsers. Reimporting a new file into the same Test mitigates missing findings, adds new ones, and reactivates returning ones.
• Deduplication you can tune. The default hashcode for Generic Findings Import is title, CWE, line, file path, and description. Because settings are looked up by Test Type name, a custom type can have its own HASHCODE_FIELDS_PER_SCANNER and DEDUPLICATION_ALGORITHM_PER_PARSER entries.
• Status from the source. Fields such as active, verified, false_p, risk_accepted, and is_mitigated let a converter carry triage decisions made elsewhere.
• Prioritization data. EPSS score and percentile, Known Exploited Vulnerabilities flags, fix availability, and fix version can all be supplied, which feeds filtering and reporting.
• Evidence attached. JSON findings can include Base64-encoded files (screenshots, logs, raw output) that are attached to the Finding.

How This Integration Works

DefectDojo imports both layouts with the Generic Findings Import scan type. A file whose name ends in .csv is read as CSV; every other file is read as JSON.

1. Build the file. A minimal JSON report:

{
  "type": "Tagging Policy Checker",
  "version": "1.0.0",
  "findings": [
    {
      "title": "S3 bucket missing data-classification tag",
      "severity": "Low",
      "description": "Bucket analytics-exports has no data-classification tag.",
      "date": "2026-10-01",
      "unique_id_from_tool": "tagcheck-analytics-exports",
      "vuln_id_from_tool": "tag.data-classification",
      "tags": ["cloud", "tagging"]
    }
  ]
}

Every JSON finding needs title, severity, and description. A key that isn't part of the format stops the import with a "Not allowed fields are present" error, so spell keys exactly (for example false_p, not false_positive). Booleans must be JSON true or false, not quoted strings.

For CSV, the header row must include Date, Title, Description, and Severity, every row needs a Date, and column names are case-sensitive. Save as UTF-8 without a byte order mark.

2. Import it. In the UI, open the Engagement, choose Import Scan Results, select Generic Findings Import, and upload the file. To automate it, use the import API in Community Edition or DefectDojo Pro:

curl "https://YOUR_INSTANCE/api/v2/import-scan/" \
  -H "Authorization: Token $DD_API_TOKEN" \
  -F "scan_type=Generic Findings Import" \
  -F "file=@tagcheck.json" \
  -F "product_name=aws-prod-account" \
  -F "engagement_name=Cloud Hygiene" \
  -F "auto_create_context=true"

DefectDojo Pro users can run the same import with Universal Importer:

universal-importer import \
  --defectdojo-url "https://YOUR_INSTANCE.cloud.defectdojo.com/" \
  --scan-type "Generic Findings Import" \
  --report-path "./tagcheck.json" \
  --product-name "aws-prod-account" \
  --engagement-name "Cloud Hygiene" \
  --auto-create-context

With "type": "Tagging Policy Checker", the Test Type becomes Tagging Policy Checker Scan (Generic Findings Import). Without a type, or for any CSV import, it is Generic Findings Import.

3. Reimport on a schedule. Send later files to /api/v2/reimport-scan/ for the same Test. The report's type must resolve to that Test's Test Type, or the reimport is rejected with a "Test type mismatch" error.

Data Granularity: What Gets Imported

CSV rows with the same Severity, Title, and Description are merged into one Finding, with their URLs and IDs combined and the occurrence count increased.

Use Cases

For an in-house scanner: A platform team writes a nightly script that checks Kubernetes clusters against internal policy and emits generic JSON with a custom type. Findings land in their own Test Type, reimport daily, and close when the policy passes.

After a manual review: An architect records design review findings in a spreadsheet. Exported as CSV with the required columns, they enter DefectDojo with severities and owners instead of staying in a document.

Bridging an unsupported tool: A niche scanner exports raw JSON with no DefectDojo parser. A short converter maps its fields to the generic format, including unique_id_from_tool, so DefectDojo can match findings reliably across runs.

Migrating historical data: When retiring a legacy tracking system, teams export open items to generic JSON with date, is_mitigated, and mitigated set, preserving the timeline in DefectDojo.

Operational Tips

• Prefer JSON over CSV. It supports components, file locations, tags, endpoints as objects, attachments, and report metadata, and it rejects bad keys instead of silently ignoring them.
• Always set a type per tool. Without one, everything lands in the shared Generic Findings Import Test Type, and any static_tool or dynamic_tool flags you send change it for every generic import on the instance.
• Emit a stable unique_id_from_tool if your tool has one, and configure a matching dedupe algorithm for your Test Type name if you want to deduplicate on it.
• Watch severity strings in CSV. high or Informational imports as Info without an error.
• Strip the byte order mark from CSV files saved by spreadsheet tools, or the first column name won't be recognized.
• Use YYYY-MM-DD for publish_date, planned_remediation_date, and kev_date in JSON; other formats stop the import.