Scan Container Images in CI
Overview
Section titled “Overview”fencer scan image scans one container image digest from a registry Fencer is already connected
to, waits for the scan, and exits non-zero unless the scan finished cleanly with no findings at or
above a severity threshold. Use it as a build gate: build and push the image, then scan that push
before you deploy it.
Fencer pulls the image from your registry. It never reads a local Docker daemon or an image archive, so a freshly built image must be pushed to a connected registry before it can be scanned.
Prerequisites
Section titled “Prerequisites”- The image’s registry is connected to Fencer (a cloud integration with container scanning, or a Container Registry integration), and Fencer has discovered the image’s repository at least once. The repository shows up under Artifacts. A new tag or digest in a known repository needs no new discovery; a brand-new repository does.
- A service-account token whose role holds
scans:execute,scans:readandvulnerabilities:read, stored as a CI secret. Withoutvulnerabilities:readthe scan runs but its findings can’t be read, so the command reports an error. - The Fencer CLI on the CI runner.
Scan a fresh build (GitHub Actions)
Section titled “Scan a fresh build (GitHub Actions)”This workflow builds and pushes an image, then scans exactly the digest it pushed:
name: buildon: [push]
jobs: image: runs-on: ubuntu-latest permissions: contents: read packages: write steps: - uses: actions/checkout@v4
- uses: docker/login-action@v3 with: registry: ghcr.io username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }}
- id: build uses: docker/build-push-action@v6 with: push: true platforms: linux/amd64 tags: ghcr.io/acme/app:${{ github.sha }}
- name: Install the Fencer CLI run: curl -fsSL https://raw.githubusercontent.com/Fencer-Security/cli/main/scripts/install.sh | sh
- name: Scan the pushed image env: FENCER_TOKEN: ${{ secrets.FENCER_TOKEN }} FENCER_ORG: your-org-slug run: | fencer scan image "ghcr.io/acme/app:${{ github.sha }}@${{ steps.build.outputs.digest }}" \ --platform linux/amd64 --fail-on high --timeout 30mPassing name:tag@sha256:<digest> pins the scan to that digest, so a later push to the same tag
cannot change what this build is judged on. Concurrent builds each get their own scan.
build-push-action pushes a multi-platform index even for one platform, so pass --platform with
the os/arch you deploy. Fencer scans exactly that platform and fails the scan if the image doesn’t
have it. Without --platform, Fencer tries the artifact’s platform first, then falls back to other
common platforms; the platform it scanned is printed and included in the JSON output.
The platform is whatever your build targets: the platforms input of build-push-action, or the
--platform you pass to docker build. A build without either targets the runner’s own platform,
linux/amd64 on GitHub’s standard runners. To list the platforms an already-pushed image has, run
docker buildx imagetools inspect <image>.
Scan an image that is already in a registry
Section titled “Scan an image that is already in a registry”Point the command at the image. A digest reference is scanned as is; a tag is resolved to the digest it points to when the scan is queued, and that digest is what gets scanned. A tag can move between your push and that moment (another build pushing the same tag, for example), so the command warns when no digest is given; pass the digest whenever your pipeline has it:
fencer scan image 123456789012.dkr.ecr.us-east-1.amazonaws.com/app@sha256:4f6e…fencer scan image 123456789012.dkr.ecr.us-east-1.amazonaws.com/app:release-2026-11Tag resolution needs a registry that supports tag tracking; for any other registry, pass the digest. Fencer pulls private images with the credentials of the connected integration, so the CI runner needs no registry access of its own.
When two artifacts share the image name (the same repository connected through two sources), pass
--artifact <slug> to choose one.
Pass, fail, and errors
Section titled “Pass, fail, and errors”| Outcome | When | Exit code |
|---|---|---|
| pass | The scan finished with no unignored findings at or above --fail-on |
0 |
| fail | The scan finished with one or more unignored findings at or above --fail-on |
1 |
| error | The scan could not be queued (missing token, a role without scans:execute, no container scanning on the plan, an unknown repository, a tag that cannot be resolved), or it failed, was cancelled, skipped or timed out, finished with any warning (for example, the registry denied the pull), or did not finish within --timeout |
2 |
An error is never reported as a pass, and exit code 1 always means findings. While waiting, the
command retries brief network failures, server errors and rate limiting until --timeout. Queuing
the scan is retried only when the API answers that the rate limit was hit; any other API error ends
the command at once, with the reason on stderr.
--fail-on takes critical, high (the default), medium, low or info. Findings at that
severity and above count.
Ignored findings: a finding someone has ignored in Fencer is listed in the output but never fails the gate, and it stays ignored for every later CI scan of that artifact, whatever the scan finds in it. Fencer groups container findings by area: every vulnerability in the image’s operating system packages is one finding (for example “Debian 12”), and each language package path is another. Ignoring a finding therefore covers every current and future vulnerability in that area, including new critical ones. Findings that have no upstream fix yet are ignored automatically when deferring vulnerabilities without an upstream patch is on; those count as ignored here too.
While the artifact’s newest image has a newer version available, Fencer reports that image’s findings together as one “newer version” finding. An ignore on that finding does not carry over to CI scans, whose findings are grouped by area as above.
Results and output
Section titled “Results and output”The command prints the scan’s link in Fencer as soon as the scan is queued. The scan appears in the
artifact’s scan history, described as triggered by a CI build of its commit. The CI run URL, ref and
repository are stored with the scan too. On GitHub Actions these are filled in automatically;
elsewhere pass --ci-run-url, --commit, --ref and --ci-repository.
CI scans are kept apart from the artifact’s regular results: their findings never change the artifact’s open vulnerabilities, they send no notifications, they aren’t triaged, they do not replace the artifact’s latest scan, and they never change the artifact’s platform or suspend its scanning.
For a machine-readable summary, add --output json:
{ "scan": { "scan": "SCAN-9RG", "artifact": "ARES-AJ3", "artifact_name": "ghcr.io/acme/app", "image": "ghcr.io/acme/app:3f2c…@sha256:4f6e…", "tag": "3f2c…", "digest": "sha256:4f6e…", "platform": "linux/amd64", "status": "queued", "results_url": "https://app.fencer.dev/a/your-org-slug/scan/SCAN-9RG" }, "gate": { "result": "fail", "reason": "2 finding(s) at or above high", "status": "finished", "platform": "linux/amd64", "fail_on": "high", "blocking": [{ "slug": "VULN-1A2", "title": "…", "severity": 1 }], "ignored": [] }}Options
Section titled “Options”| Flag | Default | Description |
|---|---|---|
--fail-on |
high |
Lowest severity that fails the gate |
--timeout |
30m |
How long to wait for the scan before reporting an error |
--poll-interval |
10s |
How often to check the scan |
--platform |
os/arch to scan exactly, e.g. linux/arm64 |
|
--artifact |
Artifact slug, when several artifacts share the image name | |
--no-wait |
Queue the scan, print its link, and exit without gating |
Limitations
Section titled “Limitations”- Each repository must be discovered once before its images can be scanned from CI. New tags and digests in a known repository need no discovery.
- The command stops waiting at
--timeout, but the scan keeps running in Fencer. - Requests are rate-limited to 30 per minute per service account.