Skip to main content

Images in CI/CD pipelines

deaconguard image scan checks an image in a pipeline, before it is pushed or deployed, and deaconguard config scan checks its Dockerfile and Kubernetes manifests. It reads the image as data and never runs it, so it needs no Docker daemon, no root and no DeaconGuard server. It needs DeaconGuard 1.4.0 or later.

What it can check​

ArgumentWhat it reads
nginx:1.27, ghcr.io/acme/shop:4.2An image in its registry. See Images in registries.
image.tar, docker-archive:image.tarAn archive from docker save or podman save, compressed with gzip or not.
oci:layout/, oci:image.tarAn OCI image layout, a folder or a tar of one, as docker buildx build --output type=oci, buildah push or skopeo copy write it. --platform picks one of several platforms.
dir:path/A folder: an image's unpacked files, a chroot, or a project. Its OS packages are checked when it has a package database, and its lock files (package-lock.json, requirements.txt, go.mod, Cargo.lock and the others in Libraries) and compiled Go programs, such as a build's output, against OSV.

Without a prefix, a path that exists is read as what it holds: an archive with manifest.json is a docker save archive, one with index.json and oci-layout an OCI layout, and a plain folder a folder. Anything else is an image name.

Archives and layouts are checked like registry images: layers named by digest must match it. Symbolic links in a folder are never followed outside it.

docker build -t shop:ci .
docker save shop:ci -o shop.tar
deaconguard image scan shop.tar --fail-on high

Failing the build​

--fail-on critical, high, medium or low makes the command exit with status 4 when the image has a vulnerability at or above that severity, so the pipeline stops. Vulnerabilities with no published severity don't count. An image on a release that has ended, such as Debian 10, has a high finding for it (DG-EOL-001), so --fail-on high stops it.

--ignore-unfixed counts, and reports, only the vulnerabilities an update fixes or attackers are known to use. A vulnerability with no fix yet can't be fixed by rebuilding, so it doesn't fail the build.

Exit statusMeans
0Checked; nothing at or above --fail-on
4Checked; vulnerabilities at or above --fail-on
1Not checked: the image couldn't be read, or an option is wrong

Reports​

--format chooses what the command writes, and --output FILE writes it to a file and keeps the summary in the job's log. --summary FILE (1.35.0 and later) also adds a Markdown summary to a file: whether the check passed, the counts by severity and the 20 worst findings with what to do about each. The GitHub action puts it on the run's Summary page; elsewhere, give it any file your pipeline shows:

--formatFor
tablePeople: the summary and what to fix (the default)
jsonScripts: the result and every vulnerability, with fixable and known_exploited
sarifSARIF 2.1.0 for GitHub code scanning, GitLab, Azure DevOps and other code-scanning tools: one result per vulnerability and package, with GitHub's security-severity
junitJUnit XML for GitLab, Jenkins, Bitbucket and Azure DevOps test reports: a test case per vulnerability; those at or above --fail-on fail
cyclonedx, spdxA software bill of materials of the image's packages and libraries: CycloneDX 1.6 or SPDX 2.3 JSON, as for hosts
deaconguard image scan shop.tar --ignore-unfixed --fail-on high --format sarif --output deaconguard.sarif
deaconguard image scan shop.tar --format cyclonedx --output shop.cdx.json

Progress goes to standard error, so a report on standard output can be piped.

What leaves the machine​

Only what any image check sends: OS package checks use the advisory data DeaconGuard downloads, and libraries are checked against OSV, which is sent their names and versions. The image itself, and its files, stay where they are. To scan without these downloads on each run, cache $DEACONGUARD_HOME (by default ~/.local/share/deaconguard for a user) between jobs: it holds the advisory data and the layer cache.

GitHub Actions​

