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 Free 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 Free 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 Free and Production Containers in our Containers overview.

Are Chainguard Containers available on Docker Hub?

Yes, Chainguard Free 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. To use Production Containers, pull them from 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.

Can anybody build Chainguard Containers themselves?

Yes. Chainguard builds from open source, and the tools it uses to build packages and containers are freely available in Wolfi. What’s hard to reproduce is the scale.

Before Chainguard adds a container, it reviews the upstream source: whether the project is actively maintained, whether it builds from source, and whether its license permits Chainguard to use and distribute it. Getting a complicated project to build the first time can take days or weeks. Once it builds, the Chainguard Factory rebuilds it automatically every time that project tags a release.

In a do-it-yourself pipeline, the rebuilding falls to a person, usually a project maintainer or a security engineer. Doing it for every image on every upstream release is where most teams run out of hours.

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 replace my current base image with a Chainguard Container and have it 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.

Since March 2024, Chainguard has maintained one version of each Wolfi package at a time. These track the latest version of the upstream software in the package. Chainguard has ended patch support for previous versions of packages in Wolfi. Existing packages remain in Wolfi and you may continue to use them, but be aware that older packages no longer receive updates and 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, 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 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 Free 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 need to ingest Chainguard Containers into an image repository within your FedRAMP boundary. Your repository requires FedRAMP but Chainguard does not since we’re outside the boundary. Reach out if you need more details.

Will Chainguard Containers run alongside eBPF agents or sensors? Will there be any issues?

Chainguard containers are OCI containers. eBPF operates at the kernel-level at runtime. This means an eBPF agent or sensor doesn’t affect Chainguard Containers, and vice versa.