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 — run gosec source-code security analysis
• just sbom — generate a CycloneDX SBOM via cyclonedx-gomod
• just 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:

1. Confirm reachability: govulncheck already 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.
2. Prefer upgrades: bump the dependency/module to a fixed version when possible. Dependabot usually opens the PR automatically.
3. Track exceptions explicitly: if a finding is accepted (e.g., non-reachable, false positive), document the reasoning in the PR that dismisses the alert.
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.
• govulncheck job fails with no obvious finding: inspect the workflow log — govulncheck exits non-zero on any reachable vulnerability, including transitive ones. The log enumerates each finding with its GO-YYYY-NNNN ID and call stack.