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.

New setting: DD_OS_MESSAGE_ENABLED

This release adds the DD_OS_MESSAGE_ENABLED setting (default True), which controls the open-source promotional (“Upgrade to Pro”) banner. The default preserves the existing behavior. Set DD_OS_MESSAGE_ENABLED=False to hide the banner; when disabled, DefectDojo skips the outbound request that fetches the message.

Deduplication execution mode for import/reimport

This release adds a new deduplication_execution_mode setting that controls how import/reimport deduplication post-processing is dispatched and whether the API response waits for it. It can be set per user (profile) and overridden per request on the import and reimport endpoints.

Modes:

• async (default): deduplication and the rest of post-processing are dispatched to the background and the response returns immediately. This is the historical behavior; nothing changes for existing users.
• async_wait: post-processing is still dispatched to the background, but the request waits for deduplication to finish before responding. As a result the scan_added notification and the statistics in the import/reimport response reflect the deduplicated state (findings that turned out to be duplicates are no longer counted/listed as new). JIRA push, product grading and other non-deduplication tasks remain asynchronous and are not awaited.
• sync: import deduplication runs inline in the web request.

The wait in async_wait is bounded by the new DD_DEDUPLICATION_ASYNC_WAIT_TIMEOUT environment variable (default 60 seconds). If no worker picks up the work within the timeout, the request responds anyway (degrading to the async outcome) rather than hanging.

The import/reimport response now also includes a deduplication_complete boolean indicating whether deduplication had finished by the time the response was produced.

Relationship to block_execution

The existing block_execution profile flag is unchanged. It remains the global switch that forces all of a user’s asynchronous tasks (notifications, JIRA push, product grading, deduplication, …) to run in the foreground. deduplication_execution_mode is independent and narrower — it only affects import/reimport deduplication post-processing. A user who has block_execution enabled continues to get fully synchronous imports; the upgrade migration seeds their deduplication_execution_mode to sync so behavior is unchanged.