We are excited to announce the release of Ratify v1.3.0!

Ratify is now a CNCF sandbox project! We sincerely thank the exceptional community for invaluable contributions and unwavering support in reaching this significant milestone. Ratify is a verification framework that ensures container images and supply chain artifacts stored in a registry are thoroughly vetted and trustworthy. By integrating Ratify into your Kubernetes workflow, you can safeguard your application deployment against potential threats and vulnerabilities, thereby greatly enhancing the security of your applications.

Read further to learn about the exciting new features and how they can be beneficial to you!

Features and deprecations​

Key features in this release include:

• Support of validating Notary Project signatures with timestamping
• Support of periodic retrieval of keys and certificates stored in a KMS (Key Management System)
• Introducing new configuration for Cosign keyless verification

Support of validating Notary Project signatures with timestamping​

Ratify now supports verifying Notary Project signatures with timestamping. Since Notation v1.2.0 release, Notary Project supports RFC 3161-compliant timestamping. This enhancement extends the trust of signatures created within the certificate's validity period by trusting on a Timestamping Authority (TSA), enabling successful signature verification even after the certificates have expired. Timestamping reduces costs by eliminating the need to periodically re-sign images due to certificate expiry, which is critical when using short-lived certificates. To validate Notary Project signatures that include timestamps from a TSA, it's essential for a verifier to determine trusted entities both as the image signer and as the TSA. In Ratify, trust stores and trust policies can be configured in the Notation verifier to establish this trust. For more information, see the configuration of Notation verifier.

Support of periodic retrieval of keys and certificates stored in a KMS​

Users configure keys and certificates through Key Management Providers (KMP) resources for signature verification. Without specifying versions in KMP resources, Ratify fetches the latest versions. Keys or certificates may rotate for security reasons, and automatic rotation is a common practice. When rotated, new versions are created, making the current versions outdated. Before Ratify v1.3.0, users had to manually update KMP resources when versions were rotated or disabled. This could result in verification failures for new versions if updates were not performed promptly. From v1.3.0 onwards, the refreshInterval parameter is introduced for KMP resources allowing periodic checks for the latest versions and status validation. Future updates will also support keeping a specified number of previous versions to validate older signatures that may still be in use.

Please note that currently, only the KMP of Azure Key Vault has this support. Let us know if you need support for other KMPs. For more information, see the Azure Key Vault KMP configuration.

Introducing new configuration for Cosign keyless verification​

Starting with version 1.2.0, trust policies have been introduced for Cosign signature verification, allowing users to fine tune verification policies. This release enhances the feature by adding support for Cosign keyless verification. For more information, see the Cosign verifier keyless configuration.

Other enhancements​

Improving error messages for artifact verification​

Clear and concise error messages help users understand what went wrong and how to fix it, reducing support requests and downtime. For developers, well-written error messages provide specific details that can assist in diagnosing and resolving bugs or system issues. Improving error messages is an ongoing initiative at Ratify project. In this release, we've refined the error messages related to artifact verification as per the proposal.

Enhancing security​

Since this release, we have strengthened the security posture of the Ratify project through several key implementations:

Docker Build Attestations: We now generate attestations, including provenance and a Software Bill of Materials (SBOM), for Ratify dev images. This improves transparency in the build process, ensuring better traceability and accountability of image contents. For more information, see the Build attestations document.

Image Signing: Ratify dev images are now signed to ensure their integrity and authenticity. This helps defend against supply chain attacks by preventing tampered or untrusted images from being deployed in production environments. For more information, see the Signature Validation document.

Vulnerability Scanning Workflow: We've implemented an automated workflow to scan Go projects, their dependencies, and Ratify images for known vulnerabilities. This proactive measure ensures that any potential security issues are identified and addressed early.

OpenSSF Best Practices Badge: By adopting the Open Source Security Foundation (OpenSSF) best practices, we've earned the best practices badge. This reflects our commitment to industry-standard security practices, enhancing the project's trustworthiness and overall security posture.

Acknowledgements​

The Ratify release team wants to thank the entire Ratify community for all the activities and engagements that has been vital for helping the project grow and reach this milestone.

