Registries and Container Supply Chains

Introduction and Context

A container image is not merely a file used to start a process. It is a software product assembled from source code, dependencies, operating-system packages, build tools, configuration, and metadata. The route by which that image is created, stored, transferred, verified, deployed, and eventually retired is its container supply chain.

A registry is the principal distribution service in this chain. It stores and serves container images and related artifacts through a standard protocol, most commonly the OCI Distribution Specification. Docker Hub, GitHub Container Registry, Amazon Elastic Container Registry, Azure Container Registry, Google Artifact Registry, and self-hosted solutions such as Harbor are examples of registries.

Supply-chain engineering is important because an image may be deployed to many systems and may remain in production for months. A compromised build environment, an untrusted base image, an accidentally public repository, or an unpatched dependency can therefore affect a large number of workloads. Professional practice combines naming conventions, immutable references, access control, retention, scanning, software bills of materials (SBOMs), provenance, and cryptographic signatures.

Learning Objectives

By the end of this chapter, you should be able to:

• distinguish public, private, hosted, and proxy registries;
• construct useful image names, tags, and immutable digests;
• authenticate to a registry and push or pull images safely;
• design repository access, retention, and promotion policies;
• explain SBOMs, provenance attestations, signatures, and vulnerability scanning;
• apply a defensible container supply-chain workflow;
• evaluate limitations, governance requirements, and operational trade-offs.

1. Registry Foundations

A registry generally contains repositories. A repository groups related image manifests, indexes, tags, and associated artifacts. An image manifest identifies the configuration object and filesystem layers. Each object is addressed by a cryptographic digest, commonly using SHA-256.

A registry may provide:

• image storage and distribution;
• authentication and authorization;
• vulnerability scanning;
• replication between regions;
• webhooks and event notifications;
• retention and garbage collection;
• artifact storage for Helm charts, SBOMs, signatures, and attestations;
• audit logs and policy enforcement.

Public and private registries

A public registry permits broad discovery or anonymous access to some repositories. It is convenient for open-source images but requires careful selection: popularity is not proof of security, maintenance, or authenticity.

A private registry restricts access to an organization or selected identities. It is normally used for proprietary applications, internal base images, and controlled release artifacts. Private does not automatically mean secure; weak credentials, excessive permissions, and unpatched registry software remain risks.

A hosted registry is operated by a cloud or commercial provider. A self-hosted registry is operated by the organization. Hosted services reduce operational burden but introduce provider, cost, availability, and data-residency considerations. Self-hosting offers control but requires reliable storage, backups, upgrades, TLS, monitoring, and incident response.

A pull-through cache or proxy registry downloads approved public images and serves cached copies internally. It reduces external dependency and improves speed, but administrators must define refresh and trust policies so that a cached artifact is not treated as permanently safe merely because it was previously approved.

OCI concepts

The Open Container Initiative (OCI) defines interoperable image and distribution specifications. Important objects include:

• Manifest: metadata describing an image configuration and its layers.
• Image index: a collection of manifests, often one for each CPU architecture and operating system.
• Layer: an immutable filesystem change set.
• Digest: a content-derived identifier such as sha256:....
• Tag: a human-readable mutable label, such as 1.4.2 or stable.
• Artifact: a registry object that may not be a runnable image, such as an SBOM or signature.

A multi-platform image allows a client to select an appropriate manifest for linux/amd64, linux/arm64, or another supported platform. A tag may point to an image index, while the selected platform manifest has its own digest.

2. Image Naming, Tags, and Digests

A typical fully qualified image reference is:

registry.example.com/team/catalog-api:1.4.2

Its components are:

An image can also be referenced immutably:

registry.example.com/team/catalog-api@sha256:abcdef...

The digest is calculated from content. If content changes, the digest changes. A tag, in contrast, is a pointer that can be moved. Thus :latest, :production, and :stable are convenient deployment labels but are not immutable identities.

Versioning strategies

A professional repository normally combines several forms of identification:

1. Semantic version tags, such as 2.3.1, communicate intended compatibility. Semantic versioning conventionally uses MAJOR.MINOR.PATCH, where major changes may be incompatible, minor changes add backward-compatible functionality, and patch changes correct defects. The project must define what compatibility means; the notation is not a guarantee.
2. Git or build identifiers, such as 2.3.1-git.a1b2c3d, connect an image to source history.
3. Environment tags, such as staging or production, support promotion workflows but should not be the only deployment reference.
4. Platform-specific tags, if used, must be documented. Prefer a multi-platform index when a single logical release supports several architectures.

