# Set up DefectDojo

> Connect ScanSuite to DefectDojo, serve it over TLS, and keep it running.

Source: https://scansuite.eu/documentation/installation/set-up-defectdojo
Last reviewed: 2026-10-19

DefectDojo is an open-source vulnerability tracker that ScanSuite exports scan results to. You need it only for the classic scanners' full results: everything the AI scans find, and most classic scanners' findings, are managed in ScanSuite's own [Vulnerabilities section](https://scansuite.eu/documentation/usage/vulnerability-management) anyway. The installer puts DefectDojo on the same server by default; this page connects it to a team, serves it over your own certificate, and keeps it running.

## Which findings go where

| Scanner | In Vulnerabilities | In DefectDojo |
|---|---|---|
| AI scans: AI Native SAST, dependency reachability, AI DAST, AI Pentest | Always | No |
| Nessus | Always | Yes, when connected |
| Semgrep, KICS, Trivy, Nuclei, ZAP, Wapiti, Dastardly, Acunetix, OpenVAS | When Store scanner findings is On (the default) | Yes, when connected |
| Other classic scanners | No: their results are in the scan reports | Yes, when connected |

The setting is per team: user menu (top right) → **Teams** → **Scanning** → **Scanner findings in Vulnerabilities**. Team admins and operators change it; the card is described in [Teams and roles](https://scansuite.eu/documentation/administration/teams-and-roles).

| Field | What it does | Default |
|---|---|---|
| Store scanner findings | Store the listed scanners' findings in Vulnerabilities as well. | On |
| Lowest severity to store | Findings below it stay in the reports only; it applies to Nessus too. | Medium |
| Close findings a rescan no longer reports | Close a stored finding as fixed when a later scan no longer reports it: for Semgrep only, for all scanners, or never. | Semgrep |

## Before you start

DefectDojo runs next to ScanSuite in `/opt/scansuite/defectdojo`, on ports 8080 and 8443. An installation made with `--no-dojo` gets it with `cd /opt/scansuite && ./scansuite update --with-dojo`. Check that it runs:

```bash
cd /opt/scansuite/defectdojo && docker compose ps
curl -sk -o /dev/null -w '%{http_code}\n' https://127.0.0.1:8443/login
```

Expected: `nginx`, `uwsgi`, `celerybeat`, `celeryworker`, `postgres` and `redis` up, and `200`. If not, run `cd /opt/scansuite && ./scansuite dojo start`; on a first start DefectDojo needs a few minutes before it answers.

The values this page uses:

| Placeholder | Where it comes from |
|---|---|
| <DOJO_HOST> | The server's DNS name or IP address, as both browsers and ScanSuite reach it — not localhost, which inside ScanSuite's containers is the container itself. |
| <DOJO_DOMAIN> | Optional: a DNS name of DefectDojo's own, for its certificate. |
| <ACCOUNT> | The account that installed ScanSuite. |

## 1. Read the DefectDojo admin password

```bash
cd /opt/scansuite && ./scansuite dojo password
```

![The DefectDojo password command output](https://scansuite.eu/static/assets/img/docs/installation/set-up-defectdojo/01.png)

*Reading the DefectDojo admin password*

Expected: a line `Admin password: …`, then, at a terminal, the question `Change the admin password now? [y/N]:`; --yes never answers it. The password is printed only from DefectDojo's first start; until it is set up (a few minutes after the install) or after DefectDojo was recreated, the command says `No password in the initializer log`. Then answer `y` and set a new password, which you type twice.

> **A person does this step:** The password appears in the terminal. A person reads it, stores it in a password manager and answers the question.
>
> An agent must not copy it into a chat.

## 2. Sign in to DefectDojo

> **A person does this step:** Open https://<DOJO_HOST>:8443 in a browser (or your DOJO_DOMAIN, see TLS for DefectDojo) and sign in as admin with that password. The certificate is self-signed until you replace it, so the browser warns once.

![DefectDojo login](https://scansuite.eu/static/assets/img/docs/installation/set-up-defectdojo/02.png)

*The DefectDojo login page*

## 3. Copy the API key

> **A person does this step:** Open https://<DOJO_HOST>:8443/api/key-v2 while signed in and copy the API key shown there.

![DefectDojo API key](https://scansuite.eu/static/assets/img/docs/installation/set-up-defectdojo/03.png)

*The DefectDojo API key page*

## 4. Connect the team to DefectDojo

The connection belongs to a team: each team connects its own DefectDojo, and only team admins and operators can change integrations.

1. In ScanSuite, open the user menu (top right) → **Teams**.
2. Open the **Integrations** tab. Under **Issue trackers**, in the **DefectDojo** block, enter `https://<DOJO_HOST>:8443` as **Address** and the key as **API key**.
3. Click **Save**.

![ScanSuite user menu](https://scansuite.eu/static/assets/img/docs/installation/set-up-defectdojo/04.png)

*Opening Teams from the user menu*

> **A person does this step:** Paste the DefectDojo API key into the API key field yourself, never into a chat.

![DefectDojo settings fields](https://scansuite.eu/static/assets/img/docs/installation/set-up-defectdojo/05.png)

*DefectDojo connection settings on the Integrations tab*

Expected: the DefectDojo block is marked as connected. The key is not shown again; leave the field empty when you save other changes, and it is kept. A self-signed DefectDojo certificate is accepted.

## 5. Check the connection

Open **Products** in the sidebar, click **New product**, enter a product name and click **Create product**.

![ScanSuite products list](https://scansuite.eu/static/assets/img/docs/installation/set-up-defectdojo/06.png)

*A test product created successfully*

Expected: under the product's name the list shows **DefectDojo · <number>**, linked to its DefectDojo engagement, instead of **Local product**. If ScanSuite says `Connection to DefectDojo failed. Verify connection string and try again.`, check the **Address** (reachable from the ScanSuite server, with `https://` and the port) and copy the key again.

## DefectDojo settings

DefectDojo reads its settings from `/opt/scansuite/defectdojo/.env`, a file you create; updates leave it alone. Apply a change with `cd /opt/scansuite && ./scansuite dojo start`.

| Setting | What it does | Default | When to change |
|---|---|---|---|
| DD_PORT | The HTTP port on the host. | 8080 | The port is taken. |
| DD_TLS_PORT | The HTTPS port on the host. | 8443 | The port is taken; change the Address in ScanSuite with it. |
| DD_ALLOWED_HOSTS | The host names DefectDojo answers to. | * (any) | Restrict to <DOJO_HOST> and <DOJO_DOMAIN>. |
| DD_ADMIN_USER | The administrator created on the first start. | admin | Before the first start only. |
| DD_SECRET_KEY | Signs DefectDojo's sessions. | a fixed value shipped with the release | Set your own random value, before DefectDojo holds data. |
| DD_CREDENTIAL_AES_256_KEY | Encrypts the credentials DefectDojo stores. | a fixed value shipped with the release | Set your own random value before DefectDojo holds data: changing it later makes stored credentials unreadable. |
| DD_DATABASE_PASSWORD, DD_DATABASE_URL | The database password, and the connection that uses it. | defectdojo | Together, before the first start only. |

## TLS for DefectDojo

DefectDojo has its own certificate, independent of the [ScanSuite console certificate](https://scansuite.eu/documentation/installation/ssl-tls-setup). To serve it over yours:

1. Create a DNS record for `<DOJO_DOMAIN>` pointing at the server (a person, as on the SSL/TLS page) and check it with `dig +short <DOJO_DOMAIN>`.
2. Get a certificate with its full chain and its key from your certificate authority, or from Let's Encrypt as on [SSL/TLS Setup](https://scansuite.eu/documentation/installation/ssl-tls-setup) — with `-d <DOJO_DOMAIN>`, and a deploy hook that copies to the paths below.
3. Put them in place, owned by your account, and restart DefectDojo's nginx:

   ```bash
   cd /opt/scansuite/defectdojo
   cp ~/certs/dojo-fullchain.pem certs/nginx.crt
   cp ~/certs/dojo-privkey.pem certs/nginx.key
   chmod 600 certs/nginx.key
   docker compose restart nginx
   ```
4. Check: `openssl s_client -connect <DOJO_DOMAIN>:8443 -servername <DOJO_DOMAIN> </dev/null 2>/dev/null | openssl x509 -noout -subject -enddate` prints your domain and the expiry date.
5. Change the **Address** in each team's DefectDojo block to `https://<DOJO_DOMAIN>:8443`.

## Restart, reset and recover

| Command, in /opt/scansuite | What it does |
|---|---|
| ./scansuite dojo start | Starts DefectDojo, or applies a changed defectdojo/.env. |
| ./scansuite dojo password | Reads the admin password from the first start and, at a terminal, offers to change it. |
| cd defectdojo && docker compose restart | Restarts DefectDojo's containers. |
| ./scansuite update --no-dojo | Stops DefectDojo and leaves it out of later updates; its data is kept. |
| ./scansuite update --with-dojo | Brings it back as it was. |
| ./scansuite reset dojo [--yes] | Deletes DefectDojo's database and starts it empty. The same as ./scansuite dojo reset [--yes]. |

> **A person does this step:** Resetting DefectDojo destroys every finding, product and engagement stored in it. A person decides it and answers Delete the DefectDojo database? [y/N].

```bash
cd /opt/scansuite && ./scansuite reset dojo
```

Afterwards read the new admin password with `./scansuite dojo password` (allow a few minutes), copy a new API key and save it in each team's DefectDojo block, or result uploads start failing.