Upgrading to DefectDojo Version 3.1.x

Blank Finding components normalized to NULL#

Previously a Finding could store an empty string ("") for component_name or component_version depending on how it was created or edited. The database treats an empty string as distinct from NULL, so the All Components view (which groups findings by component) could show two separate “None” rows — one for findings with a NULL component and one for findings with an empty-string component.

Findings without a component now consistently store NULL. Blank values are normalized to NULL when a Finding is saved, and a data migration converts existing empty-string component values to NULL on upgrade.

What you need to do#

Nothing — the change is applied automatically by the database migration included in this release. After upgrading, component-less findings will group together under a single “None” entry.

Multiple JIRA components per project#

The Component field on a JIRA project configuration now supports assigning more than one Jira component. Separate multiple component names with a comma (for example, Security,DevSecOps), and each name is sent to Jira as a distinct component. A single value without commas continues to behave as before.

What you need to do#

Nothing is required. Note that a component name that legitimately contains a comma will be split into separate components — component names rarely contain commas, so this is an accepted limitation.

Tool Configuration credentials upgraded to AES-256-GCM#

DefectDojo encrypts the credentials stored on Tool Configurations (the password, ssh, and api_key fields). Previously these values were encrypted with AES-256 in OFB mode (the AES.1 stored format). This release introduces a modern AES.2 format that uses AES-256-GCM, an authenticated encryption scheme that detects tampering with the stored ciphertext.

New and updated credentials are written in the AES.2 format automatically. The encryption key is unchanged — both formats derive their key from the same DD_CREDENTIAL_AES_256_KEY, so no key rotation or settings change is required.

A data migration (0272_reencrypt_tool_config_credentials_aes_gcm) included in this release eagerly re-encrypts every existing AES.1 credential to AES.2 on upgrade. The legacy AES.1 decryption path is retained for backward compatibility, so any value that has not yet been migrated continues to decrypt normally. The same migration also widens the password, ssh, and api_key columns by 50% so that credentials stored at the old maximum length still fit once the GCM nonce and authentication tag are added.

This release also bumps cryptography to 49.0.0 and pyopenssl to 26.3.0.

What you need to do#

Nothing — the change is applied automatically by the database migration included in this release. Ensure your DD_CREDENTIAL_AES_256_KEY is unchanged from your prior deployment so the existing credentials can be decrypted and re-encrypted; a value that fails to decrypt (for example, because it was encrypted under a different key) is left untouched rather than overwritten.

JFrog Xray API Summary Artifact parser: deterministic impact paths#

The JFrog Xray API Summary Artifact parser derives a finding’s file_path, description, and unique_id_from_tool (its deduplication key) from the first entry in the vulnerability’s impact_path list. JFrog returns that list in an arbitrary order, so the same vulnerability could produce a different first entry from one scan to the next. When the order changed, the deduplication key changed too, and a single CVE would be re-imported as multiple separate findings across successive scans.

The parser now sorts the impact paths before selecting the first one, so file_path, the description, and the deduplication key stay stable across re-imports. When a vulnerability has more than one impact path, the full sorted list is now appended to the finding description under an Impact paths: heading so no path information is lost.

What you need to do#

Nothing is required for new imports. Findings imported before this release may have been created with a non-deterministic first impact path; re-importing an affected report will now deduplicate consistently, and you may want to clean up any duplicate findings that a previous import created.

For more information, check the Release Notes.