A robust pattern is to publish a human-readable release tag while recording and deploying the resulting digest. For example, a release process may publish 2.3.1, test it, and then deploy catalog-api@sha256:.... This provides usability and reproducibility simultaneously.

Avoid relying on latest in production. It does not necessarily mean newest, and it gives no clear audit trail. Avoid embedding secrets in tags, labels, Dockerfiles, or image layers. Image layers can persist in registry history even after a later layer appears to remove a secret.

Worked example: tag promotion

Suppose catalog-api:2.3.1 resolves to digest D1 after testing. A release system may assign the production tag to D1 and record:

catalog-api:2.3.1  → D1
catalog-api:production → D1

If a later release resolves to D2, promotion changes only the production pointer:

catalog-api:2.4.0  → D2
catalog-api:production → D2

The deployment record should retain D1 and D2, so rollback can explicitly request D1 rather than relying on a mutable tag.

3. Registry Operations

The Docker CLI illustrates common operations. Exact commands vary with registry and authentication method.

docker login registry.example.com
docker build -t registry.example.com/team/catalog-api:2.3.1 .
docker push registry.example.com/team/catalog-api:2.3.1
docker pull registry.example.com/team/catalog-api:2.3.1
docker image inspect registry.example.com/team/catalog-api:2.3.1

A digest can be obtained after pushing or resolving an image:

docker buildx imagetools inspect registry.example.com/team/catalog-api:2.3.1

For CI/CD, use short-lived tokens, workload identity, or an automatically managed credential rather than a personal password. Store credentials in a secret manager and avoid printing them in logs. Configure TLS and verify certificate handling. Registry access should be auditable, and failed authentication should generate appropriate alerts.

A normal workflow is:

1. Developer commits source code.
2. CI builds an image in a controlled environment.
3. Tests and policy checks run before publication.
4. The image is pushed to a quarantine or development repository.
5. Scanning, SBOM generation, and provenance recording occur.
6. An authorized process promotes the same digest to a release repository.
7. Deployment uses the approved digest.
8. Monitoring, patching, and retention processes continue after release.

Rebuilding an image and pushing it under the same release tag is poor practice because consumers cannot determine which bytes they received. If a release must be corrected, publish a new version or explicitly document a controlled tag movement and its impact.

4. Access Control and Governance

Registry security should follow least privilege. Separate permissions for pushing, pulling, deleting, administering repositories, and managing policies. A deployment identity usually needs pull access only. A build identity may push to a development repository but should not delete production artifacts.

Useful controls include:

• single sign-on and multi-factor authentication for human users;
• short-lived tokens for automation;
• repository-level roles and team ownership;
• protected production repositories;
• approval requirements for promotion;
• immutable or protected release tags;
• audit logs for login, push, pull, delete, and policy actions;
• network restrictions and private endpoints where appropriate;
• encryption in transit and at rest;
• backup and disaster-recovery testing.

A registry namespace should have an owner, data classification, lifecycle policy, and emergency contact. Naming conventions should prevent collisions and make ownership visible, for example platform/payments/api or business-unit/service-name.

Retention and deletion

Retention controls limit storage cost and reduce the number of obsolete artifacts that could be mistakenly deployed. A policy might retain all signed production releases for seven years, development images for 30 days, and unreferenced intermediate images for 14 days. These values are organizational decisions, not universal technical rules.

Deletion must account for manifests, tags, layers, signatures, SBOMs, attestations, and legal or audit requirements. Removing a tag may not remove the underlying manifest or shared layers. Conversely, deleting an unreferenced manifest may affect attached artifacts or rollback capability. Test garbage collection in a non-production registry and preserve release evidence before deletion.

5. The Software Supply Chain

A container supply chain includes more than the final image:

• source repositories and dependencies;
• developer workstations and CI runners;
• base images and package repositories;
• build definitions and build tools;
• registry storage and transport;
• deployment systems and runtime configuration;
• identities, keys, and policy engines.

Threats include dependency confusion, typosquatting, compromised base images, malicious pull requests, poisoned build caches, leaked credentials, registry takeover, vulnerable packages, and unauthorized tag changes. Security therefore requires layered controls rather than a single scanner.

Reproducibility and hermeticity

