wesleydeanflexion/upload-sarif-to-defectdojo repository overview

⁠Upload Sarif results to Defect Dojo

⁠Quickstart

This should get you started:

export DD_TOKEN="${DEFECT_DOJO_AUTH_TOKEN}"
curl -s \
  -o './upload_sarif_to_defectdojo.bash' \
  -L 'https://raw.githubusercontent.com/wesley-dean/upload-sarif-to-defectdojo/main/upload_sarif_to_defectdojo.bash'
./upload_sarif_to_defectdojo.bash \
  -p "${PRODUCT}" \
  -e "${ENGAGEMENT}" \
  -s "${DEFECT_DOJO_SERVER}" \
  /path/to/SARIF/files/*.sarif

The script can be...

• downloaded at runtime (raw script link⁠)
• pulled from GHCR⁠
• pulled from DockerHub⁠

⁠Overview

This is a shell script that will iterate across a series of filenames passed in and upload the results to a DefectDojo instance. The goal is to have one process generate SARIF results (e.g., MegaLinter⁠) so that this script can upload the results. The original intent of this script was to upload SARIF-formatted reports produced by MegaLinter⁠, but it can work with any tool that produces SARIF output (e.g., semgrep --sarif).

There exist actions in the GitHub Actions Marketplace that will upload SARIF results to DefectDojo, such as: defectdojo-import-scan⁠

However, we want to be able to upload results to an internal, non-Internet-accessible DefectDojo instance, potentially using an internal CI/CD system (e.g., a Jenkins instance).

Configuration for the tool is expected to be provided by environment variables; this is to support clean integration with a CI/CD system that populates environment variables rather than using flags. Additionally, the tool is able to use a configuration file (e.g., .env) that can provide values.

The expected usage pattern is for a repository to include a configuration file with parameters like project name, whether or not to push results to Jira, etc. and environment variables to pass server details and authentication credentials. It's possible to use all environment variables or all configuration files or some mix.

The script supports passing multiple files to be uploaded, even if those files are in different locations or even associated with different projects. In situations like these, a configuration file for each location is supported.

Several locations for configuration files are searched with the first one found being used:

1. current directory's uploadsarifdd.conf
2. current directory's .uploadsarifdd.conf
3. file's repo's uploadsarifdd.conf
4. file's repo's .uploadsarifdd.conf
5. ~/uploadsarifdd.conf
6. ~/.uploadsarifdd.conf

Future plans may include supporting additional scan types and/or additional fields from DefectDojo's import-scan endpoint.

⁠Glob Behavior

When passing patterns such as *.sarif, the script distinguishes between an unmatched glob and a missing explicit filename.

If a glob pattern matches no files, the script treats this as a successful no-op (there were no SARIF files to upload).

If an explicitly named file does not exist, the script exits with an error.

⁠Examples

upload_sarif_to_defectdojo.bash megalinter-reports/sarif/*.sarif

⁠CLI Flags

⁠Containerized Usage

The tool may also be used in containerized form; a Dockerfile⁠ has been provided to simplify running it.

⁠Building the Image

docker build \
  -t ghcr.io/wesley-dean/upload-sarif-to-defectdojo \
  .

⁠Running the Image

docker run \
  --rm \
  -it -v "$PWD:$PWD" \
  -w "$PWD" \
  -u "$UID" \
  ghcr.io/wesley-dean/upload-sarif-to-defectdojo \
  megalinter-reports/sarif/*.sarif

⁠Configuration Values

⁠DD_TOKEN

DD_TOKEN is the authentication token for interacting with DefectDojo (required).

DD_TOKEN is required!!

The API token may be found through DefectDojo's web user interface by going to <server name>/api/key-v2

Note: there is no CLI argument to pass the token via the command line as doing so may result in the token being stored in the shell's history; it must be passed via environment variable or configuration file.

⁠DD_PRODUCT

DD_PRODUCT is the name of the product in DefectDojo (required)

DD_PRODUCT is required!!

⁠DD_ENGAGEMENT

DD_ENGAGEMENT is name of the engagement in DefectDojo.

The default value is "cicd" (lowercase, no slash).

Set via CLI with -e or --engagement

⁠DD_SERVER_PROTO

DD_SERVER_PROTO is the protocol / scheme to use when talking to DefectDojo.

The default value is https.

⁠DD_SERVER_HOST

DD_SERVER_HOST is the hostname of the DefectDojo server (required)

Set via CLI with -s or --server

⁠DD_SERVER_PATH

DD_SERVER_PATH is path on the server to the import-scan API endpoint

The default is /api/v2/import-scan/ which is the standard when DefectDojo runs at the root of the server (i.e., dojo.example.com)

⁠DD_SCAN_DATE

DD_SCAN_DATE is the date the scan took place

DefectDojo accepts ISO-8601 dates (but just year, month, and day) for when scans took place; the default value is when the file being uploaded was last modified

Set via CLI with -d or --date

⁠DD_MINIMUM_SEVERITY (-S)

DD_MINIMUM_SEVERITY is the minimum severity level to be imported

Set via CLI with -S or --severity.

The default value is 'Info'; values may be:

• Info
• Low
• Medium
• High
• Critical

⁠DD_ACTIVE

DD_ACTIVE specifies whether or not the findings are active

the default value is 'true'

⁠DD_VERIFIED

DD_VERIFIED specifies whether or not a finding has been verified

The default value is 'true'

⁠DD_SCAN_TYPE

DD_SCAN_TYPE is the type of scan results to be imported

Set via CLI with -t or --scan-type

The default value is determined by the file's extension

⁠DD_CLOSE_OLD_FINDINGS

DD_CLOSE_OLD_FINDINGS is to close old findings as mitigated when importing

The default value is 'false'

⁠DD_CLOSE_OLD_FINDINGS_PRODUCT_SCOPE

DD_CLOSE_OLD_FINDINGS_PRODUCT_SCOPE will restrict closing to this product

The default value is 'false'

⁠DD_PUSH_TO_JIRA

DD_PUSH_TO_JIRA is whether or not to push findings to Jira as well

The default value is 'false'

⁠DD_FILE_TYPE

DD_FILE_TYPE is the MIME type for the file to be uploaded

Set via CLI with -m or --mime-type

The default value is determined by the file's extension

⁠DD_BRANCH

DD_BRANCH is the SCM branch where the finding was applicable

Set via CLI with -b or --branch

This is an optional field with no default

⁠DD_COMMIT_HASH

DD_COMMIT_HASH is the hash of the commit that is being examined

This is optional and the default value is determined using git log.

⁠DD_SCM_URL

DD_SCM_URL is the URL to the Source Code Management system for this repo

This is optional and the default value is determined using git remote. Please be aware that some SCM URLs may include encoded credentials; the default is filtered to remove such credentials (and any .git on the end of the URL).

⁠Project Governance

This repository adopts released engineering standards from wesley-dean/coding_standards⁠. The complete snapshot used by this project is committed under doc/standards/, and .codingstandardrc records the exact release and release-archive SHA-256 digest.

Applicable standards are project requirements. Accepted repository-specific ADRs and explicit local policy may refine or supersede them. Imported files under doc/standards/ are not edited locally.

⁠Runtime and Testing

The directly downloadable public executable remains upload_sarif_to_defectdojo.bash. The supported runtime is Bash 4.3 or newer on Linux. A normal upload requires curl; Git is optional and is used only to enrich imports with branch, commit, and source-management metadata.

Behavior tests use Bats and do not require a live DefectDojo instance or real API token. Run them with:

make test

make check performs Bash syntax and ShellCheck validation, and make format applies the repository's shfmt policy.

⁠Repository Dependencies and Build

Repository-scoped Bash dependencies are pinned and verified with bashdeps⁠. The maintained uploader source is src/upload_sarif_to_defectdojo.bash. Builds produce documented, ordinary, and minified standalone artifacts beneath dist/; the root upload_sarif_to_defectdojo.bash file is a generated, committed ordinary compatibility artifact for the historical raw-download and container paths.

Prepare dependencies and regenerate the standalone public artifact with:

make deps
make deps-check
make build

make deps may access the network. make deps-check, make build, and make test do not synchronize dependencies. make test builds and exercises all three distribution flavors, so prepared dependencies must already exist. Every generated executable embeds the pinned bashlog library; runtime users do not need vendor/, bashdeps, Bash-Minifier, or network access.

Operational log records use bashlog⁠ and are written to STDERR. Interactive STDERR uses bashlog's human presentation; redirected or captured STDERR uses deterministic logfmt. The uploader does not invoke logger(1) or send directly to syslog.

⁠Distribution Artifacts

make build generates three standalone executable representations and adjacent SHA-256 companions:

dist/upload_sarif_to_defectdojo.dev.bash
dist/upload_sarif_to_defectdojo.dev.bash.sha256
dist/upload_sarif_to_defectdojo.bash
dist/upload_sarif_to_defectdojo.bash.sha256
dist/upload_sarif_to_defectdojo.min.bash
dist/upload_sarif_to_defectdojo.min.bash.sha256

The .dev.bash artifact retains Doxygen/source documentation, the ordinary .bash artifact removes full-line comments, and the .min.bash artifact is derived from the ordinary representation with the pinned Bash-Minifier revision. All three pass the same behavior suite. The root upload_sarif_to_defectdojo.bash remains the stable compatibility download and uses the ordinary representation.

dist/ is generated derivative state. It is ignored by Git and excluded from source/security scanning; correctness is established through deterministic builds, syntax/runtime tests, behavior equivalence, and checksum verification. CI uploads all six files as build artifacts, and semantic-version releases attach the same six validated files.

⁠ADR Inventory

The curated current-decision digest in doc/adr/README.md is maintained by contributors above <!-- adrctl-generated-footer -->. The exhaustive inventory below that marker is generated with the pinned adrctl dependency.

After adding, renaming, or removing an ADR, prepare dependencies if necessary and regenerate the landing page with:

make deps
make adr-index

make adr-index is network-free. Do not hand-edit the generated footer; CI regenerates it, verifies that the curated prefix is unchanged, and checks that repeated generation is byte-identical.

⁠Reference Documentation

Maintained Bash source documentation is compiled with the pinned bash-doxygen⁠ filter and Doxygen.

Prepare dependencies, then generate the reference site with:

make deps
make deps-check
make docs

make docs is network-free and writes derivative HTML beneath doc/reference/. That directory is ignored and should not be committed. Use make docs-clean to remove generated reference output.

Pull-request CI verifies that the documentation can be generated from maintained source. Pushes to main rebuild the same reference tree and publish doc/reference/ to GitHub Pages.

⁠Configuration Precedence

Configuration files are trusted executable Bash and are sourced intentionally. Only use configuration files you trust.

When the same setting is provided from multiple sources, precedence is:

1. command-line option;
2. pre-existing environment variable;
3. selected configuration file; and
4. built-in default.

An explicit --config / -c path is considered before automatic discovery. If explicit configuration paths are supplied and none is readable, the command fails instead of silently selecting a different discovered file.

⁠Security Note

Configuration files are sourced as executable shell code. This means that any commands contained in those files will be executed in the context of this script.

Only use configuration files from repositories or environments that you trust. Do not source configuration files from untrusted pull requests, forks, or external contributions without review.