Try it now​

Follow this quick start guide to try out Ratify v1.3.0.

We are thrilled to announce the release of Ratify v1.2.0!

Ratify is a verification framework that ensures all supply chain artifacts stored in a registry are thoroughly vetted and trustworthy. By integrating Ratify into your Kubernetes workflow, you can protect your deployment pipeline from potential threats and vulnerabilities, significantly enhancing the overall security of your applications.

Read on to discover the exciting new features and how they can benefit you!

Key Features and Decprecations​

Key features in this release include:

• Cosign Verifier Enhancements
• Kubernetes Multi-Tenancy Support
• Key Management Provider
• OCI 1.1 support

Deprecations:

• CertificateStore is deprecated in favor of KeyManagementProvider (KMP). Please migrate to KeyManagementProvider by following guide here. Support will be removed in Ratify v2.0.0

A brand new Cosign experience!​

Starting in v1.2.0, Ratify now has more comprehensive Cosign verification capabilities.

Verification of Cosign signatures is a critical validation. As such, the Cosign verifier is now a built-in verifier along with the Notation verifier. Beyond first class support, the Cosign verifier introduces a Trust Policy which binds a particular set of verification settings to a certain registry scope. Now, it's possible to specify multiple trust policies based on your registry, namespace, and/or image.

Cosign verification also includes a robust key experience that integrates directly with KMP resources. Expanded capabilities include: multiple key support from KMP or filesystem and RSA + elliptical keys across multiple sizes.

Watch this short demo to see the Cosign Verifier in action. Or check out the documentation for more information.

Support for Multi-Tenancy in Kubernetes​

Ratify now supports multi-tenancy, enabling organizations to share a single cluster among multiple teams by allowing users to define resources within a namespace scope.

This enhancement is seamlessly integrated, as users implicitly opt into multi-tenancy by applying namespace-specific resources such as NamespacedPolicy and NamespacedVerifier, without the need for an explicit feature flag.

Currenlty multi-tenancy supports the following resources: Referrer Store, Verifier, Policy and Key Management Provider, allowing these to be defined and managed within specific namespaces.

Additionally, cluster-wide resources can be set as defaults for namespaces that do not have specific resources defined, ensuring flexibility and efficient resource management across the organization.

Watch this step-by-step tutorial to see multi-tenancy in action. Or check out the documentation for more information.

Introduction of the Key Management Provider​

In this release, we are introducing the KeyManagementProvider (KMP), a new resource designed to replace the existing CertificateStore.

A KMP represents keys and/or certificate that are consumed by a verifier. KMP contains various providers for different use cases, such as inline or cloud hosted key management solutions. Each provider is responsible for defining custom configuration and providing a set of public keys and/or x.509 certificates. Notation and Cosign verifiers can consume KMP resources to use during signature verification. Please refer to respective Notation and Cosign verifier documentation on how to consume KMP.

This new feature aims to streamline key and certificate management, enhancing the efficiency and security of your operations.

An invitation to contribute!​

We are thrilled to share that Ratify is currently under review to be adopted by the Cloud Native Computing Foundation (CNCF).

This marks an exciting opportunity for Ratify to become an open and inclusive project, welcoming contributions from the entire community. We encourage you to get involved, whether you're a developer, tester, or user. Your input and contributions are invaluable to us.

Join us in shaping the future of Ratify by contributing to the project!

The Ratify maintainers are proud to announce the first major release v1.0.0 for production use!

Ratify is an extensible verification framework for container images and other artifacts that can examine and author policies to audit existing resources in Kubernetes. Ratify can use and manage any number of custom verifiers for image metadata like signatures, SBOMs, vulnerability scan reports, and so on.

It helps users to validate the image integrity and authenticity in containers secure supply chain, ensuring your deployments are built from a trusted entity and that images haven't been tampered with since their creation.

Ratify was created and open-sourced on December 9, 2021. After quickly iterating with 18 releases over the past two years, the Ratify framework has became more mature and extensible, and has now reached enterprise-grade quality. Users can easily run Ratify as an External Data Provider for Gatekeeper admission controller on Kubernetes with Helm.

