Shared CI building blocks: two composite actions, sbom-scan (an SBOM and a vulnerability gate)
and sbom-store (put-once storage of what was scanned), whose scripts also run locally.
- uses: Arkiv-Network/ci-tools/sbom-scan@<commit sha>
with:
sources: docker:my-app:${{ github.sha }}Pin a full commit SHA: the runner fetches this repository at that SHA, with no credential. Each source gets a syft SBOM and a grype report, the job a Markdown step summary, and the step fails on fixable High-and-above findings.
| input | default | meaning |
|---|---|---|
sources |
required | one source per line: registry:<ref>@sha256:…, docker:<tag>, dir:<path>, oci-archive:<file>, or sbom:<path or https URL> for a ready-made SBOM, which grype scans directly |
fail-on |
high |
lowest severity that fails: critical, high, medium, low, negligible |
only-fixed |
true |
count only findings with a fix available toward the gate |
ignore-file |
`` | the ignore ledger; when empty, .grype.yaml at the workspace root if it exists |
fail |
true |
false = report only |
output-dir |
sbom-scan |
where files land, relative to the workspace |
artifact-name |
sbom-scan |
workflow artifact holding output-dir; empty = no upload |
public |
false |
true for a public repository: ignored findings read accepted, the ledger stays out of output-dir, nothing is uploaded (Public callers) |
| output | meaning |
|---|---|
failed |
true when the gate found something — also with fail: false |
fixable-high / fixable-critical |
findings at High or above (Critical), not ignored, with a fix |
unfixed-high / unfixed-critical |
findings at High or above (Critical), not ignored, without a fix |
ignored-high / ignored-critical |
findings at High or above (Critical) accepted by an ignore rule, fixed or not |
kev |
findings on the CISA Known Exploited Vulnerabilities list, any severity, not ignored |
ignored-kev |
findings on the CISA KEV list, any severity, accepted by an ignore rule |
output-dir / summary-json |
absolute path of the output directory / of summary.json |
The gate counts non-ignored findings at or above fail-on (grype's severities) with a fix, when
only-fixed; unfixed ones are reported, not failed. It is decided from the report, not grype's exit
code. Output files, summary.json and exit codes: docs/sbom-scan.md.
One ledger per repository: ignore-file, or .grype.yaml at the workspace root. A rule names a
vulnerability, a package (by location or name), or both, and needs a reason and an
expires at most 180 days ahead; an expired or malformed rule fails the scan. Lint with
mise exec -- bin/check-grype-ignores .grype.yaml; the full grammar (location globs, anchored-regex
names, rejected keys, catch-alls) is in docs/sbom-scan.md.
ignore:
- vulnerability: CVE-2024-12345
reason: not reachable — the image never parses untrusted input with libfoo
expires: 2027-01-31
- package: {location: /usr/local/bin/some-tool}
reason: upstream binary at its newest release
expires: 2027-04-01A public repository's logs, summary and artifacts are readable by anyone. public: "true" keeps
rule reasons out of them (the grype reports on disk keep them, for a private store). Keep the ledger
in a private repository, fetched with a read-only deploy key: public half on the ledger repository,
private half the caller's Actions secret. Fork PRs get no secrets, so there the scan is report-only:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
if: github.event.pull_request.head.repo.fork != true
with:
repository: example-org/sbom-ledgers
ssh-key: ${{ secrets.SBOM_LEDGER_KEY }}
path: ledger
- uses: Arkiv-Network/ci-tools/sbom-scan@<commit sha>
with:
sources: docker:my-app:${{ github.sha }}
ignore-file: ${{ github.event.pull_request.head.repo.fork != true && 'ledger/my-app.grype.yaml' || '' }}
fail: ${{ github.event.pull_request.head.repo.fork != true }}
public: "true"Stores SBOMs, grype reports and a run manifest in the SBOM bucket put-once, lists the SBOMs the
bucket lacks, so only those are scanned, and fetches the ones it holds, so grype re-matches them
without pulling the image. The job uses a GitHub Environment restricted to main:
environment: sbom-writer
env:
R2_SBOM_ENDPOINT: ${{ secrets.R2_SBOM_ENDPOINT }}
R2_SBOM_BUCKET: ${{ secrets.R2_SBOM_BUCKET }}
R2_SBOM_ACCESS_KEY_ID: ${{ secrets.R2_SBOM_ACCESS_KEY_ID }}
R2_SBOM_SECRET_ACCESS_KEY: ${{ secrets.R2_SBOM_SECRET_ACCESS_KEY }}
steps:
- id: missing
uses: Arkiv-Network/ci-tools/sbom-store@<commit sha>
with: {mode: missing, lines: "${{ steps.inventory.outputs.lines }}"}
# sbom-scan with fail: false over the third field of each missing line, then:
- uses: Arkiv-Network/ci-tools/sbom-store@<commit sha>
with: {mode: put, source: my-app, lines: "${{ steps.inventory.outputs.lines }}"}| input | default | meaning |
|---|---|---|
mode |
required | missing, get or put |
lines |
required | one <key> <ref|-> <source> per line: sha256:<hex>, the image ref or -, the sbom-scan source |
scan-dir |
sbom-scan |
put: the sbom-scan output directory |
source |
`` | put: the run's source name — the repository for a builder, the cluster for a cluster scan |
meta |
`` | put: a JSON file {"<key>": {"namespaces": […], "nodes": […]}} added to the manifest's images; empty = none |
out-dir |
sbom-get |
get: where the fetched syft SBOMs land |
| output | meaning |
|---|---|
lines |
missing: the input lines whose SBOM is absent from the bucket; get: every input line, its source sbom:<out-dir>/sha256-<hex>.syft.json when the bucket holds the key's SBOMs |
A cluster run re-matches the SBOMs the bucket holds and scans only the rest, then stores each report, the SBOMs of what was scanned, and where each image runs:
- id: get
uses: Arkiv-Network/ci-tools/sbom-store@<commit sha>
with: {mode: get, lines: "${{ steps.inventory.outputs.lines }}"}
# sbom-scan with fail: false over the third field of each line of steps.get.outputs.lines, then:
- uses: Arkiv-Network/ci-tools/sbom-store@<commit sha>
with:
mode: put
source: cluster-a
lines: ${{ steps.get.outputs.lines }}
meta: inventory/meta.jsonBucket contract: docs/storage.md. missing, get, put, exit codes: docs/sbom-store.md.
mise install
mise exec -- bin/sbom-scan [--out DIR] [--fail-on SEV] [--ignore FILE]… [--no-fail] SOURCE…
mise exec -- bin/sbom-store missing <LINES
mise exec -- bin/sbom-store get --out DIR <LINES
mise exec -- bash bin/tests/<name>.test.shLicensed under either of Apache License, Version 2.0 (LICENSE-APACHE) or MIT
license (LICENSE-MIT) at your option. Unless you explicitly state otherwise, any
contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0
license, shall be dual licensed as above, without any additional terms or conditions.