Skip to main content
Most vulnerabilities in a container image typically come from its base image rather than your application code. Base image remediation helps you attribute findings to the base image layer and choose a base image update that resolves the most findings with the least risk. Base image remediation is available through the endorctl container scan command. Endor Labs identifies the base image your application image is built on and attributes findings to the base and application layers. It then compares newer base image versions so you can plan a safe upgrade. See Scan containers using endorctl to set up a container scan.

​
How base image remediation works

Base image remediation builds on base image detection during a container scan. The workflow has the following stages.
1

Base image detection

Container scanning identifies the base image your application image is built on. It looks for a base image you scanned earlier, one present in your container runtime, a base image label, or a name you provide with --base-image-name or --dockerfile-path. Detecting the base image separates vulnerabilities in the base image layers from those introduced by your application.
2

Update candidate discovery

Endor Labs discovers a refreshed build of the current tag, the next version, and the latest version as candidate updates for your base image. Auto-discovery of the next and latest tags is limited to base images on Docker Hub, including private repositories. For base images in other registries, point to those tags with --base-image-tag-next and --base-image-tag-latest. For more information, see Perform base image remediation.
3

Impact analysis

Impact analysis scans each candidate base image and compares it against your current base image. The comparison reports how many findings each update would fix, how many it would introduce, and the change in findings broken down by severity and reachability.
4

Remediation guidance

Remediation guidance recommends the base image version that resolves the most findings at an acceptable risk of breaking changes. Update your project’s base image reference to that version, then rebuild and rescan the image to see the updated findings. For more information, see View update options.

​
Perform base image remediation

To compute the base image update options, scan your application image with the --base-image-check-updates flag. Choose the approach that matches how your base image is detected. Auto-discovery of the next and latest versions is best effort, so scan the base image first when you need more predictable results.
When the base image is available in your local container runtime, Endor Labs detects it automatically. Run the scan with --base-image-check-updates.
When the base image is not in your local container runtime, such as a CI environment that scans a tar file, scan the base image first as its own project. Then scan your application image with --base-image-check-updates. Scanning the exact base image first is the most reliable and recommended approach for CI.
  1. Scan the base image.
  2. Scan the application image.
When the base image is present under multiple names or tags, use --base-image-name to specify which one, along with the --base-image-check-updates flag.
To read the base image name from the Dockerfile that built the application image, use --dockerfile-path along with --base-image-check-updates. This flag is incompatible with --base-image-name.
Pre-scanning the base image and pinning the candidate tags address different needs. Pre-scanning identifies the base image, while --base-image-tag-next and --base-image-tag-latest name the next and latest versions when auto-discovery can’t determine them. Both flags require --base-image-check-updates, and each flag takes a single tag.

​
View update options

You can view how the findings of your scanned application image would change with each base image update option. The results reflect the last scan and are not recomputed when you run this command. To recompute the update options, run the container scan with --base-image-check-updates again. Each update option is a version of your base image that you can move to:
  • Refreshed: The current base image tag resolved to its newest digest. Your version stays the same, but the image now includes the patches that were published for that tag since you last built. It’s a low-risk update, shown as Rebuild in the Endor Labs user interface.
  • Next version: The tag that comes immediately after your current version, in version or timestamp order. This option keeps the upgrade small, so your application sees fewer changes. It’s a medium-risk update.
  • Latest version: The newest tag available for the base image. It typically resolves the most findings of the three, but it makes the largest version change. It’s a high-risk update.
Run the following command to view the update options.
For each update option, the command reports:
  • The finding counts for your current base image and the candidate, and the change between them. A negative change means fewer findings after the update.
  • The findings each update fixes and the findings it introduces. A fixed finding is present now and gone on the candidate. An introduced finding is absent now and present on the candidate.