Notable capabilities in this Release​

• Ratify as a CLI binary for verifying artifacts stored in a registry
• Support multiple verifiers including Notation, Cosign, and SBOM
• Support dynamic configuration through CRD
• TLS certificate management and rotation for mTLS service-to-service communication
• Out-of-the-box observability: logging and prometheus metrics support
• Extensible plugin design to support new verifier and referrer store plugins
• High availability support (Experimental)

Extensible plugin design​

Ratify framework was designed from the beginning on an extensible plugin model without any affinity towards a particular verifier or storage model. Ratify uses an extensible plugin architecture to enable extensibility and interoperability to support both the existing and new emerging needs of the artifact verification. Developers can easily create a new plugin and integrate into Ratify ecosystem. See Framework overview for details.

Support dynamic configuration through CRDs​

Ratify supports updating its common configuration through Kubernetes CRDs using kubectl commands, delivering a Kubernetes-native experience for users. The configuration takes effect dynamically so that users have no need to restart the running Ratify Pod. There are four CRDs including Certificate Store, Policy, Store, and Verifier. You can see CRD reference docs for details.

Observability​

Observability is the process of gaining insight into the behavior and performance of applications running on Kubernetes, in order to monitor, troubleshoot, and identify issues more effectively. Ratify introduces standardized logging component and metrics exporter for Prometheus in this release so that users can gather and visualize the metrics via a popular monitoring and logging stack with Prometheus, Grafana, and EFK.

With the rich metrics and verbose logs, it can help ensure the stability and performance of Kubernetes deployments and Ratify system, reduce verification request latency, system downtime and improve security posture. All available metrics are listed in this doc. Refer to this guide to build your own visualized dashboard for Ratify with Prometheus and Grafana.

Ready for large-scale scenarios​

In order to provide security and reliability guarantees for production users in a large-scale deployment scenario, Ratify maintainers finished the load performance testing and published a performance report with detailed performance metrics. It demonstrates Ratify is ready for large-scale deployment scenario. See performance at scale for details.

High Availability (Experimental)​

For higher performance and availability requirements, Ratify can be set to run with multiple replicas and a shared state store. Ratify supports High Availability (HA) using a distributed cache with Dapr and Redis under the hood. HA is an experimental feature in Ratify v1.0.0. Experimental features are intended for testing and evaluation purposes only and should not be used in production environments. See Install Ratify for High Availability to set up an HA cluster.

Brand-new website​

With the contribution from the community, the new Ratify website (ratify.dev) is launched along with the major release. All Ratify documentation has also been migrated from the code repository to the website repository. It provides friendly user experience for readers.

Adopted and trusted by industry leaders​

Ratify has been adopted in AKS Image Integrity and AWS Signer as the verification solution. As a vendor-neutral project, the early adoption status demonstrates the Ratify project's maturity and trustworthiness in the industry.

See it in action​

When deploy a signed image and another unsigned image to Kubernetes, Ratify will allow the signed image to be deployed only and deny the unsigned image deployment.

Learn signing and verification end-to-end tutorial with Notation and Ratify:

What's next​

The Ratify maintainers are considering the following major features for the next milestone.

• Support verifying SBOM of a container image
• Support verifying vulnerability reports of a container image
• Multi-tenancy support

The detailed issues for the next release are tracked in the v1.1.0 milestone. We appreciate all kinds of input from the community. Feel free to reach out us on the Slack channel or GitHub issues to ask questions, provide feedback, or share ideas.

Acknowledgements​

The Ratify team wants to thank the entire Ratify community for all the activity and engagement that has been vital for helping the project grow and reach this major milestone.

Try it now​

You can follow this quick start to try Ratify v1.0.0 and signature verification demo within minutes.

The signed container images enable users to assure deployments are built from a trusted entity and verify images haven't been tampered with since their creation. The signed image ensures integrity and authenticity before the user pulls an image into any environment and avoid attacks.

Notation is a standards-based tool and library for signing and verifying OCI artifacts. It generates signatures and associates them with OCI artifacts to ensure integrity for the supply chain.

