Securing the Container Supply Chain: Building a Private Docker Registry with Harbor and Cosign

Introduction: The Imperative of Container Supply Chain Security

In the modern cloud-native paradigm, containerization has revolutionized how organizations build, ship, and run software. However, this velocity introduces significant security challenges. The software supply chain has emerged as a primary target for malicious actors. If a compromised or untrusted container image infiltrates your production environment, the consequences can be catastrophic—ranging from data breaches to total infrastructure compromise.

To mitigate these risks, modern enterprise architectures must move beyond public repositories and implement a defense-in-depth strategy. This requires a robust infrastructure consisting of two foundational pillars: a secure, private registry to manage container artifacts, and a reliable cryptographic signing mechanism to verify image integrity. This guide provides an end-to-end blueprint for building a secure, private container registry utilizing Harbor and Sigstore Cosign.

Why Harbor and Cosign?

Before diving into the implementation details, it is crucial to understand why the combination of Harbor and Cosign has become the industry standard for securing containerized workflows.

Harbor: Enterprise-Grade Artifact Management

Harbor is an open-source, trusted cloud-native registry project hosted by the Cloud Native Computing Foundation (CNCF). Unlike basic registries, Harbor extends the Docker Distribution open-source project by adding critical enterprise features:

• Role-Based Access Control (RBAC): Granular permissions to ensure only authorized users and systems can push or pull images.
• Vulnerability Scanning: Built-in integration with scanners like Trivy to detect Common Vulnerabilities and Exposures (CVEs) within layers.
• Pluggable Architecture: Native support for OCI (Open Container Initiative) artifacts, image replication, and immutable repositories.

Cosign: Simplified Artifact Signing

Part of the Sigstore project, Cosign makes signing and verifying container images straightforward. Traditionally, signing containers relied on complex systems like Docker Content Trust (Notary v1), which required dedicated database infrastructure and complex key management. Cosign simplifies this by:

• Storing signatures as standard OCI artifacts directly inside the registry, alongside the image.
• Eliminating the need for extra infrastructure components or stateful databases.
• Supporting hardware security modules (HSMs), cloud key management systems (KMS), and passwordless OpenID Connect (OIDC) identities.

Step 1: Setting Up Your Private Harbor Registry

To begin, we must deploy an instance of Harbor. For enterprise environments, deploying Harbor via Helm on a Kubernetes cluster or utilizing an optimized docker-compose setup is recommended. Ensure that you have a fully qualified domain name (FQDN) and valid TLS certificates; Cosign and Docker require secure HTTPS connections to operate correctly.

Prerequisites

• A Linux host with Docker and Docker Compose installed.
• A registered domain name pointing to your host's public IP address.
• TLS certificates (e.g., from Let's Encrypt or your internal corporate Certificate Authority).

Configuration and Installation

1. Download the latest Harbor installer bundle and extract the contents.
2. Copy the harbor.yml.tmpl template to harbor.yml.
3. Edit harbor.yml to configure your hostname, ports, and TLS certificate paths:

Note: Never run an enterprise registry over insecure HTTP. Passwords, auth tokens, and proprietary source code layers can easily be intercepted without transport layer encryption.

Once configured, run the installation script: ./install.sh. After a successful deployment, log in to the Harbor Web UI using your admin credentials, create a new project named production, and set its access level to Private.

Step 2: Installing and Configuring Cosign

With Harbor operational, the next phase is preparing the signing environment. Install the Cosign CLI tool onto your local machine or your CI/CD runner. Cosign is distributed as a single binary, making installation seamless across Linux, macOS, and Windows.

Generating the Cryptographic Key Pair

Cosign uses asymmetric cryptography to sign and verify images. To generate a secure key pair, execute the following command in your terminal:

cosign generate-key-pair

You will be prompted to enter a secure passphrase. This passphrase protects your private key file (cosign.key). The command also generates a public key file (cosign.pub).

Crucial Security Rule: The cosign.key file must be kept strictly confidential. Store it securely within an enterprise vault, a Secret Management service, or encrypted CI/CD variables. The cosign.pub file, however, will be distributed to your Kubernetes clusters and verification systems to validate the signatures.

Step 3: The Secure Build-Sign-Push Workflow

With our registry running and keys generated, we can now execute the secure workflow. This process models how an automated CI/CD pipeline (such as GitHub Actions, GitLab CI, or Jenkins) behaves.

1. Build and Authenticate

First, build your application container image and log in to your private Harbor registry:

docker build -t [harbor.yourdomain.com/production/secure-app:v1.0](https://harbor.yourdomain.com/production/secure-app:v1.0) .
docker login harbor.yourdomain.com

2. Push the Base Image

Push the newly compiled OCI image to your private Harbor repository:

docker push [harbor.yourdomain.com/production/secure-app:v1.0](https://harbor.yourdomain.com/production/secure-app:v1.0)

3. Sign the Container Image

Now, use Cosign to sign the remote image artifact. Cosign targets the image directly inside the registry using its repository path and tag (or best practice, its immutable SHA256 digest):

cosign sign --key cosign.key [harbor.yourdomain.com/production/secure-app:v1.0](https://harbor.yourdomain.com/production/secure-app:v1.0)

Cosign will prompt you for your private key passphrase, compute the cryptographic signature of the image digest, and push that signature to your Harbor project. If you inspect your Harbor project via the web interface, you will see a newly created `.sig` tag object linked directly to your application image. Harbor natively recognizes this Cosign signature format.

Step 4: Verifying Signatures and Enforcing Policy

An image signature is only useful if it is strictly verified before deployment. Verification ensures that the image has not been altered since it was signed and that it originates from an authorized publisher.

Manual Verification via CLI

To manually verify an image before pulling it down to a staging or production server, use the public key:

cosign verify --key cosign.pub [harbor.yourdomain.com/production/secure-app:v1.0](https://harbor.yourdomain.com/production/secure-app:v1.0)

If successful, Cosign will output the verified structured JSON payload detailing the image digest, timestamp, and a success message. If the image layers have been modified or tampered with, the cryptographic verification will fail, and the image should be discarded immediately.

Automated Admission Control in Kubernetes

To eliminate human error, verification should be automated inside your infrastructure. In a production Kubernetes environment, you can deploy admission controllers such as Kyverno or Policy Controller (Sigstore).

These controllers intercept every deployment request sent to the Kubernetes API server. They evaluate the incoming image against a strict policy rule: "Reject any container deployment targeting the production namespace if it does not possess a valid signature matching our corporate cosign.pub key." This ensures that even if an attacker gains unauthorized access to your cluster, they cannot deploy unsigned, rogue containers.

Conclusion and Best Practices

Integrating Harbor with Cosign builds a formidable barrier against supply chain attacks. By establishing a private registry, you gain absolute sovereignty over your container software assets. By layering cryptographic signatures via Cosign, you establish absolute certainty regarding the provenance and integrity of every single line of code running in production.

As you scale this architecture across your enterprise, adhere to these operational best practices:

• Automate in CI/CD: Never allow manual image signing. Embed the cosign sign process directly into isolated, secure phases of your automated deployment pipelines.
• Rotate Keys Regularly: Establish a lifecycle policy for your cryptographic keys and have a revocation plan ready in case a private key is exposed.
• Enable Vulnerability Gates: Configure Harbor to deny content trust permissions or prevent image pulls if a vulnerability scan returns "Critical" severity ratings.

By enforcing a strict policy of "Verify Everything, Trust Nothing," your organization can confidently innovate at cloud-native speeds without sacrificing security compliance.