The DeaconGuard action installs the command (checking the release's signature and checksum), keeps the advisory data in the Actions cache for a day, runs the check, fails the job on what you choose, and shows what it found on the run's Summary page. This works in public and private repositories on every GitHub plan:

jobs:
deaconguard:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@v7

- name: Build the image
run: docker build -t shop:${{ github.sha }} . && docker save shop:${{ github.sha }} -o shop.tar

- name: Check the image
uses: Cloudopsshell/deaconguard@v1.35.0
with:
target: shop.tar
fail-on: high
ignore-unfixed: "true"

- name: Check the Dockerfile and manifests
if: always()
uses: Cloudopsshell/deaconguard@v1.35.0
with:
scan: config
target: Dockerfile deploy
fail-on: high
output: config.sarif

- name: Keep the reports
if: always()
uses: actions/upload-artifact@v7
with:
name: deaconguard-reports
path: "*.sarif"

Where the results show​

WhereWhatNeeds
The job's resultPassed, or failed with "DeaconGuard found problems at or above high"fail-on
The run's Summary pageWhether each check passed, the counts by severity, and the 20 worst findings with what to do about each; the rest are in the report (1.35.0 and later)Nothing: on by default, on every plan, in private repositories too. summary: "false" turns it off
The job's logThe same findings as textNothing
The report fileEvery finding, as SARIF, JUnit, JSON or an SBOM; keep it with actions/upload-artifactNothing
The repository's Security → Code scanning pageFindings as alerts that GitHub tracks between runs and shows on pull requestsupload-sarif: "true", and see below

Code scanning​

upload-sarif: "true" also sends the SARIF report to GitHub code scanning. The report goes to your own repository's Security tab and nowhere else. It shows the same findings as the Summary page, as alerts GitHub remembers between runs. GitHub decides who can use it:

RepositoryCode scanning
PublicAvailable, free
Private or internalNeeds GitHub Code Security (part of what was GitHub Advanced Security), a paid GitHub add-on; see GitHub's code scanning documentation for who can buy it

The job then needs these permissions:

permissions:
contents: read
security-events: write # to upload to code scanning
actions: read # in a private repository

From 1.35.0 a refused upload is a warning, with why, and doesn't fail the job: whether the job passes depends on what the check found. Before 1.35.0 a refused upload failed the job, even for a clean image; leave upload-sarif off there unless the repository has code scanning.

InputDefault
scanimageimage, or config for Dockerfiles and Kubernetes manifests
targetThe image or path; for config, files and folders separated by spaces
fail-oncritical, high, medium or low fails the step; empty only reports
ignore-unfixedfalseImages: count and report only what an update fixes
platformthe runner'sImages: a platform of a multi-platform image
skipConfig: rules to leave out
format, outputsarif, deaconguard.sarifThe report and its file
summarytrueShow what was found on the run's Summary page (1.35.0 and later)
upload-sariffalseAlso upload the SARIF report to code scanning: a public repository, or GitHub Code Security on a private one
categorydeaconguard-image or deaconguard-configThe code scanning category
registry, registry-username, registry-passwordA login for a private registry, from secrets; sent to registry only
versionthe action's releaseA release such as 1.35.0, latest, or installed for a deaconguard already on the PATH
cachetrueKeep the advisory data and layer cache between runs

The status output is 0, or 4 when there were findings at or above fail-on; summary is true when the Summary page got the findings. Pin the action to a release, as above, or to its commit.

For an image in GHCR, use the job's token:

- uses: Cloudopsshell/deaconguard@v1.35.0
with:
target: ghcr.io/${{ github.repository }}:${{ github.sha }}
registry: ghcr.io
registry-username: ${{ github.actor }}
registry-password: ${{ secrets.GITHUB_TOKEN }} # the job needs packages: read

GitLab CI​

Include the template from a release, and extend its jobs. They run in alpine:3.22, need no Docker or privileges, show findings as test results with JUnit, keep SARIF as an artifact, and give GitLab the image's CycloneDX SBOM:

include:
- remote: https://raw.githubusercontent.com/Cloudopsshell/deaconguard/v1.35.0/ci/gitlab/deaconguard.gitlab-ci.yml

deaconguard-image:
extends: .deaconguard-image
needs: [build]
variables:
DEACONGUARD_VERSION: "1.35.0"
DEACONGUARD_TARGET: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
DEACONGUARD_FAIL_ON: high
DEACONGUARD_ARGS: --ignore-unfixed

deaconguard-config:
extends: .deaconguard-config
variables:
DEACONGUARD_VERSION: "1.35.0"
DEACONGUARD_FAIL_ON: high

The image job logs in to $CI_REGISTRY with the job's own token, and only there (DEACONGUARD_REGISTRY). DEACONGUARD_TARGET can also be an archive or OCI layout an earlier job left as an artifact.

Other CI systems​

Everywhere else, install the command with ci/install.sh from a release, which checks the release's signature and checksum, needs no root, and installs only the deaconguard binary:

curl -fsSL https://raw.githubusercontent.com/Cloudopsshell/deaconguard/v1.35.0/ci/install.sh | sh -s -- 1.35.0 "$HOME/.local/bin"

It needs Linux on amd64 or arm64, curl and sha256sum.

Jenkins​

pipeline {
agent any
environment { PATH = "${env.HOME}/.local/bin:${env.PATH}" }
stages {
stage('DeaconGuard') {
steps {
sh 'curl -fsSL https://raw.githubusercontent.com/Cloudopsshell/deaconguard/v1.35.0/ci/install.sh | sh -s -- 1.35.0'
sh 'docker save shop:${GIT_COMMIT} -o shop.tar'
sh 'deaconguard image scan shop.tar --ignore-unfixed --fail-on high --format junit --output deaconguard-image.xml'
sh 'deaconguard config scan . --fail-on high --format junit --output deaconguard-config.xml'
}
}
}
post {
always { junit allowEmptyResults: true, testResults: 'deaconguard-*.xml' }
}
}

With the Warnings Next Generation plugin, --format sarif and recordIssues(tools: [sarif(pattern: 'deaconguard.sarif')]) show the findings as issues instead.

Bitbucket Pipelines​

Bitbucket shows JUnit reports it finds under test-results/:

pipelines:
default:
- step:
name: DeaconGuard
image: alpine:3.22
script:
- apk add --no-cache curl
- curl -fsSL https://raw.githubusercontent.com/Cloudopsshell/deaconguard/v1.35.0/ci/install.sh | sh -s -- 1.35.0 /usr/local/bin
- mkdir -p test-results
- deaconguard config scan . --fail-on high --format junit --output test-results/deaconguard-config.xml
- deaconguard image scan "$IMAGE" --ignore-unfixed --fail-on high --format junit --output test-results/deaconguard-image.xml

For a private image, set DEACONGUARD_REGISTRY, DEACONGUARD_REGISTRY_USERNAME and DEACONGUARD_REGISTRY_PASSWORD as secured repository variables.

Azure DevOps​

steps:
- script: curl -fsSL https://raw.githubusercontent.com/Cloudopsshell/deaconguard/v1.35.0/ci/install.sh | sh -s -- 1.35.0 "$HOME/.local/bin"
displayName: Install DeaconGuard
- script: |
export PATH="$HOME/.local/bin:$PATH"
deaconguard image scan "$(image)" --ignore-unfixed --fail-on high --format junit --output deaconguard-image.xml
displayName: Check the image
- task: PublishTestResults@2
condition: always()
inputs:
testResultsFormat: JUnit
testResultsFiles: deaconguard-*.xml

To see SARIF in Azure DevOps, publish the --format sarif report as a build artifact named CodeAnalysisLogs, which the SARIF SAST Scans Tab extension shows.