> For the complete documentation index, see [llms.txt](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/findings/containers/base-image-upgrades.md). # Base Image Upgrades Newer tags of the base image an image was built on, what each one removes, and the pull request that makes the change. An image inherits vulnerabilities from the base it was built on. Where an image declares a base, Heeler looks for newer tags of that base, scans a few of them, and reports what each one would remove. ## Where it appears On the [Images listing](/mrecEO40m5D6bt7Pq5pE/findings/containers/images.md), the **Base Upgrade** column reads **removes N** or **up to date**. On the [image detail page](/mrecEO40m5D6bt7Pq5pE/findings/containers/image-detail.md), the **Base Upgrade** term under **Build** carries the state. Select it to open the **Base Image Upgrade** drawer. ## The Base Upgrade states | State | Meaning | | -------------------------- | ------------------------------------------------------------------------------------------------------- | | **Not declared** | Neither the build's provenance, the image's OCI base annotations nor its labels named a base image. | | **Evaluation pending** | The base is queued for evaluation. | | **Evaluating candidates…** | Candidate tags are being scanned. | | **Up to date** | No newer compatible tag was found. | | **Unsupported base** | The base reference cannot be evaluated. | | **No layers to attribute** | The image has no per-layer attribution, so base findings cannot be separated from application findings. | | **Evaluation failed** | The evaluation did not complete. | ## Candidate selection Heeler reads the tags of the base image's repository and keeps only those that are a safe move from the tag your image names. The rules are deliberately narrow: * A candidate never crosses a major version. * A candidate never trades a precise tag for a vaguer one. * Pre-release tags are skipped. * A tag variant moves only when it carries its own version. Up to three candidates are kept per base. Each one is pulled and scanned, so the comparison is between two sets of scan results. Each candidate is labelled with the kind of move it is: | Kind | Meaning | | ----------- | --------------------------------------------------- | | **Patch** | A newer patch on the same release line. | | **Minor** | The next release line under the same major version. | | **Pin** | A more precise tag on the same version. | | **Refresh** | A newer date-stamped build of the same release. | | **Rebuild** | The same tag, rebuilt since this image was built. | One candidate is marked **Recommended**. ## Reading a candidate The drawer header shows the **Current base** and its digest, the count of **Base CVEs in this image** with its severity split, and when the base was last **Evaluated**. Where Heeler identified the Dockerfile that declares the base, its path is shown too. Each candidate carries its tag, its digest, its operating system, when it was scanned, and three counts: | Bucket | What it counts | | -------------- | ------------------------------------------------------------------------------------------------ | | **Removes** | Base vulnerabilities in your image that this candidate does not have, with their severity split. | | **Remains** | Base vulnerabilities that this candidate still has. | | **Introduces** | Vulnerabilities this candidate has that your image does not. | Expand a candidate for the per-vulnerability detail, including the version each is fixed in. A candidate still being scanned shows **Queued** or **Scanning** instead of the counts. ## Opening a pull request Where your role allows you to trigger remediation, each scanned candidate carries an **Open Dockerfile PR** button. Confirming in the **Open Dockerfile PR** dialog starts an agent execution that edits the Dockerfile's base reference and opens a pull request. The button is disabled when the candidate has not been scanned, or when the image is not eligible for an automated change. Hover it for the reason. Follow the run from [Agent Executions](/mrecEO40m5D6bt7Pq5pE/fix/agent-executions.md). ## Re-evaluation Each distinct base is re-listed and rescanned every **seven days**, so a base that publishes a new patch tag produces a candidate without waiting for your image to be rebuilt. ## Related * [Container Image Detail](/mrecEO40m5D6bt7Pq5pE/findings/containers/image-detail.md) — where the Base Upgrade term lives. * [Scanning and Retention](/mrecEO40m5D6bt7Pq5pE/findings/containers/scanning-and-retention.md) — the rest of the scan cadence. * [Agent Executions](/mrecEO40m5D6bt7Pq5pE/fix/agent-executions.md) — following the pull request the upgrade opens. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/findings/containers/base-image-upgrades.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.