Notary v2 — supply chain attestations beyond signatures

Notary v2 (branded as Notation) is a CNCF project for signing OCI artifacts using X.509 certificates. It complements Cosign by providing a standardised mechanism for attaching and verifying signatures to arbitrary OCI artifacts — images, SBOMs, vulnerability reports, SLSA provenance. This lesson covers the Notation workflow, the integration with admission (Ratify), and the production patterns.

Notation vs Cosign

Both Notation and Cosign sign OCI artifacts; the differences are in the cryptographic model and the use case focus:

Cosign is the right primitive for image signatures (integration with Kyverno is straightforward); Notation is the right primitive for multi-artifact attestations (a Sigstore alternative with corporate PKI support).

Signing with Notation

Notation uses a certificate and a private key:

# Generate a self-signed cert (or use a corporate PKI)
notation cert generate-test --default "myapp-signer"

# Sign the image
notation sign --signature-format cose myapp:v1.0

# List signatures
notation list myapp:v1.0
# sha256:abc...  myapp@sha256:def...  application/vnd.cncf.notary.signature.v1

The signature is an OCI artifact tagged with the image’s digest. The application/vnd.cncf.notary.signature.v1 media type identifies it.

sequenceDiagram
    participant CI
    participant Registry
    CI->>CI: notation sign (with cert + key)
    CI->>Registry: Push signature (OCI artifact)
    Registry->>CI: Ack

Signing SBOMs and attestations

Notation can sign any OCI artifact, including SBOMs and SLSA provenance:

# Generate SBOM
syft myapp:v1.0 -o cyclonedx-json > myapp.cdx.json

# Attach SBOM to the registry as an OCI artifact
oras attach --artifact-type application/vnd.cyclonedx+json \
  myapp:v1.0 myapp.cdx.json:application/vnd.cyclonedx+json

# Sign the SBOM
notation sign --artifact-type application/vnd.cyclonedx+json \
  myapp@sha256:sbom-digest

The SBOM is signed and stored in the registry. The image references the SBOM by digest.

Verifying with Ratify

Ratify is the CNCF reference implementation for Notation verification. It runs as a webhook in the cluster:

apiVersion: ratify.notaryproject.io/v1beta1
kind: Verifier
metadata:
  name: notation-verifier
spec:
  artifactTypes: application/vnd.cyclonedx+json,application/vnd.cncf.notary.signature.v1
  trustPolicies:
  - name: myapp-trust
    registryScopes:
    - "registry.example.com/myapp"
    trustStores:
    - certs:
      - |
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
    trustIdentities:
    - cert:
      subject: "CN=myapp-signer,O=myorg"

Ratify verifies that every image, SBOM, or attestation has a valid Notation signature from a trusted signer.

sequenceDiagram
    participant Pod
    participant AS as API server
    participant R as Ratify
    participant Reg as Registry
    Pod->>AS: Pod admission
    AS->>R: Verify image signatures
    R->>Reg: Fetch signatures
    Reg->>R: Signatures
    R->>R: Verify with cert
    R->>AS: Allow or deny

Production patterns

1. Notation for attestations. Use Notation for SBOMs, vulnerability reports, and SLSA provenance.
2. Cosign for image signatures. Use Cosign for the image signature (Kyverno integration is mature).
3. Ratify for verification. Ratify is the reference verifier; it integrates with the API server via a webhook.
4. Corporate PKI for certificates. Use the organisation’s PKI for Notation certs (rather than self-signed).

Production failure modes

1. Certificate expired. The signature is valid; the cert is not. The fix is to rotate the cert.
2. Trusted signer changed. The signer cert is no longer in the trust store. The fix is to update the trust store.
3. Artifact missing. The image has no SBOM or attestation. The fix is to enforce SBOM generation in CI.
4. Verifier is bypassed. Ratify is disabled for debugging. The fix is to enforce the webhook in CI/CD.

Cross-course references

• The Linux course covers X.509 certificates and PKI.
• The Observability course covers the audit log entries for signature verification.

Quiz

Production discipline

Notation is the right primitive for OCI attestations beyond the image itself. A defensible supply chain uses Cosign for image signatures (Kyverno integration) and Notation for SBOMs, vulnerability reports, and SLSA provenance (Ratify integration). The certificate is renewed before expiry; the trust store is updated on rotation. A cluster whose images, SBOMs, and attestations are all signed and verified has a supply chain that is auditable.