docker-trivy/README.md

docker-vuln-scan

Scan Docker images for vulnerabilities with Trivy and get an Apprise notification whenever a HIGH or CRITICAL finding is detected.

By default it scans the images used by running containers, so a scheduled run covers whatever is actually deployed. Specific images can still be passed explicitly.

Everything runs from one container image (Trivy + Apprise + Python), so the host only needs Docker. JSON reports are kept on disk for auditing.

How it works

1. scan.py determines which images to scan (see Which images are scanned) and runs trivy image for each of them, writing a JSON report to /reports/<image>.json. Optional VEX sources are applied through Trivy's --vex flag, so findings marked as not affected are filtered out before counting and notifying (see VEX).
2. Findings are aggregated by CVE across all scanned images. Two thresholds are checked against the aggregate counts:
   • NOTIFY_MIN_SEVERITY (default HIGH) – when to send a single Apprise alert.
   • FAIL_ON (default HIGH) – when the script should exit with code 1 (useful for CI).
3. Notifications are sent. When IMPORTANT_CONTAINERS is set, each named container gets its own complete CVE list plus a fenced monospaced table of image/container severity counts (C, H, M, L), even if there are no CVEs at or above NOTIFY_MIN_SEVERITY. Missing important containers are reported, every other container is summarised in chunks using the same table, and one final notification lists the important packages plus the overall totals. Columns below NOTIFY_MIN_SEVERITY are omitted. Without IMPORTANT_CONTAINERS, a single aggregated notification lists each CVE with the affected packages, containers, and images.

Quick start

cd docker-vuln-scan
cp .env.example .env        # set APPRISE_URLS; IMAGES is optional
docker compose build
docker compose run --rm vulnscan

Or without Compose:

docker build -t docker-vuln-scan:latest .

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v "$PWD/reports:/reports" \
  -v trivy-cache:/var/lib/trivy \
  -e APPRISE_URLS='discord://webhook_id/webhook_token' \
  docker-vuln-scan:latest

Reports land in ./reports/.

Which images are scanned

The list is built from these sources, in order:

