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#
Continuous security scanning is defined by .github/workflows/security.yml. The workflow runs on every push to main, every pull request, and on a weekly schedule (Mondays at 06:00 UTC).
| Scanner | Scope | Output |
|---|---|---|
| govulncheck | Go vulnerability database scan across the module graph (./...) | Workflow log; job fails on findings |
| CodeQL (Go) | Semantic static analysis for Go source | SARIF → GitHub Security / Code scanning |
| Trivy (fs) | Filesystem SCA + misconfiguration scan | SARIF → GitHub Security / Code scanning |
The Trivy job is configured with ignore-unfixed: true and reports CRITICAL, HIGH, and MEDIUM findings.
Two additional workflows round out the supply-chain posture:
.github/workflows/scorecard.yml— OSSF Scorecard repository hygiene scoring..github/workflows/sbom.yml— SBOM generation for the repository..github/dependabot.yml— automated dependency update PRs.
Outputs and where to find them#
GitHub Security tab (SARIF)#
CodeQL and Trivy upload SARIF results, so findings appear under GitHub → Security → Code scanning alerts.
Workflow logs#
govulncheck reports vulnerabilities directly in the job log and fails the job on any finding. Findings include the vulnerability ID, affected package, and call stack when reachable.
Release SBOMs#
Every GoReleaser-produced release includes a CycloneDX SBOM (*.bom.json) alongside each binary archive and package. See docs/development/releasing.md for the full release artifact list.
How to run scans locally#
The project provides just targets for local security workflows:
just scan— rungosecsource-code security analysisjust sbom— generate a CycloneDX SBOM viacyclonedx-gomodjust security-all— run gosec and SBOM generation together
To run govulncheck locally:
go install golang.org/x/vuln/cmd/govulncheck@latest
govulncheck ./...
Trivy and CodeQL are only run in CI. If you need to reproduce a Trivy finding locally, install the CLI from the upstream project and run trivy fs --severity CRITICAL,HIGH,MEDIUM --ignore-unfixed ..
Interpreting and addressing findings#
When a vulnerability is reported:
- Confirm reachability:
govulncheckalready reports whether the vulnerable symbol is reached from the module's call graph. For Trivy or CodeQL findings, verify the affected code path is actually executed. - Prefer upgrades: bump the dependency/module to a fixed version when possible. Dependabot usually opens the PR automatically.
- Track exceptions explicitly: if a finding is accepted (e.g., non-reachable, false positive), document the reasoning in the PR that dismisses the alert.
- 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.
govulncheckjob fails with no obvious finding: inspect the workflow log —govulncheckexits non-zero on any reachable vulnerability, including transitive ones. The log enumerates each finding with itsGO-YYYY-NNNNID and call stack.
