av image scan

Scan a container image and tier every finding REDYELLOWGREEN.

Synopsis

av image scan <image-ref> [flags]

The binary ships as alertavuln; av is the common alias - they are interchangeable in every example.

Description

av image scan inspects a container image for known vulnerabilities in its OS packages (deb / apk / rpm) and the application dependencies baked into its layers, and normalises everything into one finding set tiered RED / YELLOW / GREEN. The same run also produces a CycloneDX inventory of the image and records its metadata - digest, OS, and base-image candidates.

The scan runs where the image is reachable - your dev machine or CI runner - using your own container registry credentials from your local Docker configuration. Those credentials never reach AlertaVuln. By default the target is a live image reference the scanner pulls or reads from the local daemon; you can instead scan a saved image tarball with --archive, or an existing CycloneDX SBOM with --sbom (no image pull at all).

Pass --project to upload the findings and the inventory so they appear on the project’s Containers page. --no-upload keeps a scan local-only even when --project is set. On upload, the server owns the authoritative RED / YELLOW / GREEN tier - the CLI display is a local preview.

For CI gating, --fail-on makes the command exit non-zero when the worst finding is at or above the given tier.

Options

Flag	Default	Description
--project	-	Project ID to upload findings to (omit for a local-only scan)
--archive	-	Scan a saved image tarball (docker save output) instead of a live reference
--sbom	-	Scan an existing CycloneDX SBOM (JSON) instead of pulling an image
--format	table	Output format: table or json
--no-upload	false	Scan locally only; do not upload even if --project is set
--fail-on	none	Exit non-zero if the worst finding is at or above the tier: red, yellow, or none

Examples

Scan a live image reference:

av image scan acme/api:1.2.3

Scan and upload the findings to a project’s Containers page:

av image scan acme/api:1.2.3 --project <projectId>

Gate a CI pipeline - the run exits non-zero on a RED finding:

av image scan acme/api:1.2.3 --project <projectId> --fail-on red

Scan a saved image tarball on an air-gapped runner:

docker save acme/api:1.2.3 -o api.tar
av image scan --archive api.tar --project <projectId>

Note

The scanner is auto-downloaded - pinned and checksum-verified - on first use and runs locally. The CLI reports it by a neutral capability label, container-scanner, rather than a product name. Only when you pass --project are the resulting findings and the image inventory uploaded - never your registry credentials.

Exit codes

Code	Meaning
0	Scan completed and no finding is at or above the --fail-on tier
1	Scan failed, or at least one finding is at or above the --fail-on tier

See also

• av image findings - pull the consolidated container findings the server holds for a project
• av image list - list a project’s scanned images
• Base image advice - safer base images with concrete vuln deltas
• Container image scanning - what container scanning covers, and the CLI-scan + server-monitor model