Chainguard Containers FAQs

Learn answers to your questions about Chainguard Containers. Chainguard provides container images designed with security as the primary focus, featuring zero known CVEs, minimal attack surface, and built-in SBOMs for every image.

Which Linux distribution is used as base for Chainguard Containers?

Chainguard Containers are based on Wolfi, a Linux undistro we built specifically to address software supply chain security issues. We call it an undistro because it doesn’t contain certain software you’d normally find in a traditional Linux distribution such as Debian or Alpine. Wolfi is a minimal Linux distribution designed specifically to be used as a base for stripped-down container images.

How do Chainguard Containers relate to the Google Distroless Container Images?

The Google distroless images follow a similar philosophy to many of our images: they are minimal images that don’t include package managers or shells. The main difference is in the implementation. The Google distroless images are built with Bazel and based on the Debian distribution, whereas Chainguard Containers are built with apko and based on Wolfi. We believe our approach is more maintainable and extensible.

Which images are available?

There are currently over a thousand Chainguard Containers available, which are segmented as Starter or Production. You can read more about this in the next question.

Chainguard Containers are primarily available from Chainguard’s registry, but a selection of Starter images is also available on Docker Hub. You can find the complete list of available Chainguard Containers in our public Containers Directory or within the Chainguard Console.

What options do I have to use Chainguard Containers?

You can get free Chainguard Containers for your organization. You can also upgrade for more versions, SLAs, and dedicated support.

You can read more about the differences between Starter and Production Containers in our Containers Overview.

Are Chainguard Containers available on Docker Hub?

Yes, Chainguard Starter Container images are available on Docker Hub. As a Docker Verified Publisher, Chainguard has met Docker’s stringent standards for security, quality, and transparency. This status signifies that our container images are trusted, reliable, and have undergone rigorous verification processes. If you wish to use Production Containers, you will use Chainguard’s registry.

What is an SBOM and why is it important?

An SBOM is a Software Bill of Materials, which is a list containing detailed information about all software that is included within a software artifact, whether it’s an application, a container image, or a physical appliance.

SBOMs provide visibility into the software you depend on. They can allow automated systems to quickly identify issues such as unpatched vulnerabilities, since SBOMs typically include the version of each dependency listed.

Who maintains Chainguard Containers?

Chainguard Containers are officially maintained by Chainguard engineers.

How often are Chainguard Containers updated?

Chainguard Containers are rebuilt every night to ensure that new package versions and security updates in upstream Wolfi are quickly applied.

Can I simply replace my current base image with a Chainguard Container and it will work out of the box?

Chainguard Containers are designed to be minimal, and many of them don’t come with a package manager. Depending on your stack and specific dependencies, you may need to include additional software by combining -dev container images and our distroless images in a multi-stage Docker build.

What packages are available in Chainguard Containers?

Chainguard Containers only contain packages that come from the Wolfi Project or those that are built and maintained internally by Chainguard.

Starting in March of 2024, Chainguard will maintain one version of each Wolfi package at a time. These will track the latest version of the upstream software in the package. Chainguard will end patch support for previous versions of packages in Wolfi. Existing packages will not be removed from Wolfi and you may continue to use them, but be aware that older packages will no longer be updated and will accrue vulnerabilities over time. The tools we use to build packages and images remain freely available and open source in Wolfi.

This change ensures that Chainguard can provide the most up-to-date patches to all packages for our customers. Note that specific package versions can be made available in Production containers. If you have a request for a specific package version, please contact us.

How do I add packages to a Chainguard Container?

Chainguard's Custom Assembly tool is the officially supported approach for extending Chainguard Containers with additional packages. Custom Assembly automatically ensures all packages remain on compatible versions and handles rebuilds when packages are updated, eliminating version conflicts and reducing maintenance overhead.

While using apk add to add packages in a Dockerfile or similar is effective, issues can arise when packages in a base image conflict with new packages that are added. This can be particularly pronounced when core packages are updated — there can be brief windows when the latest version of a base image has a conflict with the latest version of a package.

For example, when the openssl package is updated, there will be a brief window where base images with an old and potentially incompatible version of libcrypto, and attempting to apk add openssl will fail. This conflict will be resolved in a few hours when a new version of the base image is released. The only way around this is to pin to specific versions of packages and images, which adds its own significant maintenance burden.

Refer to our Custom Assembly documentation for more information.

What does Chainguard do when a CVE is published, but a patch is not available from the owner of the OSS code?

Chainguard investigates the CVE and marks relevant images as affected or not. If Chainguard can identify a patch that’s unreleased, Chainguard may apply a patch before it lands upstream. In either case, when the patch lands upstream, Chainguard picks it up and rolls it out.

Why are some CVEs persistent in select Chainguard Containers?

There are several Chainguard Containers container images–such as Druid and Spark–with a notable number of CVEs that are marked pending-upstream-fix. The reasons that these CVEs can’t be remediated by standard engineering procedures include: some vulnerabilities can only be patched through major version upgrades, which often break compatibility through broken builds or tests; many of these CVEs (over fifty percent by one internal Chainguard analysis) stem from “shaded” JARs, JAR files that bundle their dependencies internally; and a small portion of these CVEs simply have no fix available. The Chainguard engineering team continually investigates new approaches to fixing these persistent CVEs.

I added software on top of one of Chainguard’s base container images, why are there CVEs?

Chainguard is not responsible for CVEs in software you add on top of base images.

Do I need to authenticate into Chainguard to use Chainguard Containers?

Logging in is optional if you are only using Starter containers. That being said, there are benefits for all users who authenticate to Chainguard’s registry, as Chainguard provides notifications of version updates, breaking changes, or critical security updates.

To learn how to authenticate into Chainguard’s registry, you can review our authentication documentation . You can read more about the thought process behind authentication in our blog post, Scaling Chainguard Containers with a growing catalog and proactive security updates.

Is Chainguard FedRAMP certified?

You will need to ingest Chainguard Containers into an image repository within your FedRAMP boundary. Your repo requires FedRAMP but Chainguard does not since we’re outside the boundary. Please reach out if you need more details.