Ratify is a verification engine as a binary executable and on Kubernetes which enables verification of artifact security metadata and admits for deployment only those that comply with policies you create. It works with OPA Gatekeeper to provide fine-grained admission policy control capabilities for application deployment on Kubernetes.

This article walks you through the following end-to-end workflow:

• Build and sign an image in GHCR as a software publisher
• Verify the signed image as a software consumer
• Validating and enforcing only signed images are allowed to be deployed on Kubernetes

The typical scenario is when you want to secure your containerized package for a GitHub repository, you can apply this workflow to your project to ensure image integrity between software publisher and consumer.

Prerequisites​

• Kubernetes v1.20 or higher (You can use minikube if you are new to Kubernetes)
• Helm v3

Create an OCI-compatible registry​

Create and run an OCI-compatible registry on your development computer using the distribution/distribution with the image deletion enabled. The following command creates a registry that is accessible at localhost:5001.

docker run -d -p 5001:5000 -e REGISTRY_STORAGE_DELETE_ENABLED=true --name registry registry

Add an image to the registry​

The following commands build and push the wabbit-networks/net-monitor container image to your container registry. Notation supports OCI v1.1 and v1.0 compliant registries. In this article, we use ghcr.io as a sample registry.

docker build -t localhost:5001/net-monitor:v1 https://github.com/wabbit-networks/net-monitor.git#main

Log in to ghcr.io with Docker. You can follow this guide to get the your personal GitHub Token.

echo $CR_PAT | docker login ghcr.io -u $YOUR_USER_NAME --password-stdin

Push the image to ghcr.io. You can record the image digest from the output.

docker push ghcr.io/$namespace/net-monitor:v1

You can record the image digest from the output. For example, the image digest is ghcr.io/feynmanzhou/net-monitor@sha256:27c0290c485140c3c998e92c6ef23fba2bd9f09c8a1c7adb24a1d2d274ce3e8e. Set the environment variable for this image digest.

IMAGE=ghcr.io/$namespace/net-monitor@sha256:27c0290c485140c3c998e92c6ef23fba2bd9f09c8a1c7adb24a1d2d274ce3e8e

Change the package visibility from private to public on GitHub Package settings. It will allow Notation and Ratify to pull the images from the GHCR registry without authentication configuration. See Configuring a package's access control and visibility for details.

Install Notation CLI​

Install the latest version on Linux. Follow the installation guide for other platforms.

curl -LO https://github.com/notaryproject/notation/releases/download/v$NOTATION_VERSION/notation_$NOTATION_VERSION\_linux_amd64.tar.gz

tar xvzf  -C /usr/bin/ notation

Generate a test key and self-signed certificate​

Use notation cert generate-test to generate a test RSA key for signing artifacts, and a self-signed X.509 test certificate for verifying artifacts. Please note the self-signed certificate should be used for testing or development purposes only.

The following command generates a test key and a self-signed X.509 certificate. With the --default flag, the test key is set as a default signing key.

notation cert generate-test --default "ratify-sample.io"

Use notation cert ls to confirm the certificate is stored in the trust store.

notation cert ls

Sign the image​

Sign the sample image with the flag --signature-format to use COSE signature format. in ghcr.io.

notation sign --signature-format cose $IMAGE

The generated signature is pushed to the registry and the digest of the container image returned.

Use notation ls to show the signature associated with the container image.

$ notation ls $IMAGE
ghcr.io/feynmanzhou/net-monitor@sha256:27c0290c485140c3c998e92c6ef23fba2bd9f09c8a1c7adb24a1d2d274ce3e8e
└── application/vnd.cncf.notary.signature
    └── sha256:f4c1e923d1f2a7b76513c889a0db548a093f422d06ac6b83ce7243e0c8fa7805

You can find the signature has also been pushed to the GHCR registry associated with the signed image.

Create a trust policy​

To verify the container image, configure the trust policy to specify trusted identities that sign the artifacts, and level of signature verification to use. For more details, see trust policy spec.

Create a JSON file with the following trust policy, for example:

