To scan a container image from the command line, install the Safeguard CLI and run its scan command with the image option and the image name. Add your registry username and password for a private registry. The CLI builds a list of what is inside the image and checks it against vulnerability databases.
TL;DR
- A container image holds your app and also an operating system. Both can carry known flaws.
- With the Safeguard CLI, one command scans one image. Private registries are supported with a username and password.
- Results land in JSON files in an output folder.
- A scan reports. A policy gate decides whether a release is allowed.
Definition: A container image is a packaged bundle of an app plus everything it needs to run, such as system libraries and tools. A container is a running copy of that image. Teams build images once and run them in many places.
Why does a container image need its own scan?
Picture a shipping container. You packed your goods, but the box itself has a floor, walls and a lock. If the lock is faulty, it does not matter how well you packed.
A container image is similar. The Safeguard demo on this topic puts it plainly: an image ships an operating system as well as your app, and both carry vulnerabilities. Your dependency scan covers the packages your app asked for. It does not cover the operating system packages that came with the base image you started from.
Many teams only find this out after a security review. Their app packages are clean, but the base image is a year old and full of known flaws. Scanning the image closes that gap.
For a look at running image scans inside a pipeline, see our post on automating container image scans. This post is about the hands on steps.
What do I need first?
You need three things:
- The Safeguard CLI installed. The install steps are in our CLI install guide. On macOS and Linux it is one curl command, and on Windows one PowerShell command.
- The name of the image you want to check, such as nginx:latest or the full address of an image in your own registry.
- If the image is private, the username and password (or token) for the registry that holds it.
The documentation says the CLI is one static program with nothing else to install, except the scanner tools it downloads the first time you open its interactive terminal. The scan uses two helper tools named syft and grype. Syft builds the list of what is inside. Grype matches that list to known vulnerabilities.
On a fresh machine such as a new CI container, open the interactive terminal once so it can download them, or put both on your path yourself.
What is the command?
For a public image:
safeguard scan --image nginx:latest
For an image in a private registry:
safeguard scan --image myregistry.azurecr.io/myapp:v1 \
--registry-username "$REGISTRY_USER" \
--registry-password "$REGISTRY_PASSWORD"
Notice the two variables. Do not type a real password straight into the command, because it ends up in your shell history. Keep it in an environment variable or a secret store instead.
The scan command takes exactly one target. If you want to scan an image and a folder, run two commands.
Some other useful options from the usage guide:
| Option | What it does |
|---|---|
| Output folder | Choose where result files go (the default is a folder named output) |
| Scanners | Run only the scanners you name |
| Verbose | Show more detail while the scan runs |
Run safeguard scan with the help option to see the full list in your build.
Where do the results go, and how do I read them?
The scan writes JSON files into the output folder. JSON is plain text that programs can read. You will find a file of vulnerabilities and a file of licenses, along with others.
If you scan from the interactive terminal while signed in, the runner also uploads the SBOM (the list of ingredients) and the findings to the platform, so you can see them next to your other projects. The documentation says it uploads only results, never your source code.
When you read the findings, sort by these questions:
- Which layer is it in? A flaw in the operating system layer is usually fixed by moving to a newer base image. A flaw in an app package is usually fixed by upgrading that package.
- Is there a fixed version? If yes, the fix is often a rebuild.
- How severe is it, and does it matter here? A flaw in a tool your container never runs is less urgent than one in the web server it runs all day.
The Safeguard container scan demo lists what to upgrade in each layer of the stack. That matches the first question above.
How do I scan every image I have?
Scanning one image by hand is fine for a first look. For the rest, think about three habits.
- Scan at build time. Put the scan in your pipeline so a new image is checked before it ships. Our pipeline guide shows the pattern.
- Scan what is already running. Images that shipped last year may now have flaws that were unknown then. A scan at build time is a snapshot. See our post on continuous vulnerability management.
- Scan the base image alone. If many apps share one base image, fixing it once helps all of them.
If you use Podman instead of Docker, the CLI also has a podman command that lists and scans the images in a Podman store, with no Docker needed. The documentation says to start the Podman socket first.
What does an image scan look like with invented numbers?
Here is a pretend run. The numbers are invented to show the thinking.
Your team ships an image called billing-api. You scan it. The CLI finds 58 known issues. Of those, 41 sit in the base operating system layer and 17 sit in app packages.
You check the base image. Your Dockerfile starts from an older version of the base. A newer tag of the same base image has fixes for 36 of the 41 operating system issues. You change one line in the Dockerfile to use the newer tag, rebuild, and rescan. Now the count is 22. The remaining 17 are app packages, and 5 are operating system issues with no fix yet.
You upgrade four of the app packages that have fixed versions. After the rebuild, 18 issues remain, 13 app and 5 operating system.
One line change and a few upgrades took you from 58 to 18. That is the typical shape: the biggest win is often the base image. Your real numbers will differ.
Does the scan block a release?
No. The scan reports. It exits with a success code whenever it ran, even if it found problems. The documentation says there is no severity threshold option on the CLI, and that blocking on findings is the job of policy gates in the platform. If you want a release to stop on critical findings, set up a gate. Our gate guide walks through it.
How can Safeguard help?
The CLI is one door into Safeguard. Behind it are generally available capabilities that help with images and the rest of your software:
- SBOM and dependency scanning, including images, with findings kept in one place.
- Reachability analysis, to rank findings by whether your code can reach the flaw.
- Policies, gates and guardrails, to decide what may ship.
- Autonomous remediation with fix pull requests, which is off by default and starts on Manual in every category.
The CLI also includes an assistant that can write code, for example to update a package file. It asks before it changes anything unless you pick a mode that does not. If you want a quick, no install look at your packages first, try the free scan at gold.safeguard.sh/scan. That page checks dependency files and SBOMs rather than images.
Try it yourself
Click through it at your own pace, or open it full screen.
Click through the seven steps and look for how findings are split by layer, so you know whether to change the base image or an app package.
Quick check
Do I need Docker installed to scan an image?
The documentation does not list Docker as a requirement for the scan command. It does say the CLI downloads two helper tools, syft and grype, the first time you open its interactive terminal. For Podman there is a separate command that uses the Podman API and needs no Docker.
How do I scan an image in a private registry?
Add the registry username and password options to the scan command. Keep the values in environment variables or a secret store, not in the command text.
Why does my app scan look clean while the image scan does not?
An app scan covers your packages. An image also carries an operating system and its tools, and those have their own known flaws. Updating the base image often clears many of them.
Does the image scan upload my image?
The CLI scans on your machine. The documentation says it uploads only the SBOM and findings when you scan signed in from the interactive terminal, never your source code.
Sources
- CLI usage documentation
- CLI installation documentation
- Safeguard download page
- Container image scan demo
- Safeguard Gold, Free Dependency Scan
Last reviewed: 19 October 2026.