A reproducible build attempts to produce equivalent outputs from the same declared inputs. Pinning a base image by digest, locking dependency versions, controlling build tools, and recording source revision improve reproducibility. Perfect byte-for-byte reproducibility can be difficult because timestamps, compiler behavior, network access, and generated metadata may vary.

A hermetic build restricts undeclared external inputs. Dependencies are retrieved from approved sources or an internal mirror, and network access during the build is limited where practical. This reduces the chance that a build changes because an external package changed unexpectedly.

6. SBOMs and Provenance

An SBOM is a structured inventory of components in a software artifact. It may identify packages, versions, suppliers, licenses, relationships, and vulnerable component identifiers. Common formats include SPDX and CycloneDX.

An SBOM can answer, “Which deployed images contain package X?” It does not by itself prove that the inventory is complete, that a package is safe, or that the image was built by an authorized process. SBOM quality depends on the tool, package ecosystem, build stage, and accuracy of metadata.

Provenance describes how an artifact was produced. It may record source revision, builder identity, build parameters, timestamps, dependencies, and the resulting artifact digest. Provenance enables a verifier to ask whether an image was produced by an approved workflow from an expected source.

SBOMs and provenance should be attached to the image digest rather than treated as unrelated documents. They must be retained and access-controlled like other release evidence.

Example conceptual metadata:

artifact digest: sha256:D1
source revision: a1b2c3d
builder: ci.example.com/release
build workflow: trusted-build-v4
sbom: cyclonedx document attached to D1
provenance: signed attestation attached to D1

7. Signing and Verification

Image signing provides an authenticity and integrity signal. A signer uses a private key to create a signature over an artifact identity, normally including its digest. A verifier uses the corresponding public key or trusted certificate to check the signature and establish whether the signer is authorized.

Signing does not mean that an image is free of vulnerabilities. It means that the signed content was endorsed by a particular identity under a particular trust system. If a trusted build process produces a vulnerable image, the signature remains valid.

Modern workflows commonly use keyless or managed-key approaches, with identity established through an identity provider and certificates or transparency records. Traditional key pairs remain possible, but private-key protection, rotation, revocation, and recovery must be managed carefully.

A deployment policy might require that:

• the image digest has a valid signature;
• the signer belongs to the production build identity;
• provenance meets the organization’s policy;
• the SBOM is present;
• vulnerability findings are below the defined threshold.

Verification should occur close to deployment, because an image can be replaced or a tag can move after an earlier check.

8. Vulnerability Scanning

A vulnerability scanner compares detected components with vulnerability databases and reports findings, commonly using identifiers such as CVE. Scanners may inspect operating-system packages, language dependencies, binaries, and sometimes configuration. Results can include severity, affected versions, exploitability context, and available fixes.

Scanning has important limitations:

• detection may miss statically compiled or unusual components;
• a vulnerable package may be unreachable or not exploitable in the deployed configuration;
• databases may contain false positives or delayed information;
• severity is not the same as organizational risk;
• a clean scan is not proof of safety;
• newly disclosed vulnerabilities may appear after deployment.

A mature policy distinguishes build-time, registry-time, and deployment-time scanning. It defines exceptions with an owner, reason, compensating control, expiry date, and review process. “Critical” should not be treated as a universal automatic decision without considering exposure, exploitability, network position, privileges, and available mitigation.

Images should also be scanned for poor configuration, such as running as root, unnecessary shells, exposed secrets, excessive capabilities, or writable sensitive paths. These checks complement, but do not replace, dependency scanning.

9. A Practical Secure Promotion Model

Consider four repositories: dev, candidate, release, and archive.

• Developers and CI can push to dev.
• A pipeline copies a digest to candidate after tests.
• Automated checks generate an SBOM, provenance, and vulnerability report.
• An authorized release process signs and promotes the unchanged digest to release.
• Superseded but auditable releases move to archive according to policy.

Promotion should copy or reference the same immutable digest, not rebuild the image for each environment. Rebuilding can introduce different dependency versions or timestamps and therefore changes the artifact being tested.

A deployment manifest should use a digest:

image: registry.example.com/team/catalog-api@sha256:abcdef...

Configuration such as database URLs, credentials, and environment-specific settings should be supplied separately through deployment configuration or a secret manager. It should not be baked into the image.

10. Illustrative Case: Northstar Payments

Background

