Skip to main content

DefectDojo

License Apache-2.0GitHub release (latest SemVer)OWASP Incubator ProjectArtifact HUBGitHub Repo starsTwitter Follower

What is "Persistence DefectDojo" Hook about?#

The DefectDojo hook imports the reports from scans automatically into OWASP DefectDojo. The hook uses the import scan API v2 from DefectDojo to import the scan results.

Scan types which are both supported by the secureCodeBox and DefectDojo benefit from the full feature set of DefectDojo, like deduplication. These scan types are:

  • Nmap
  • Nikto
  • ZAP (Baseline, API Scan and Full Scan)
  • ZAP Advanced
  • SSLyze
  • Trivy
  • Gitleaks
  • Semgrep

After uploading the results to DefectDojo, it will use the findings parsed by DefectDojo to overwrite the original secureCodeBox findings identified by the parser. This lets you access the finding metadata like the false positive and duplicate status from DefectDojo in further ReadOnly hooks, e.g. send out Slack notification for non-duplicate & non-false positive findings only.

For scan types which are not supported by DefectDojo, the generic importer is used, which will result in a less sophisticated display of the results and fewer features inside DefectDojo. In the worst case, it can lead to some findings being lost - see the note below.

caution

Be careful when using the DefectDojo Hook in combination with other ReadAndWrite hooks. By default, the secureCodeBox makes no guarantees about the execution order of multiple ReadAndWrite hooks, they can be executed in any order. This can lead to "lost update" problems as the DefectDojo hook will overwrite all findings, which disregards the results of previously run ReadAndWrite hooks. ReadOnly hooks work fine with the DefectDojo hook as they are always executed after ReadAndWrite Hooks. If you want to control the order of execution of the different hooks, take a look at the hook priority documentation (supported with secureCodeBox 3.4.0 and later).

caution

The DefectDojo hook will send all scan results to DefectDojo, including those for which DefectDojo does not have native support. In this case, DefectDojo may incorrectly deduplicate findings, which can in some cases lead to incomplete imports and even data loss. You can set the hook to read-only mode, which will prevent it from writing the results back to secureCodeBox (--set defectdojo.syncFindingsBack=false during installation of the hook) if you want to rule out any data loss inside secureCodeBox, but this will not prevent the incorrect deduplication from affecting the data you see inside DefectDojo (for this, you will need to contribute a parser to DefectDojo). You can also selectively disable the DefectDojo hook for certain scans using the hook selector feature (supported with secureCodeBox 3.4.0 and later).

Running "Persistence DefectDojo" Hook Locally from Source#

