image-scan¶
Scans the image tarball a build job produced, twice, because two different people can act on the two answers — and, when told where, keeps one issue per image current with the findings so the answer reaches someone.
| job | what it scans | gate |
|---|---|---|
scan:os |
OS packages (--pkg-types os) — ours to fix with a base bump |
hard; your publish jobs needs: it |
scan:tools |
library packages inside upstream tool binaries (--pkg-types library) — cleared only when upstream rebuilds |
advisory by default (tools_allow_failure) |
scan:report |
nothing; reads the two JSON artifacts and upserts the dashboard issue | never gates (allow_failure: true) |
Each scan runs trivy once to JSON and renders the table in the job log from that JSON, so the report and the log describe the same findings.
Why the report exists¶
The nightly rebuild + rescan schedules on the image repositories catch a
newly-disclosed advisory against what is already shipped. They were doing
that — and telling nobody: an advisory scan:tools failure under a green
pipeline sat in a job log for weeks. Spec 0099 D6 puts it this way: the
release merge request gates what is about to ship; the nightly rescan is
surveillance of what has shipped, and the gap between releases was
measured at 17–24 days for five of the eight images.
The dashboard issue¶
scan:report exists only when report_project is set, and runs only on
default-branch pipelines (report_if) — a merge-request pipeline scans a
branch build, and a branch's findings are not what the image ships. Use a
private project: the body carries unpatched advisories.
On every run it:
- finds the issue by a marker in its body carrying
$CI_PROJECT_PATH(the title is cosmetic; renaming it is safe), creating it withreport_labelif absent; - always rewrites the body — findings per section, and a
Last scannedline with the pipeline URL. This happens on a closed issue too: a clean image and a dead token must not look the same, and a stale stamp is the tell; - posts one comment listing new and cleared findings, only when the set changed;
- closes the issue when both sections are empty, and reopens it on a finding, so history stays on one issue.
A finding is identified by (advisory, package, installed version). The body
also carries the rendered markdown as the image-scan-report.md artifact.
A scan that did not run is not a clean scan. scan:report runs
when: always so a failed scan still reports, but when a scan was skipped —
the build failed — there is no JSON, and the job exits 2 without touching
the issue. Reading absence as zero once closed a real dashboard issue as
clean.
Inputs¶
| Input | Type | Default | Description |
|---|---|---|---|
stage |
string | scan |
Stage for all three jobs. You must declare it. |
trivy_image |
string | ghcr.io/aquasecurity/trivy:0.73.0 |
Trivy image the scan jobs run in. |
trivy_cache_dir |
string | /opt/ci-cache/trivy |
Shared trivy cache. When the vuln DB there was downloaded under 48 hours ago it is copied into a job-local cache and the scan runs offline; the Java DB, when both its files are there and it was downloaded under six days ago, is linked rather than copied. Absent or older, the vuln DB is downloaded before the scan and retried from ghcr.io if mirror.gcr.io fails; trivy fetches the Java DB as normal. |
runner_tags |
array | ["linux", "amd64", "trivy-cache"] |
Runner tags for both scan jobs. The default keeps them on the runner that holds the shared trivy DB; elsewhere they download it online, which is slower and leans on the ghcr.io retry when the mirror fails. Set [] where no runner carries these tags. |
build_job |
string | build |
Your job whose artifact carries the tarball; both scans needs: it. |
input_tar |
string | image.tar |
Tarball passed to trivy image --input. |
severity |
string | HIGH,CRITICAL |
Severities that count, for gating and reporting alike. |
ignore_unfixed |
boolean | true |
Only advisories with a fixed version count. |
tools_allow_failure |
boolean | true |
Whether scan:tools is advisory. docs-tools sets false. |
if |
string | $CI_COMMIT_SHA |
rules:if: for the scan jobs. Always true by default. |
report_project |
string | "" |
Project holding the dashboard issue. Empty means no scan:report job. |
report_token |
string | $REPORTER_TOKEN |
Token with api scope on report_project. Not a job token, which cannot write another project's issues. |
report_title |
string | Image scan: $CI_PROJECT_NAME |
Issue title. |
report_label |
string | security-advisory |
Label applied on create and re-applied on update. |
image_version |
string | "v0.3.4" |
phpboyscout/images/ci-base tag scan:report runs on. |
report_if |
string | $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH |
rules:if: for scan:report; runs when: always so a failed scan still reports. |
report_dry_run |
boolean | false |
Render the body and the change comment to the log; write nothing, need no token. |
report_token defaults to $REPORTER_TOKEN rather than $CI_JOB_TOKEN,
because a job token cannot write issues in another project. Under
spec 0108
that makes it a purpose-named, hidden variable holding a service account's
token, the token-input convention's
rule for anything the job token cannot do. It defaulted to the group
GITLAB_TOKEN until that variable was retired on 2026-10-07, so a consumer
still relying on it has to define REPORTER_TOKEN or pass the input.
Jobs produced¶
| Job | Runs when |
|---|---|
scan:os |
if (every pipeline by default) |
scan:tools |
if (every pipeline by default) |
scan:report |
report_project set and report_if (default-branch pipelines) |
Usage¶
Replacing a hand-written .scan-base / scan:os / scan:tools trio is a
drop-in: the job names are the same, so a publish job's
needs: ["scan:os"] keeps working.
stages: [lint, build, scan, publish]
include:
- component: gitlab.com/phpboyscout/cicd/[email protected]
inputs:
stage: scan
report_project: phpboyscout-private/org
The shared DB cache is copied, not opened¶
trivy keeps its cache in BoltDB. Two jobs on one runner opening the same file
lock each other out, so the cached DB is copied into /tmp for the job and
--skip-db-update runs against the copy. The metadata's UpdatedAt is
echoed so the log says how fresh the DB was.
trivy's Java DB is separate, and only an image holding jars needs it. Its
update is skipped only when the cache holds both trivy-java.db and its
metadata.json. With either missing, --skip-java-db-update is a fatal error
at the first jar, so trivy is left to fetch it instead. android-tools was the
first image to hit this. The Java DB is SQLite, which takes concurrent readers,
so it is linked into the job's cache rather than copied: at 1.5 GB, a copy per
scan job was most of the job's disk.
A cached DB is trusted only while it is recent, so a missed refresh cannot pass a
scan against old advisories. The vuln DB's limit is 48 hours, which tolerates one
missed night. The Java DB's is six days, because trivy does not download it again
until its NextUpdate, so a healthy download can be four days old. Age comes from
metadata.json, which trivy writes at download; the DB files keep upstream's build
time. A date ahead of the clock counts as stale too. Past the limit the job logs a warning and takes the same path as an absent
DB, so a stale cache combined with an upstream outage fails the scan rather than
passing it (wiki spec 0127).
What the self-test cannot prove¶
The live write. The report token belongs in a protected variable, which a merge-request pipeline never sees, and a job token cannot create issues. The self-test scans a real tarball and renders the report in dry-run; the write is verified at the consumer, on its first default-branch pipeline after adoption.
See also¶
image-release— the release-time path, which relies on the release merge request having scanned the tagged commit- Spec 0099