cat <<EOF > ./trustpolicy.json
{
    "version": "1.0",
    "trustPolicies": [
        {
            "name": "ratify-sample-images",
            "registryScopes": [ "*" ],
            "signatureVerification": {
                "level" : "strict"
            },
            "trustStores": [ "ca:ratify-sample.io" ],
            "trustedIdentities": [
                "*"
            ]
        }
    ]
}
EOF

Import the trust policy configuration from a JSON file.

notation policy import ./trustpolicy.json

Verify the image signature as a software consumer​

As a consumer, verify the signed image before using it.

notation verify $IMAGE

You can also check the signature digest and inspect the signature and its certificate information to make sure the image is produced from a trusted identity.

notation inspect $IMAGE

Verify the containe image before deploying to Kubernetes​

Try out Ratify in Kubernetes through OPA Gatekeeper as the admission controller. It will enforce only signed images can be deployed to Kubernetes.

Set up Gatekeeper with external data.

helm repo add gatekeeper https://open-policy-agent.github.io/gatekeeper/charts

helm install gatekeeper/gatekeeper  \
    --name-template=gatekeeper \
    --namespace gatekeeper-system --create-namespace \
    --set enableExternalData=true \
    --set validatingWebhookTimeoutSeconds=5 \
    --set mutatingWebhookTimeoutSeconds=2

Install the lastest version of Ratify. Specify the certificate generated by Notation for verification purposes.

helm repo add ratify https://ratify-project.github.io/ratify

helm install ratify \
    ratify/ratify --atomic \
    --namespace gatekeeper-system \
    --set-file notaryCert=ghcr-networks.io.crt

Apply the constrait to enforce Gatekeeper policy to allow only signed images can be deployed on Kubernetes:

kubectl apply -f https://ratify-project.github.io/ratify/library/default/template.yaml
kubectl apply -f https://ratify-project.github.io/ratify/library/default/samples/constraint.yaml

Deploy the sample image signed by Notation. Ratify will verify if this image has a valid signature.

$ kubectl run ratify-signed --image=$IMAGE
/net-monitor@sha256:27c0290c485140c3c998e92c6ef23fba2bd9f09c8a1c7adb24a1d2d274ce3e8e
pod/demo created

Check the signature associated with the image.

notation ls $IMAGE

Deploy an unsigned image to Kubernetes cluster. The deployment has been denied since the image has not been signed and doesn't meet the deployment criteria.

$ kubectl run demo --image=ghcr.io/feynmanzhou/notation/alpine@sha256:1304f174557314a7ed9eddb4eab12fed12cb0cd9809e4c28f29af86979a3c870
Error from server (Forbidden): admission webhook "validation.gatekeeper.sh" denied the request: [ratify-constraint] Subject failed verification: ghcr.io/feynmanzhou/notation/alpine@sha256:1304f174557314a7ed9eddb4eab12fed12cb0cd9809e4c28f29af86979a3c870

Inspect the logs to get the detailed error message from the Ratify Pod.

$ kubectl logs ratify-xxxx -n gatekeeper-system
 {
      "subject": "ghcr.io/feynmanzhou/notation/alpine@sha256:1304f174557314a7ed9eddb4eab12fed12cb0cd9809e4c28f29af86979a3c870",
      "isSuccess": false,
      "message": "verification failed: no referrers found for this artifact"
    }
···

Deploy a signed image with an expired certificate.

kubectl run sample --image=ghcr.io/feynmanzhou/alpine:latest@sha256:1304f174557314a7ed9eddb4eab12fed12cb0cd9809e4c28f29af86979a3c870
Error from server (Forbidden): admission webhook "validation.gatekeeper.sh" denied the request: [ratify-constraint] Subject failed verification: ghcr.io/feynmanzhou/alpine:latest@sha256:1304f174557314a7ed9eddb4eab12fed12cb0cd9809e4c28f29af86979a3c870

Inspect the logs to get the detailed error message from the Ratify Pod. You can find that verification failed caused by an invalid signature.

{
  "isSuccess": false,
  "verifierReports": [
    {
      "isSuccess": false,
      "name": "notaryv2",
      "message": "an error thrown by the verifier: failed to verify signature, err: signature is not produced by a trusted signer",
···