Skip to content

Vulnerability Scanning & SBOMs

opnDossier is designed for offline and airgapped environments, but the project itself is developed with supply-chain security and vulnerability transparency in mind.

This document explains:

  • what security scanning runs in CI,
  • what artifacts are produced (reports + SBOMs), and
  • how to interpret and act on findings.

What runs in CI

Two GitHub Actions workflows provide vulnerability scanning:

  • CI workflow: runs on pull requests and pushes.
  • Scheduled workflow: runs daily at midnight UTC and can be triggered manually.

Both workflows run Grype scans in two modes:

  1. Filesystem scan: scans the repository workspace (.).
  2. Go module dependency scan: explicitly scans the Go module manifest (go.mod) to surface dependency vulnerabilities directly.

Severity thresholds

The CI workflow applies a branch-aware policy for the filesystem scan:

  • On main: fail the job when findings are \(\\ge\) medium severity.
  • On non-main branches: fail the job when findings are \(\\ge\) high severity.

The Go module dependency scan uses a strict cutoff of critical.

The scheduled workflow is configured to not fail the build (to reduce alert fatigue), but it still uploads results and artifacts.

Outputs and where to find them

GitHub Security tab (SARIF)

Both workflows upload SARIF results so findings appear under GitHub → Security → Code scanning alerts.

Workflow artifacts

Each run publishes downloadable artifacts:

  • SBOM artifacts (sbom-reports)
  • sbom.spdx.json (SPDX JSON)
  • sbom.cyclonedx.json (CycloneDX JSON)
  • Vulnerability report artifacts (vulnerability-reports)
  • vulnerability-report.txt (human-readable table)
  • vulnerability-report.json (machine-readable JSON)

Artifacts are retained for 30 days.

How to run scans locally

The project provides just targets for local security workflows:

  • just scan - run vulnerability scanning locally
  • just sbom - generate SBOM artifacts locally

Interpreting and addressing findings

When a vulnerability is reported:

  1. Confirm reachability: determine whether the vulnerable dependency is actually used at runtime.
  2. Prefer upgrades: bump the dependency/module to a fixed version when possible.
  3. Track exceptions explicitly: if a finding is accepted (e.g., non-reachable, false positive), document the reasoning and constraints.
  4. Avoid breaking offline-first: do not add runtime network dependencies as a “fix”.

Troubleshooting

  • SARIF upload succeeds but you see no alerts: GitHub may take a short time to index results; also ensure the repository has code scanning enabled.
  • Artifacts missing on failing scans: artifact steps are configured to run with if: always(), so missing artifacts typically indicate that the Grype CLI wasn’t available or the workflow was interrupted.