Skip to content

docs: Update the API pull documentation #13689

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 14, 2025
+44 −27
Merged

docs: Update the API pull documentation #13689

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 13 additions & 6 deletions docs/content/supported_tools/parsers/api/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,21 @@ All parsers that use API pull have common basic configuration steps, but with di

Follow these steps to set up API importing:

## Tool Configuration

1. Configure the API authentication details by navigating to
`Configuration -> Tool Configuration -> Add Tool Configuration`. Enter a `Name`,
selecting the related `Tool Type` and `Authentication Type` "API Key". Paste your credentials
to the proper fields based on definitions below.
into the proper fields based on the selected parser.

## Product-Level Configuration

1. Navigate to `Products -> All Products` and select a product from the list.

2. Click on `Settings` and select `Add API Scan Configuration`

2. In the `Product` settings select `Add API Scan Configuration` and select the
previously added `Tool Configuration`. Provide values based on definitions below.
3. Select the previously added `Tool Configuration` and provide additional values based on the selected parser.

3. After this is done, you can import the findings on the `Product` page through
`Findings -> Import Scan Results`. As the `Scan type`, select the related type,
the API scan configuration from the last step, and click `Import`.
4. After this is done, you can import the findings on the `Product` page through
`Findings -> Import Scan Results`. As the `Scan type`, select the related type
(the `API Scan Configuration` created above) and click `Import`.
52 changes: 31 additions & 21 deletions docs/content/supported_tools/parsers/api/sonarqube.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,24 @@
title: "SonarQube API Import"
toc_hide: true
---
All parsers which using API have common basic configuration step but with different values. Please, [read these steps](../) at first.
All parsers that use API pull have common basic configuration steps, but with different values. Please, [read these steps](../) first.

In `Tool Configuration`, select `Tool Type` to "SonarQube" and `Authentication Type` "API Key".
Note the url must be in the format of `https://<sonarqube_host>/api`
## Tool Configuration

In `Tool Configuration`, select `Tool Type` "SonarQube" and `Authentication Type` "API Key".
The URL must be in the format of `https://<sonarqube_host>/api`
Paste your SonarQube API token in the "API Key" field.
By default the tool will import vulnerabilities issues
and security hotspots only, but additional filters can be setup using the
Extras field separated by commas (e.g. `BUG,VULNERABILITY,CODE_SMELL`). When using
SonarCloud, you must also specify the Organization ID in the Extras field as follows
`OrgID=sonarcloud-organzation-ID`. If also specifying issue type filters, please
seperate the items in the Extras field by a vertical bar as follows
`BUG,VULNERABILITY,CODE_SMELL|OrgID=sonarcloud-organzation-ID`

In "Add API Scan Configuration"
By default, the tool will import vulnerability issues
and security hotspots only, but additional filters can be applied using the
"Extras" field separated by commas (e.g. `BUG,VULNERABILITY,CODE_SMELL`). When using
SonarCloud, you must also specify the Organization ID in the "Extras" field (e.g.
`OrgID=sonarcloud-organzation-ID`). When also specifying issue type filters, please
separate the items in the "Extras" field by a vertical bar (e.g.
`BUG,VULNERABILITY,CODE_SMELL|OrgID=sonarcloud-organzation-ID`)

## Product-Level Configuration

In `Add API Scan Configuration`
- `Service key 1` must
be the SonarQube project key, which can be found by navigating to a specific project and
selecting the value from the url
Expand All @@ -24,23 +28,29 @@ In "Add API Scan Configuration"
use the name of the Product as the project key in SonarQube. If you would like to
import findings from multiple projects, you can specify multiple keys as
separated `API Scan Configuration` in the `Product` settings.
- If using SonarCloud, the orginization ID can be used from step 1, but it
can be overiden by supplying a different orginization ID in the `Service key 2` input field.
- If using SonarCloud, the organization ID can be used from step 1, but it
can be overridden by supplying a different organization ID in the `Service key 2` input field.

## Multiple SonarQube API Configurations

In the import or re-import dialog you can select which `API Scan
In the import or re-import dialog, you can select which `API Scan
Configuration` shall be used. If you do not choose
any, DefectDojo will use the `API Scan Configuration` of the Product if there is
only one defined or the SonarQube `Tool Configuration` if there is only one.

## Multi Branch Scanning
## Multi-Branch Scanning

If using a version of SonarQube with multi branch scanning, the branch tha be scanned can
be supplied in the `branch_tag` fieild at import/re-import time. If the branch does not exist,
a notification will be generated in the alerts table indicating that branch to be imported
If using a version of SonarQube with multi-branch scanning, the branch to be scanned can
be supplied in the `branch_tag` field at import/re-import time. If the branch does not exist,
a notification will be generated in the alerts table, indicating that branch to be imported
does not exist. If a branch name is not supplied during import/re-import, the default branch
of the SonarQube project will be used.

**Note:**: If `https` is used for the SonarQube, the certificate must be
trusted by the DefectDojo instance.
## Custom Trust

If you are connecting to SonarQube via HTTPS, the issuer of the certificate that is presented by
SonarQube must be trusted.

One way of achieving this is by defining the `REQUESTS_CA_BUNDLE` environment variable to point
Copy link
Contributor

@paulOsinski paulOsinski Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

REQUESTS_CA_BUNDLE environment variable

this is an env var within SonarQube? Just want to specify

Copy link
Author

@sNiXx sNiXx Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, this appears to be an env variable of the python requests library (see here). Although its usage in DefectDojo is not really documented besides in one sentence here and in the helm instructions (e.g. here)

As far as I understand, REQUESTS_CA_BUNDLE should ideally point to a file (or a directory) that includes custom trusted CA certificate(s) as well as the other trusted CA certificates already present (i.e. it overrides the default trust store).

I would propose to reflect this in the documentation by referencing the official requests docs.

Another alternative could be to bind /etc/ssl/certs to a read-only mounted volume, add the custom trusted CA certificates with Ubuntu's update-ca-certificates command and then set REQUESTS_CA_BUNDLE to /etc/ssl/certs/ca-certificates.crt

Writing these lines, I wonder, if it would make sense to have a dedicated page for this?

Copy link
Member

@valentijnscholten valentijnscholten Nov 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sNiXx That would be very helpful (a page about REQUESTS_CA_BUNDLE). But can be a follow up PR as it's not blocking this.

to a PEM-encoded certificate file in the container (e.g. `REQUESTS_CA_BUNDLE=/app/media/cacerts.pem`).
To ensure the certificate is persisted, the file should be in a mounted volume.