Skip to content

Latest commit

 

History

History

persistence-defectdojo

Folders and files

README.md

title DefectDojo
category hook
type persistenceProvider
state released
usecase Publishes all Scan Reports to OWASP DefectDojo.

License Apache-2.0 GitHub release (latest SemVer) OWASP Incubator Project Artifact HUB GitHub Repo stars Twitter 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.

This means that only scan types are supported by the hook which are both supported by the secureCodeBox and DefectDojo. These are:

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

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.

:::caution

Be careful when using the DefectDojo Hook in combination with other ReadAndWrite hooks. The secureCodeBox currently has no way to guarantee that one ReadAndWrite hook gets executed before another ReadAndWrite hook. 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. :::

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 e.g., 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 Settings)
  • 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 build
java -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 ReadOnly 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).

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 Annotation Description Default if not set Notes
defectdojo.securecodebox.io/product-type-name Name of the Product Type Product 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-name Name of the Product ScheduledScan Name if Scheduled, Scan Name if it's a standalone Scan Product will be automatically created if no Product under that name exists
defectdojo.securecodebox.io/product-description Description of the Product Empty String Only used when creating the Product not used for updating
defectdojo.securecodebox.io/product-tags Product Tags Nothing Only used when creating the Product not used for updating
defectdojo.securecodebox.io/engagement-name Name of the Engagement Scan Name Will be automatically created if no engagement with that name and version exists
defectdojo.securecodebox.io/engagement-version Engagement Version Nothing
defectdojo.securecodebox.io/engagement-deduplicate-on-engagement Deduplicate On Engagement false Only used when creating the Engagement not used for updating
defectdojo.securecodebox.io/engagement-tags Engagement Tags Nothing Only used when creating the Engagement not used for updating
defectdojo.securecodebox.io/test-title Test Title Scan Name

Simple Example Scans

This will import the results daily into an engagements called: "zap-juiceshop-$UNIX_TIMESTAMP" (Name of the Scan created daily by the ScheduledScan), in a Product called: "zap-juiceshop" in the default DefectDojo product type.

apiVersion: "execution.securecodebox.io/v1"
kind: ScheduledScan
metadata:
  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: ScheduledScan
metadata:
  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

Key Type Default Description
defectdojo.authentication.apiKeyKey string "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.userSecret string "defectdojo-credentials" Link a pre-existing generic secret with username and apikey key / value pairs
defectdojo.authentication.usernameKey string "username" Name of the username key in the userSecret secret. Use this if you already have a secret with different key / value pairs
defectdojo.syncFindingsBack bool true Syncs back (two way sync) all imported findings from DefectDojo to SCB Findings Store, set to false to only import the findings to DefectDojo (one way sync).
defectdojo.url string "http://defectdojo-django.default.svc" Url to the DefectDojo Instance
hook.image.pullPolicy string "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.repository string "docker.io/securecodebox/hook-persistence-defectdojo" Hook image repository
hook.image.tag string nil Container image tag

License

License

Code of secureCodeBox is licensed under the Apache License 2.0.