Northstar Payments operates a web API deployed to Kubernetes in two regions. Engineers previously pulled public base images directly, used latest in a deployment manifest, and stored images in one large shared repository.

Problem

A production rollback failed because latest had moved. An audit also found that CI credentials could delete images, vulnerability reports were not retained, and no evidence connected a deployed image to its source commit.

Analysis

The organization had three related weaknesses: mutable deployment references, excessive registry permissions, and insufficient supply-chain evidence. Scanning alone would not solve these governance problems.

Approach

Northstar implemented the following design:

1. An internal pull-through cache supplied approved base images.
2. Repositories were separated into dev, candidate, and release namespaces.
3. CI used workload identity and could push only to dev.
4. Releases used semantic version tags plus immutable digests.
5. Each release generated an SPDX SBOM and signed provenance.
6. A policy gate required an approved signer, an SBOM, and no unaccepted high-risk finding.
7. Kubernetes manifests used digests rather than latest.
8. Production images and their evidence were retained for the audit period.
9. Exceptions required security-owner approval and an expiry date.

Outcome

Rollback became deterministic because the earlier digest remained identifiable. The organization could query which releases contained a vulnerable package and could demonstrate the source revision and builder for a deployed image. Storage costs increased initially because evidence and release artifacts were retained, but lifecycle rules removed unreferenced development images.

Learning points

The case demonstrates that supply-chain security is a coordinated operating model. Naming, access, build controls, metadata, signing, scanning, deployment, and retention must support one another. No individual control establishes complete trust.

11. Professional, Ethical, and Regulatory Considerations

Organizations are responsible for protecting customer data, credentials, intellectual property, and service availability. Publishing an image publicly may disclose proprietary code, internal hostnames, package metadata, or embedded secrets. License information in an SBOM can reveal obligations such as attribution or source-distribution requirements.

Regulated environments may require evidence of access control, change management, vulnerability remediation, retention, and incident response. Requirements differ by jurisdiction and sector; teams should consult applicable laws, contractual obligations, and standards rather than assuming that a particular registry feature satisfies compliance.

Ethically, vulnerability exceptions should be transparent and time-limited. Teams should not suppress findings merely to improve dashboard metrics. Security researchers and upstream maintainers should receive responsible disclosure, and compromised artifacts should be quarantined with clear communication to affected users.

12. Contemporary Developments and Best Practices

Current practice is moving toward policy-driven artifact platforms, signed attestations, standardized SBOM exchange, automated provenance verification, and software supply-chain frameworks such as SLSA. These developments improve evidence and automation but do not eliminate the need for skilled review.

Recommended practices are:

• use fully qualified image references;
• deploy by digest and treat tags as human-facing pointers;
• pin important base images and dependencies;
• prefer minimal, maintained base images;
• separate development and production permissions;
• use short-lived automation credentials;
• generate SBOMs and provenance during trusted builds;
• sign artifacts and verify signatures at deployment;
• scan continuously and triage according to actual risk;
• protect release tags and audit all administrative actions;
• define retention, backup, and disaster-recovery policies;
• test rollback using known digests;
• document exceptions and expire them;
• rehearse response to a compromised image, key, registry, or dependency.

Chapter Summary

Registries are central control points in the container supply chain, but they are only one part of a broader system. Public and private registries differ in exposure, governance, and operational responsibility. Image tags improve human usability but are mutable; digests provide immutable content identity and should be used for production deployment. Effective registry governance combines least-privilege access, protected repositories, audit logging, retention, backup, and tested recovery.

SBOMs describe component contents, provenance records how an image was built, signatures provide an authenticity and integrity signal, and vulnerability scanners identify known weaknesses. Each control has limitations, so secure delivery requires their combination in a controlled promotion workflow. The professional goal is not to claim that an image is absolutely safe, but to make its origin, contents, approval, risks, and deployment history visible and governable.

Key Terms

Registry: A service that stores and distributes container images and artifacts.

Repository: A named collection of related manifests, tags, and artifacts.

OCI: The Open Container Initiative specifications for container images and distribution.

Manifest: Metadata describing an image configuration and its layers.

Image index: A collection of platform-specific image manifests.

Layer: An immutable filesystem change set in an image.

Tag: A human-readable, mutable reference to an image or index.

Digest: A content-derived identifier used to address an exact artifact.

Semantic versioning: A versioning convention using major, minor, and patch components.