By default, results group by reachability when the scan collected reachability data. Otherwise, they group by severity. Use --by-severity to group by severity even when reachability data is available.
Reachability analysis for containers targets OS dependencies, not language packages. Most base image findings are OS packages, so reachability data helps you prioritize them. See Container reachability to learn how Endor Labs measures it.
Every update option reports one of the following statuses. Consider an application image built on python:3.11.4. Its update options might look like the following:
  • Refreshed: Rebuild on python:3.11.4 to include its latest patches.
  • Next version: Upgrade to python:3.11.5.
  • Latest version: Upgrade to the newest release, such as python:3.13.1.
The list-base-image-updates command supports additional flags to target the image and narrow or format the results. See Base image update flags.

​
Examples

The following examples show common ways to run the command, from a quick comparison of the update options to a complete review of a single candidate.
Show vulnerability findings only, grouped by severity. The results leave out other finding types and are organized into critical, high, medium, and low buckets, which is useful when you triage CVEs.
Show counts only, without individual findings. This is the fastest way to compare how many findings each update option resolves before you drill into one, because the command skips fetching the finding records.
Show every changed finding for a single update option. Use this to review the complete list of fixed and introduced findings for a candidate before you adopt it. The --list-all flag requires --update-option.
Return the results as JSON for scripting and automation, such as gating a CI job on the number of findings an update resolves.

​
Base image scan flags

Use the following endorctl container scan flags for base image remediation.

​
Base image update flags

Use the following flags with the endorctl container remediation list-base-image-updates command.

​
View remediation results in the Endor Labs user interface

You can view the update options and remediation guidance for a scanned container image in the Endor Labs user interface.
  1. Select Containers from the left sidebar.
  2. Select a container image version to view its remediation summary.
The summary varies based on whether reachability analysis is enabled:
  • If reachability analysis is enabled, the summary reports the number of reachable findings, and each update option shows how many of them remain after the update.
  • If reachability analysis is not enabled, the summary ranks the findings by their total counts.
In Base image versions, you can view your current base image version and the update options identified for the image, each with its change in findings and a risk level:
  • Current: Your existing base image version. It’s the baseline that the update options are compared against.
  • Rebuild: The same base image version, rebuilt to include the latest patches published for it. It’s a low-risk update, shown as the refreshed option in endorctl results.
  • Next: The version immediately after your current one. It introduces the fewest changes and rarely requires configuration updates, so it’s a medium-risk update.
  • Latest: The newest available version. It typically fixes more findings than the other options but involves the largest version change and requires a configuration review, so it’s a high-risk update.
Select any version to review its findings in detail. Findings that the update resolves appear struck through, and findings that the update introduces are marked New. When the image was scanned with reachability analysis, the findings are grouped as Reachable, Potentially reachable, and Non-reachable. Otherwise, they are grouped by severity. AURI is the Endor Labs AI assistant. Ask it about the container image and its findings to get an explanation in plain language, so you can judge an update without reading every finding yourself. Use the suggested prompts, such as Summarize this package version and What stays unfixed?, or ask your own questions. AURI answers only about the container image and its findings. To update the base image to its next or latest version:
  1. Select Next or Latest in Base image versions.
  2. Click Upgrade.
  3. Copy the command that matches your build setup, either a Dockerfile instruction or a Bazel rule for rules_oci or rules_docker.
  4. Update the image tag in the file your project uses to define base images.
  5. Rebuild the image.
  6. Rescan the container image to see the refreshed results.
Base image remediation You can also select Image context in the summary to review how the image is composed:
  • Select Layers to view the number of findings in the base image and the number of findings in the application layer. It also shows the base image name and digest, whether an update is available, and every layer in the order it’s applied with its finding count.
  • Select Metadata to view the project, resolution time, package version UUID, exposed ports, environment variables, and labels of the image.
  • Select Dependencies to view the dependency counts by visibility, scope, and reachability, along with the finding counts by severity.
  • Select Reachability Analysis to view the profiling status, application type, profile type, image classification, duration, and entry point package.