Skip to content

Prevent vulnerable container images

Container images can contain known vulnerabilities in their operating system packages and application dependencies. Welkin's Harbor registry provides vulnerability scanning and a project setting that blocks image pulls based on vulnerability severity. This helps enforce your organization's vulnerability management policy before an image is deployed.

Note

This safeguard supports vulnerability management, including ISO 27001 Annex A 8.8 Management of Technical Vulnerabilities. Combine it with regular vulnerability dashboard review and remediation. Enabling the setting alone does not ensure compliance.

How the safeguard works

Harbor's Prevent vulnerable images from running setting applies to a project. When enabled, Harbor blocks pulls of images with vulnerabilities at or above the selected severity, except for vulnerabilities exempted by the applicable CVE allowlist. For example, selecting High blocks images with High or Critical vulnerabilities that are not exempted. Choose the threshold according to your organization's risk assessment.

The check uses the scanner configured for the project, or Harbor's default scanner if no project scanner is selected.

This check happens when an image is pulled from Harbor. It is separate from trusted registry enforcement, which controls which image sources a workload may reference, and from image signature verification. Check your project's settings to determine whether vulnerability blocking is enabled and which threshold applies.

Configure your Harbor project

You need a Harbor account with at least project administrator privileges and an available vulnerability scanner. See container registry access for login instructions. Contact your administrator if you cannot change the project settings or the scanner is unavailable.

  1. Log in to Harbor, open Projects, and select your project.
  2. Open the Configuration tab.
  3. Enable Prevent vulnerable images from running and select the severity threshold required by your policy.
  4. Enable Automatically scan images on push to scan new images when they are uploaded. This is a separate setting from vulnerability blocking.
  5. Save your settings, then reopen Configuration to confirm they persist.
  6. For images already in the project, open the repository, select the artifact, and run Scan. Wait for a successful scan and review the report for the image you intend to deploy.

See Harbor's project configuration and individual artifact scanning instructions for details.

Verify the policy

Review the completed scan report for the exact image digest, the project's severity threshold, and any applicable CVE exceptions. An incomplete or failed scan is not evidence that an image is safe.

Using an authenticated Docker client, test a pull from the project:

docker pull <harbor-host>/<project>/<repository>@<digest>

Replace the placeholders with your Harbor hostname, project, repository, and image digest, including the sha256: prefix. A scanned image with no non-exempt vulnerabilities at or above the threshold should be allowed. A scanned image with a non-exempt vulnerability at or above the threshold should be denied. Use the current scan results to choose test images; vulnerability results can change over time. You do not need to deploy the blocked image to verify the pull policy.

Resolve a blocked image pull

A Pod whose image pull is blocked may show ErrImagePull or ImagePullBackOff. Inspect its events:

kubectl describe pod <pod-name> -n <namespace>

Look for a Harbor vulnerability-policy denial, such as this illustrative excerpt:

current image with ... vulnerabilities cannot be pulled due to configured policy

ImagePullBackOff can also result from incorrect image names or registry credentials. Check the event message before changing the vulnerability policy.

For a vulnerability-policy denial:

  1. Open the artifact's scan report in Harbor and identify vulnerabilities at or above the project threshold.
  2. Update the affected dependencies or base image, rebuild, and push the corrected image.
  3. Wait for a successful scan and confirm that the corrected image meets the policy.
  4. Update your workload to use the corrected image and redeploy.

If scanning fails or does not complete, inspect the scan status and ask your administrator to help resolve scanner problems.

Handle exceptions

If a fix cannot be applied immediately, assess the risk with your security team before making an exception. Prefer a documented exception for specific CVE IDs with an expiry date to disabling vulnerability blocking or lowering the threshold for the entire project.

Harbor supports system and project CVE allowlists. Projects inherit the system allowlist unless a project allowlist is configured to override it. Review the applicable exceptions when checking why a pull was allowed. See Harbor's project CVE allowlist instructions for configuration and expiry options.

Limitations

  • The policy applies to pulls from the configured Harbor project. Images from other sources require separate controls, such as trusted registry enforcement.
  • Changing the policy does not stop already-running Pods. Continue reviewing the vulnerability dashboard and remediate affected workloads.
  • Kubernetes can reuse a locally cached image without contacting Harbor when imagePullPolicy is IfNotPresent or Never. With Always, the container runtime contacts the registry on each container start. See Kubernetes image pull policies.
  • Scanners detect known vulnerabilities within their coverage. New vulnerabilities can be discovered after a scan, so regularly scan images again and review the results as part of your vulnerability management process.
  • For multi-architecture images, Harbor checks the individual image artifacts being pulled. The image index's aggregate report can include vulnerabilities from other architectures; review the report for the architecture you deploy.

Further Reading