Container image security scanning run book
Purpose
This run book explains how to build container images locally using either Docker or Podman and scan them for security vulnerabilities using Aqua Trivy (and optionally Anchore Grype) prior to publishing them to Azure Container Registry (ACR). It also documents scanning remote images directly in ACR and gating deployment pipelines.
This run book supports: - Blob processor local run book - GraphQL processor local run book
Base image architecture
All application Dockerfiles use Microsoft's hardened Azure Linux 3.0 Distroless base image:
mcr.microsoft.com/dotnet/aspnet:10.0-azurelinux3.0-distroless-extra
Key security characteristics:
- Distroless runtime: Zero shell (/bin/sh, /bin/bash), zero package manager (tdnf, apt, apk), and no core utilities (curl, wget).
- Minimal attack surface: Contains only 13 minimal RPM packages required by .NET (compared to ~97 packages in standard Ubuntu/Debian images).
- Non-root execution: Runs as non-root user $APP_UID (UID 1654).
- Full globalization: The -extra variant bundles ICU globalization and tzdata, ensuring accurate UK NHS patient record string comparison and date collation.
- glibc compatibility: Full compatibility with standard native C runtime libraries without the DNS or memory allocation quirks of musl.
Prerequisites
Docker users
- Docker Desktop or Docker Engine installed (
docker --version). - Docker daemon running (
docker info).
Podman users
- Podman installed (
podman --version). - Podman machine running on macOS:
podman machine start
Build images locally
Run these commands from the repository root:
With Docker
Build the external API image:
docker build -t external-api:local -f src/external-api/Dockerfile .
Build the matching API image:
docker build -t matching-api:local -f src/matching-api/Dockerfile .
Build the storage processor job image:
docker build -t sui-client-storage-process-job:local -f src/SUI.Client/SUI.Client.StorageProcessJob/Dockerfile .
Build the GraphQL processor job image:
docker build -t sui-client-graphql-process-job:local -f src/SUI.Client/SUI.Client.GraphQLProcessJob/Dockerfile .
Build the PDS emulator image (optional test dependency):
docker build -t pds-emulator:local -f src/tools/pds-emulator/Dockerfile .
With Podman
Build the external API image:
podman build -t external-api:local -f src/external-api/Dockerfile .
Build the matching API image:
podman build -t matching-api:local -f src/matching-api/Dockerfile .
Build the storage processor job image:
podman build -t sui-client-storage-process-job:local -f src/SUI.Client/SUI.Client.StorageProcessJob/Dockerfile .
Build the GraphQL processor job image:
podman build -t sui-client-graphql-process-job:local -f src/SUI.Client/SUI.Client.GraphQLProcessJob/Dockerfile .
Build the PDS emulator image (optional test dependency):
podman build -t pds-emulator:local -f src/tools/pds-emulator/Dockerfile .
Scan images for vulnerabilities with Aqua Trivy
Aqua Trivy is the project's standard vulnerability scanner, mirroring
.github/workflows/gh-trivy.yml. It scans both the minimal OS layer (Azure Linux RPM packages) and application-level language
dependencies (NuGet packages recorded in .deps.json).
Trivy runs directly inside a container without needing any host binaries installed.
With Docker
docker run --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
-v trivy-cache:/root/.cache/ \
aquasec/trivy image external-api:local
With Podman
podman run --rm \
--security-opt label=disable \
--user 0 \
-v /run/podman/podman.sock:/var/run/docker.sock \
-v trivy-cache:/root/.cache/ \
aquasec/trivy image localhost/external-api:local
Command options explained
-v /var/run/docker.sock:/var/run/docker.sock(Docker) /-v /run/podman/podman.sock:/var/run/docker.sock(Podman): Mounts the container engine socket into the container so Trivy can inspect local images without pushing them to a registry.--security-opt label=disable(Podman only): Disables container SELinux separation so the container can access the mounted Podman socket.--user 0(Podman only): Runs the scanner container as root inside the container to grant read permissions to the forwarded socket inside the Podman machine.-v trivy-cache:/root/.cache/: Caches the downloaded vulnerability database in a named volume so subsequent scans complete rapidly.
Generate vulnerability reports
Human-readable summary table (default)
Run the scan command above without output format flags to display the console table with vulnerability breakdown by target and severity.
Export a structured JSON report
Export vulnerability scan results to a JSON file in the repository root:
With Docker:
docker run --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
-v "$(pwd)":/reports \
aquasec/trivy image \
--format json \
--output /reports/external-api-trivy-report.json \
external-api:local
With Podman:
podman run --rm \
--security-opt label=disable \
--user 0 \
-v /run/podman/podman.sock:/var/run/docker.sock \
-v "$(pwd)":/reports \
aquasec/trivy image \
--format json \
--output /reports/external-api-trivy-report.json \
localhost/external-api:local
Export an HTML report
Generate a self-contained HTML vulnerability report for sharing or auditing:
With Docker:
docker run --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
-v "$(pwd)":/reports \
aquasec/trivy image \
--format template \
--template "@/contrib/html.tpl" \
--output /reports/external-api-trivy-report.html \
external-api:local
With Podman:
podman run --rm \
--security-opt label=disable \
--user 0 \
-v /run/podman/podman.sock:/var/run/docker.sock \
-v "$(pwd)":/reports \
aquasec/trivy image \
--format template \
--template "@/contrib/html.tpl" \
--output /reports/external-api-trivy-report.html \
localhost/external-api:local
Automated quality gate (fail on High or Critical)
To use the scan as an automated gate in scripts or CI pipelines (returns exit code 1 if any HIGH or CRITICAL issues exist):
With Docker:
docker run --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
aquasec/trivy image \
--exit-code 1 \
--severity HIGH,CRITICAL \
external-api:local
With Podman:
podman run --rm \
--security-opt label=disable \
--user 0 \
-v /run/podman/podman.sock:/var/run/docker.sock \
aquasec/trivy image \
--exit-code 1 \
--severity HIGH,CRITICAL \
localhost/external-api:local
Scan remote images in Azure Container Registry (ACR)
Trivy can also scan images published in ACR directly using a temporary OAuth token without downloading the entire image to your machine:
With Docker:
ACR_TOKEN="$(az acr login --name "${ACR_NAME}" --expose-token --output tsv --query accessToken)"
docker run --rm \
-e TRIVY_USERNAME=00000000-0000-0000-0000-000000000000 \
-e TRIVY_PASSWORD="${ACR_TOKEN}" \
-v trivy-cache:/root/.cache/ \
aquasec/trivy image \
--exit-code 1 \
--severity HIGH,CRITICAL \
"${ACR_LOGIN_SERVER}/${IMAGE_REPOSITORY}:${IMAGE_TAG}"
With Podman:
ACR_TOKEN="$(az acr login --name "${ACR_NAME}" --expose-token --output tsv --query accessToken)"
podman run --rm \
-e TRIVY_USERNAME=00000000-0000-0000-0000-000000000000 \
-e TRIVY_PASSWORD="${ACR_TOKEN}" \
-v trivy-cache:/root/.cache/ \
aquasec/trivy image \
--exit-code 1 \
--severity HIGH,CRITICAL \
"${ACR_LOGIN_SERVER}/${IMAGE_REPOSITORY}:${IMAGE_TAG}"
Cross-validate with Anchore Grype (optional)
Optionally cross-validate vulnerability results using Anchore Grype:
With Docker:
docker run --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
anchore/grype:latest external-api:local
With Podman:
podman run --rm \
--security-opt label=disable \
--user 0 \
-v /run/podman/podman.sock:/var/run/docker.sock \
anchore/grype:latest localhost/external-api:local