From 20ebe960cf67d9947d694111d22818636eeaa590 Mon Sep 17 00:00:00 2001 From: svader0 Date: Mon, 10 Aug 2026 13:34:26 -0500 Subject: [PATCH] docs: state what the credential encryption key actually covers The backup and production pages described the credential encryption key as protecting stored credentials for connected tools in general. It does not. It covers Tool Configuration credentials; Pro connector credentials are encrypted with the secret key instead, and several integration credentials are not encrypted at all. An operator following the old wording could keep the key away from the backup and conclude the backup was safe on its own. Say plainly which key covers what, and that a database backup carries secrets whether or not the keys travel with it. Also fixes the restore drill, which checked one tool connection and claimed that proved the credential encryption key was restored correctly. --- .../get_started/open_source/running-in-production.md | 2 +- docs/content/get_started/pro/onprem/backing_up.md | 10 ++++++---- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/content/get_started/open_source/running-in-production.md b/docs/content/get_started/open_source/running-in-production.md index e22e9b69516..107751efe6d 100644 --- a/docs/content/get_started/open_source/running-in-production.md +++ b/docs/content/get_started/open_source/running-in-production.md @@ -33,7 +33,7 @@ With a separate database, the minimum recommendations to run DefectDojo are: ### Security Verify the `nginx` configuration and other run-time aspects such as security headers to comply with your compliance requirements. Change the AES256 encryption key `&91a*agLqesc*0DJ+2*bAbsUZfR*4nLw` in `docker-compose.yml` to something unique for your instance. -This encryption key is used to encrypt API keys and other credentials stored in Defect Dojo to connect to external tools such as SonarQube. A key can be generated in various ways for example using a password manager or `openssl`: +This encryption key is used to encrypt Tool Configuration credentials, for example the SonarQube credentials. It does not cover every credential DefectDojo stores, so treat the database and its backups as carrying secrets in their own right rather than relying on this key alone. A key can be generated in various ways for example using a password manager or `openssl`: ``` openssl rand -base64 32 diff --git a/docs/content/get_started/pro/onprem/backing_up.md b/docs/content/get_started/pro/onprem/backing_up.md index 8ad319f2566..843f801b1c1 100644 --- a/docs/content/get_started/pro/onprem/backing_up.md +++ b/docs/content/get_started/pro/onprem/backing_up.md @@ -6,7 +6,7 @@ weight: 12 audience: pro --- -A deployment is more than its database. A backup that captures only the database restores into a system that runs but is missing uploaded files and cannot decrypt the credentials it holds for your other tools. This page covers what to capture, where each piece lives, and how to confirm the result is restorable. +A deployment is more than its database. A backup that captures only the database restores into a system that runs but is missing uploaded files and cannot decrypt the connection credentials that are stored encrypted. This page covers what to capture, where each piece lives, and how to confirm the result is restorable. ## The four things to capture @@ -16,7 +16,9 @@ Uploaded files live outside the database. Screenshots, threat models, risk accep Deployment configuration is what makes the application come back up the same way, including your own customizations and TLS certificates. -The encryption keys are the piece most often missed. The credential encryption key is what makes stored credentials for your connected tools readable. Restore a database without it and those credentials are intact but undecryptable, which means every integration has to be re-entered by hand. +The encryption keys are the piece most often missed. Connector credentials are encrypted with the secret key, and Tool Configuration credentials with the credential encryption key. Restore a database without the matching key and those credentials are intact but undecryptable, which means the affected integrations have to be re-entered by hand. + +Not every integration credential is encrypted. Some are stored as entered, so treat a database backup as carrying secrets in its own right, whether or not you also hold the keys. Protect it accordingly, and rotate the credentials of any integration whose backup you cannot account for. ## The database @@ -58,7 +60,7 @@ On Compose, capture your `customizations` directory, your `certs` directory, and On Kubernetes, capture your values files and the contents of the secrets your release references. -In both cases, keep the credential encryption key and the secret key somewhere durable and separate, in a secret manager rather than alongside the backup. Anyone holding both the database and the credential key can read the credentials for every tool you have connected, so they should not travel together. +In both cases, keep the credential encryption key and the secret key somewhere durable and separate, in a secret manager rather than alongside the backup. Anyone holding both the database and those keys can read every stored credential that is encrypted, so they should not travel together. Keys and backup travelling separately narrows the exposure of a lost backup; it does not eliminate it, because the backup still holds the credentials that are not encrypted. ## What is not a backup @@ -72,7 +74,7 @@ A backup nobody has restored is an assumption. Test it into a scratch environmen 1. Log in, and confirm your organizations, assets, engagements, tests, and findings are present in the numbers you expect. 2. Open a finding with an attachment and download it. This is what proves the media restore worked, since the database alone would show the attachment listed but fail to serve it. -3. Open a configured tool connection and confirm its credentials are intact. This is what proves you restored the credential encryption key correctly, and it is the check most likely to reveal a gap. +3. Open a configured connector and a configured Tool Configuration, and confirm the credentials on each are intact. Between them these cover both keys, and this is the check most likely to reveal a gap. 4. Confirm users and groups came across. Authentication settings such as SSO usually need reconfiguring for a different environment, so treat differences there as expected rather than as a failed restore. Run this drill on a schedule rather than only when you need it. Doing a restore for the first time during an incident is where backup plans usually fail.