For development purposes, it can be useful to run this hook locally. You can do so by following these steps:

  1. Make sure you have access to a running DefectDojo instance.
  2. Run a Scan of your choice.
  3. Supply Download Links for the Scan Results (Raw Result and Findings.json). You can access them from the included Minio Instance and upload them to a GitHub Gist.
  4. Set the following environment variables:
  • DEFECTDOJO_URL (e.g http://192.168.0.1:8080);
  • DEFECTDOJO_USERNAME (e.g admin)
  • DEFECTDOJO_APIKEY= (e.g. b09c.., can be fetched from the DefectDojo API information page)
  • IS_DEV=true
  • SCAN_NAME (e.g nmap-scanme.nmap.org, must be set exactly to the name of the scan used in step 2)
  1. Build the jar with gradle and run it with the following CLI arguments: {Raw Result Download URL} {Findings Download URL} {Raw Result Upload URL} {Findings Upload URL}. See the code snippet below. You have to adjust the filename of the jar for other versions than the '0.1.0-SNAPSHOT'. Also you will need to change the download URLs for the Raw Result and Findings to the ones from Step 3.
./gradlew buildjava -jar build/libs/defectdojo-persistenceprovider-0.1.0-SNAPSHOT.jar https://gist.githubusercontent.com/.../scanme-nmap-org.xml https://gist.githubusercontent.com/.../nmap-findings.json https://httpbin.org/put https://httpbin.org/put

Deployment#

The persistence-defectdojo chart can be deployed via helm:

# Install HelmChart (use -n to configure another namespace)helm upgrade --install persistence-defectdojo secureCodeBox/persistence-defectdojo

Requirements#

Kubernetes: >=v1.11.0-0

Additional Chart Configurations#

Installing the DefectDojo persistenceProvider hook will add a ReadAndWrite Hook to your namespace.

kubectl create secret generic defectdojo-credentials --from-literal="username=admin" --from-literal="apikey=08b7..."
helm upgrade --install dd secureCodeBox/persistence-defectdojo \    --set="defectdojo.url=https://defectdojo-django.default.svc"

The hook will automatically import the scan results into an engagement in DefectDojo. If the engagement doesn't exist the hook will create the engagement (CI/CD engagement) and all objects required for it (product & product type). The hook will then pull the imported information from DefectDojo and use them to replace the findings inside secureCodeBox.

You don't need any configuration for that to work, the hook will infer engagement & product names from the scan name. If you want more control over the names or add additional meta information like the version of the tested software you can add these via annotation to the scan. See examples below.

Scan AnnotationDescriptionDefault if not setNotes
defectdojo.securecodebox.io/product-type-nameName of the Product TypeProduct Type with ID 1 (typically "Research and Development")Product Type will be automatically created if no Product Type under that name exists
defectdojo.securecodebox.io/product-nameName of the ProductScheduledScan Name if Scheduled, Scan Name if it's a standalone ScanProduct will be automatically created if no Product under that name exists
defectdojo.securecodebox.io/product-descriptionDescription of the ProductEmpty StringOnly used when creating the Product not used for updating
defectdojo.securecodebox.io/product-tagsProduct TagsNothingOnly used when creating the Product not used for updating
defectdojo.securecodebox.io/engagement-nameName of the EngagementScan NameWill be automatically created if no engagement with that name and version exists
defectdojo.securecodebox.io/engagement-versionEngagement VersionNothing
defectdojo.securecodebox.io/engagement-deduplicate-on-engagementDeduplicate On EngagementfalseOnly used when creating the Engagement not used for updating
defectdojo.securecodebox.io/engagement-tagsEngagement TagsNothingOnly used when creating the Engagement not used for updating
defectdojo.securecodebox.io/test-titleTest TitleScan Name

Read-only Mode#

By default, the DefectDojo hook will pull the imported results from DefectDojo and use them to replace the results inside secureCodeBox. This allows you to benefit from DefectDojo's deduplication logic and only trigger follow-up scans or notifications for new findings. If you want to disable this feature, you can install the hook in read-only mode using --set defectdojo.syncFindingsBack=false while installing the hook using Helm.

Low Privileged Mode#

By default the DefectDojo Hook requires a API Token with platform wide "Staff" access rights.

DefectDojo >2.0.0 refined their user access rights, allowing you to restrict the users access rights to only view specific product types in DefectDojo. The secureCodeBox DefectDojo Hook can be configured to run with such a token of a "low privileged" users by setting the defectdojo.lowPrivilegedMode=true.

Limitations of the Low Privileged Mode#

  • Instead of the username, the userId must be configured as the low privileged can't use the users list api to look up its own userId.
  • The configured product type must exist beforehand as the low privileged user isn't permitted to create a new one
  • The hook will not create / link the engagement to the secureCodeBox orchestration engine tool type.
  • The low privileged user must have at least the Maintainer role in the configured product type.

Low Privileged Mode Install Example#

kubectl create secret generic defectdojo-credentials --from-literal="apikey=08b7..."
helm upgrade --install dd secureCodeBox/persistence-defectdojo \    --set="defectdojo.url=https://defectdojo-django.default.svc" \    --set="defectdojo.lowPrivilegedMode=true" \    --set="defectdojo.authentication.userId=42"

Simple Example Scans#

This will run a daily scan using ZAP on a demo target. The results will be imported using the name "zap-juiceshop-$UNIX_TIMESTAMP" (Name of the Scan created by the ScheduledScan), in a product called "zap-juiceshop" in the default DefectDojo product type.

apiVersion: "execution.securecodebox.io/v1"kind: ScheduledScanmetadata:  name: "zap-juiceshop"spec:  interval: 24h  scanSpec:    scanType: "zap-full-scan"    parameters:      - "-t"      - "http://juice-shop.demo-targets.svc:3000"

Complete Example Scan#

This will import the results into engagement, product and product type following the labels. The engagement will be reused by the hook for the daily scans / imports until the engagement version is increased.

apiVersion: "execution.securecodebox.io/v1"kind: ScheduledScanmetadata:  name: "zap-full-scan-juiceshop"  annotations:    defectdojo.securecodebox.io/product-type-name: "OWASP"    defectdojo.securecodebox.io/product-name: "Juice Shop"    defectdojo.securecodebox.io/product-description: |      OWASP Juice Shop is probably the most modern and sophisticated insecure web application!      It can be used in security trainings, awareness demos, CTFs and as a guinea pig for security tools!      Juice Shop encompasses vulnerabilities from the entire OWASP Top Ten along with many other security flaws found in real-world applications!    defectdojo.securecodebox.io/product-tags: vulnerable,appsec,owasp-top-ten,vulnapp    defectdojo.securecodebox.io/engagement-name: "Juice Shop"    defectdojo.securecodebox.io/engagement-version: "v12.6.1"    defectdojo.securecodebox.io/engagement-tags: "automated,daily"    defectdojo.securecodebox.io/engagement-deduplicate-on-engagement: "true"    defectdojo.securecodebox.io/test-title: "Juice Shop - v12.6.1"spec:  interval: 24h  scanSpec:    scanType: "zap-full-scan"    parameters:      - "-t"      - "http://juice-shop.demo-targets.svc:3000"

Values#

KeyTypeDefaultDescription
defectdojo.authentication.apiKeyKeystring"apikey"Name of the apikey key in the userSecret secret. Use this if you already have a secret with different key / value pairs
defectdojo.authentication.userIdstringnilSet the userId explicitly. When not set the configured username is used to look up the userId via the DefectDojo API (which is only available for privileged users.)
defectdojo.authentication.userSecretstring"defectdojo-credentials"Link a pre-existing generic secret with username and apikey key / value pairs
defectdojo.authentication.usernameKeystring"username"Name of the username key in the userSecret secret. Use this if you already have a secret with different key / value pairs
defectdojo.lowPrivilegedModeboolfalseAllows the hook to run with a users token whose access rights are restricted to one / multiple product types but doesn't have global platform rights. If set to true, the DefectDojo User ID has to be configured instead of the username (defectdojo.authentication.userId). User needs to have at least the Maintainer role in the used Product Type.
defectdojo.syncFindingsBackbooltrueSyncs back (two way sync) all imported findings from DefectDojo to SCB Findings Store. When set to false the hook will only import the findings to DefectDojo (one way sync).
defectdojo.urlstring"http://defectdojo-django.default.svc"Url to the DefectDojo Instance
hook.image.pullPolicystring"IfNotPresent"Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images
hook.image.repositorystring"docker.io/securecodebox/hook-persistence-defectdojo"Hook image repository
hook.image.tagstringnilContainer image tag
hook.labelsobject{}Add Kubernetes Labels to the hook definition
hook.priorityint0Hook priority. Higher priority Hooks are guaranteed to execute before low priority Hooks.

License#

License

Code of secureCodeBox is licensed under the Apache License 2.0.