CycloneDX Integration with DefectDojo

CycloneDX Integration with DefectDojo

CycloneDX is an open standard for software bills of materials (SBOMs), created within OWASP and also published by Ecma International as ECMA-424. A CycloneDX document lists the components that make up a piece of software (libraries, packages, containers, services) with identifiers such as package URLs, and since version 1.4 it can also carry vulnerability data and VEX (Vulnerability Exploitability eXchange) analysis about those components. CycloneDX files come in XML and JSON and are produced by many tools, including Anchore Grype and the CycloneDX generators for Python and other ecosystems.

CycloneDX Integration with DefectDojo

We standardized on CycloneDX because nearly every SCA and container tool we evaluate can emit it, and DefectDojo is where the vulnerabilities in those documents become tracked work. Importing a CycloneDX file into DefectDojo creates one Finding per vulnerability per affected component, with the component name and version, vulnerability IDs, CVSS data, and fix guidance. If the document includes VEX analysis that marks a vulnerability as not affected or resolved, DefectDojo respects it. That means one import path for every tool that speaks CycloneDX instead of a separate parser per vendor.

Why CycloneDX Matters

Supply chain security starts with knowing what is in the software you ship, and regulators and customers increasingly ask for that inventory in a standard format.

• It is a vendor-neutral format, so SBOMs from scanners, build plugins, and suppliers can be handled the same way.
• Its vulnerability section links each issue to the exact components it affects through bom-ref references.
• VEX analysis states (such as not_affected or false_positive) let a producer explain why a listed vulnerability doesn't apply.
• It supports ratings with CVSS vectors, CWE lists, advisories, and recommendations, which is everything a triage workflow needs.
• An SBOM on its own is a document. It doesn't assign owners, measure SLAs, or show which issues were fixed since the last release.

Advantages of This Integration

What we gained by importing CycloneDX into DefectDojo:

• One parser for many producers. Any tool that writes CycloneDX with a vulnerabilities section can feed DefectDojo through the same scan type.
• Component-level deduplication. DefectDojo hashes CycloneDX findings on vulnerability ID, component name, and component version, so the same CVE in the same library version is recognized across builds.
• VEX decisions carried over. Vulnerabilities analyzed as resolved, resolved_with_pedigree, or not_affected arrive mitigated and inactive, and false_positive arrives as a false positive.
• A lifecycle per release. Reimporting each new SBOM into the same Test mitigates vulnerabilities that were fixed by upgrades and adds newly disclosed ones.
• Supplier SBOMs as tracked risk. Vendor-provided SBOMs can be imported into their own Assets so third-party components get owners and SLAs too.

How This Integration Works

DefectDojo imports CycloneDX documents with the CycloneDX Scan scan type. Files ending in .json are read as JSON; anything else is read as XML.

1. Produce a CycloneDX document that includes vulnerabilities. For example, with Grype against a container image:

grype registry.example.com/payments-api:2.3.0 -o cyclonedx-json > payments-api.cdx.json

Or in XML:

grype registry.example.com/payments-api:2.3.0 -o cyclonedx > payments-api.cdx.xml

The parser creates findings from vulnerability entries. A pure inventory SBOM with no vulnerabilities section imports with no findings. For XML, it reads both the native vulnerabilities element from CycloneDX 1.4 and later and the older vulnerability extension namespace used by earlier tools.

2. Import it. In the UI, open the Engagement, choose Import Scan Results, select CycloneDX Scan, 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=CycloneDX Scan" \
  -F "file=@payments-api.cdx.json" \
  -F "product_name=payments-api" \
  -F "engagement_name=SBOM" \
  -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 "CycloneDX Scan" \
  --report-path "./payments-api.cdx.json" \
  --product-name "payments-api" \
  --engagement-name "SBOM" \
  --auto-create-context

3. Reimport for each release. Send each new SBOM to /api/v2/reimport-scan/ for the same Test so upgrades close findings automatically.

Data Granularity: What Gets Imported

Use Cases

In a container build pipeline: Every image build emits a CycloneDX file with Grype and reimports it into a Test per image. The team sees which component CVEs were introduced or removed by each build.

Ingesting supplier SBOMs: Procurement or vendor management receives SBOMs from software suppliers. Importing them into an Asset per supplier product turns a compliance document into tracked risk with owners and review dates.

Publishing VEX alongside SBOMs: Teams that ship SBOMs with VEX statements can import their own documents and confirm that components marked not_affected arrive inactive, while everything else follows normal SLAs.

Standardizing across tools: An organization using different SCA tools across business units asks each to produce CycloneDX. DefectDojo then applies one deduplication model and one set of SLAs across all of them.

Operational Tips

• Check that your producer includes vulnerabilities, not just components. An inventory-only SBOM is valid CycloneDX but produces no findings.
• Make sure every component has a bom-ref and that affects entries point to it. An unresolved reference produces a finding with no component name or version (the title shows None:None), which weakens deduplication.
• Name JSON files with a .json extension. Any other extension is parsed as XML.
• Severity follows the producer. If a vulnerability has no rating at all it lands as Medium, so review unrated findings before SLAs depend on them.
• Use one Test per artifact (image, library, or release line) and reimport into it, so upgrades show up as mitigations.
• Tag imports with the artifact version (for example tags=payments-api,2.3.0) to compare releases in metrics.