Private registry: A registry whose repositories require controlled authorization.

Pull-through cache: A registry that retrieves and caches artifacts from an upstream source.

SBOM: A structured software bill of materials listing components and relationships.

Provenance: Evidence describing an artifact’s source, builder, inputs, and build process.

Signature: Cryptographic evidence linking an artifact to a signing identity.

Attestation: Structured evidence associated with an artifact, such as provenance or test results.

Vulnerability scan: An analysis comparing detected components or configurations with known risks.

Promotion: Moving or authorizing an unchanged artifact for a later environment.

Least privilege: Granting only the permissions necessary for a task.

Retention policy: Rules defining how long artifacts and related evidence are kept.

Hermetic build: A build designed to use controlled, declared inputs rather than undeclared external state.

Review Questions

Short Answer Questions

1. What is the difference between an image tag and an image digest?
2. State two differences between a public registry and a private registry.
3. What information does an SBOM provide?
4. Why should CI and deployment credentials be separated?
5. Name two limitations of vulnerability scanning.

Long Answer Questions

1. Explain how a registry supports the complete container supply chain from build to deployment.
2. Describe a versioning and naming strategy suitable for a multi-team organization.
3. Explain how access control, retention, audit logging, and backup contribute to registry governance.
4. Compare SBOMs, provenance, signatures, and vulnerability reports. What question does each answer?
5. Design a secure promotion workflow for development, staging, and production images.

Analytical / Application Questions

1. A production manifest uses service:latest, and the tag has moved since the previous deployment. Analyze the operational risks and propose a migration plan.
2. A scanner reports a critical vulnerability in a package that is present but unreachable in the deployed application. Explain how the team should assess and document the finding rather than automatically ignoring or accepting it.
3. An organization wants to rebuild an image separately for each environment while retaining the same version tag. Evaluate this design and recommend a more reproducible alternative.

Multiple Choice Questions with Answers

Question 1

Which reference identifies the exact content of a container image?

A. A mutable tag such as latest

B. A repository namespace

C. A content digest

D. A registry display name

Correct Answer: C. A content digest

Question 2

What is the principal purpose of an SBOM?

A. To encrypt image layers

B. To list software components and their relationships

C. To replace registry authentication

D. To assign a network address to a container

Correct Answer: B. To list software components and their relationships

Question 3

Which identity should normally have pull-only access to a production registry?

A. A deployment identity

B. A registry administrator

C. A release manager with delete rights

D. A build identity that publishes images

Correct Answer: A. A deployment identity

Question 4

What does provenance primarily describe?

A. The runtime CPU utilization of a container

B. The visual appearance of an image

C. The process, source, and builder used to create an artifact

D. The number of registry users

Correct Answer: C. The process, source, and builder used to create an artifact

Question 5

Why is deploying by digest preferable to deploying by latest?

A. A digest automatically patches vulnerabilities

B. A digest identifies immutable content

C. A digest removes the need for testing

D. A digest makes an image public

Correct Answer: B. A digest identifies immutable content

Question 6

What is a pull-through cache designed to do?

A. Sign every source commit

B. Cache artifacts from an upstream registry

C. Delete all old production images

D. Convert containers into virtual machines

Correct Answer: B. Cache artifacts from an upstream registry

Question 7

Which statement about image signing is correct?

A. A valid signature proves the image has no vulnerabilities

B. Signing links an artifact to an identity and its exact content

C. Signing makes tags immutable automatically in every registry

D. Signing replaces the need for access control

Correct Answer: B. Signing links an artifact to an identity and its exact content

Question 8

Which practice best supports reproducible builds?

A. Using unpinned floating dependencies

B. Rebuilding separately for every environment

C. Pinning important inputs and recording the source revision

D. Deleting all build metadata

Correct Answer: C. Pinning important inputs and recording the source revision

Question 9

What should a vulnerability exception normally include?

A. No documentation, because exceptions are permanent

B. An owner, justification, compensating control, and expiry

C. A new mutable latest tag

D. A request to disable all scanning

Correct Answer: B. An owner, justification, compensating control, and expiry

Question 10

Why should production release repositories be protected from ordinary CI deletion rights?

A. To prevent unauthorized loss of released artifacts

B. To make images execute faster

C. To eliminate the need for image tags

D. To ensure every image is publicly searchable

Correct Answer: A. To prevent unauthorized loss of released artifacts