1. image arguments: scan.py nginx:1.27-alpine redis:7-alpine
2. the IMAGES environment variable (space or newline separated)
3. the IMAGES_FILE environment variable (one image per line, # comments)
4. the images used by running containers (the default when nothing is configured)

For the last one the scanner asks the Docker Engine API on the Unix socket for /containers/json and scans each Image reference, de-duplicated and in listing order. Stopped containers are not included. The scanner's own container image is skipped so a scheduled run does not report on itself; set INCLUDE_SELF=true to include it. Scan logs still name the running container(s) that use each image (e.g. Scanning nginx:1.27 (used by container web)). Without IMPORTANT_CONTAINERS, notifications are aggregated by CVE after all images are scanned: a single report lists each CVE with the containers and images it affects. With IMPORTANT_CONTAINERS, each named container gets its own full CVE list and the remaining containers are summarised together (see Important containers). Scan failures still notify per failed image with container context. Explicitly passed images omit container context unless IMPORTANT_CONTAINERS is set, in which case running containers are looked up to match them to the scanned images.

The socket is looked up in this order:

• DOCKER_SOCK (explicit path)
• DOCKER_HOST when it is a unix:// URL
• /var/run/docker.sock and /run/docker.sock
• $XDG_RUNTIME_DIR/docker.sock
• /run/user/<uid>/docker.sock and /run/user/<uid>/podman/podman.sock (rootless Docker and Podman), plus any /run/user/*/docker.sock if /run/user is mounted into the container
• ~/.docker/run/docker.sock (Docker Desktop)

If no socket is reachable, the docker CLI is used as a fallback. When neither works and no explicit images were given, the run logs a warning and exits 0 with nothing to scan.

Rootless Docker

Rootless Docker keeps its socket under the user runtime directory, so /var/run/docker.sock does not exist on the host. The Compose file mounts /run/user (read-only), so the scanner finds the socket automatically. If your socket lives elsewhere, set DOCKER_SOCK to its path; Compose mounts it at the same path inside the container:

# Find the socket path (strip the leading unix://)
docker context inspect --format '{{.Endpoints.docker.Host}}'
# unix:///run/user/1000/docker.sock

export DOCKER_SOCK=/run/user/1000/docker.sock
docker compose run --rm vulnscan

To make it permanent, add the same line to .env:

DOCKER_SOCK=/run/user/1000/docker.sock

Without Compose:

docker run --rm \
  -v /run/user:/run/user:ro \
  -v "$PWD/reports:/reports" \
  docker-vuln-scan:latest

Scanning a registry image works without the Docker socket; the socket is needed for auto-discovery and for images that exist only in the local daemon. When no socket is reachable and IMAGES is empty, the scanner logs a warning explaining exactly that and exits 0.

Komodo

Ready-to-apply Komodo Resource Sync definitions live in komodo/: a Stack that builds and runs the scanner, plus a nightly Procedure schedule. Findings still go through Apprise; Komodo only triggers the job.

Configuration

All configuration is done through environment variables.

Variable	Default	Description
IMAGES	(images in use)	Space/newline separated image references. When empty, running containers are scanned.
IMAGES_FILE	–	File with one image per line (# comments allowed).
DOCKER_SOCK	auto	Unix socket of the Docker daemon (or Podman). Also the Compose mount source.
DOCKER_HOST	–	Standard Docker variable; unix:// paths are used for discovery.
INCLUDE_SELF	false	Also scan the scanner's own image when auto-discovering.
IMPORTANT_CONTAINERS	–	Container names (space/comma separated) that get a full per-container CVE notification. Others are summarised together.
APPRISE_URLS	–	Space separated Apprise URLs (quote the value).
APPRISE_CONFIG	–	Alternative: path to an Apprise YAML config.
APPRISE_TITLE_PREFIX	Vulnerability scan	Prefix of notification titles.
NOTIFY_MIN_SEVERITY	HIGH	NONE, LOW, MEDIUM, HIGH, CRITICAL. NONE disables alerts.
FAIL_ON	HIGH	Exit 1 when a finding at/above this severity exists. NONE never fails.
IGNORE_UNFIXED	false	Skip vulnerabilities without a fixed version.
TRIVY_SEVERITIES	(all)	Restrict severities Trivy reports, e.g. HIGH,CRITICAL.
TRIVY_VEX	–	VEX sources passed to Trivy: repo, oci, sbom-ref, or file paths.
NOTIFY_ON_SCAN_ERROR	true	Also alert when Trivy itself fails (e.g. image pull error).
REPORT_DIR	/reports	Where JSON reports are written.
TRIVY_CACHE_DIR	/var/lib/trivy	Trivy DB cache (mount a volume to avoid re-downloading).
TRIVY_TIMEOUT	15m	Passed to trivy --timeout.
MAX_FINDINGS_IN_BODY	15	How many findings the single aggregated notification lists. Important-container notifications are not capped.
LOG_LEVEL	INFO	DEBUG, INFO, WARN or ERROR.

Images can be passed as arguments, via IMAGES, or via IMAGES_FILE; the sources are combined and de-duplicated. If all of them are empty, the images in use are scanned.

VEX

Trivy can filter findings with VEX (Vulnerability Exploitability eXchange) documents. Set TRIVY_VEX to one or more space-separated sources; each is passed to trivy image --vex:

# VEX Hub / repository lookup
TRIVY_VEX=repo

# VEX attestations attached to the image in an OCI registry
TRIVY_VEX=oci

# Local OpenVEX or CycloneDX VEX documents (mount them into the container)
TRIVY_VEX=/vex/app.json /vex/base.json

# Several methods; the first source has the highest priority
TRIVY_VEX="/vex/app.json repo"

For local files with Compose, mount the directory read-only:

volumes:
  - ./vex:/vex:ro
environment:
  TRIVY_VEX: /vex/app.json

Findings suppressed by VEX are removed from the Trivy JSON report and are therefore not counted, notified, or considered by FAIL_ON. The report still reflects the filtered result.

Apprise URLs

APPRISE_URLS accepts any Apprise URL. Common examples:

# Email (use an app password, not your account password)
APPRISE_URLS='mailto://user:app-password@gmail.com'

# Discord webhook
APPRISE_URLS='discord://webhook_id/webhook_token'

# Slack
APPRISE_URLS='slack://token_a/token_b/token_c/#security'

# Telegram
APPRISE_URLS='tgram://bot_token/chat_id'

# Several targets at once (quote the whole value)
APPRISE_URLS='mailto://user:app-password@gmail.com tgram://bot_token/chat_id'

For many targets or reusable credentials, mount an Apprise config file and set APPRISE_CONFIG:

# apprise.yml
urls:
  - mailto://user:app-password@gmail.com
  - discord://webhook_id/webhook_token

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v "$PWD/apprise.yml:/config/apprise.yml:ro" \
  -e APPRISE_CONFIG=/config/apprise.yml \
  docker-vuln-scan:latest nginx:1.27-alpine

Important containers

Set IMPORTANT_CONTAINERS to the containers that are reachable from outside (your public entry points). Names are matched against running containers, so leave IMAGES empty unless you also want to scan specific images explicitly.

IMPORTANT_CONTAINERS=traefik web-frontend

When the list is set, notifications are split into four groups:

1. One notification per important container, titled Vulnerability scan: <container> (<image>). It lists every CVE at or above NOTIFY_MIN_SEVERITY, with the image/container and severity counts shown in a padded fenced monospaced table (Image, Container, C, H, M, L). A notification is still sent if there are none, showing totals at 0/0.
2. One notification for important containers that are missing – either not running, or running an image that was not part of the scan.
3. One summary notification for every other container, split every ~12 containers, showing the same fenced table of image/container and fixable/total severity counts.
4. One final summary notification listing the important containers in the same table, their packages, followed by the overall severity counts and fixable/total in N container(s).

Severity columns below NOTIFY_MIN_SEVERITY are omitted from the tables (for example, only C and H are shown when it is HIGH). Image digests are shortened to their first six characters in notification text; report filenames keep the full reference.

A container can appear in only the important list or the summary, never both. If an important container shares its image with other containers, the others still appear in the summary. Important-container lists are never truncated: if a list is longer than the Apprise/Discord message limit it is sent in numbered parts. FAIL_ON and the exit codes are unchanged.

Without IMPORTANT_CONTAINERS, the previous single aggregated notification is sent.

Code	Meaning
0	All images scanned, no finding reached FAIL_ON (or nothing to scan).
1	At least one image reached FAIL_ON.
2	A scan or notification failed (bad image, registry error, Apprise error).

Scheduling and CI

Nightly scan of the images in use:

0 3 * * * cd /opt/docker-vuln-scan && docker compose run --rm vulnscan >> scan.log 2>&1

Scan every local image instead, but do not fail the job:

IMAGES="$(docker image ls --format '{{.Repository}}:{{.Tag}}' | grep -v '<none>')" \
FAIL_ON=NONE \
APPRISE_URLS='mailto://user:app-password@gmail.com' \
docker compose run --rm vulnscan

GitLab CI job:

container_scan:
  image: docker:27
  services: [docker:27-dind]
  script:
    - docker build -t docker-vuln-scan:latest .
    - >
      docker run --rm
      -e APPRISE_URLS="$APPRISE_URLS"
      -e FAIL_ON=HIGH
      -v /var/run/docker.sock:/var/run/docker.sock:ro
      docker-vuln-scan:latest "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA"

Development

scan.py uses only the Python standard library; tests need neither Docker nor Trivy nor Apprise (a fake Docker socket and fake binaries are used):

python3 -m unittest discover -s tests -v

tests/test_scan.py covers socket discovery (including rootless paths and self-skip), report parsing, thresholds, notification bodies, and full runs of main() with a fake trivy and apprise.

Notes and limitations

• The container mounts the Docker socket read-only, but the process still runs as root inside the container. That is equivalent to root on the host – run it only on trusted machines / CI runners.
• Rootless Docker uses a different socket path. The Compose file mounts /run/user so it is found automatically; for sockets elsewhere, set DOCKER_SOCK as shown above, otherwise the scanner sees no containers.
• Private registries: Trivy reads the standard variables (TRIVY_USERNAME, TRIVY_PASSWORD, TRIVY_INSECURE, DOCKER_CONFIG). Pass them with -e.
• The first scan downloads the Trivy vulnerability database; keep /var/lib/trivy on a volume and it is reused.
• aquasec/trivy:latest is used as the source of the Trivy binary. For reproducible builds pin it: docker build --build-arg TRIVY_IMAGE=aquasec/trivy:0.XX.Y .
• Notifications are informational: a failed Apprise delivery makes the run exit with 2 so monitoring can catch a broken alerting path.