Wiki · Concept · Last reviewed June 25, 2026

Notary Project

Notary Project is a CNCF supply-chain project, and Notation is its command-line tooling for signing and verifying OCI artifacts with certificate-backed trust policies.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: Notary Project, Notation, OCI artifacts, trust policy, AI supply chain

Definition

Notary Project is a set of specifications and tools for signing and verifying software artifacts. Its own site describes the project as focused on authentic container images and other OCI artifacts. The CNCF project page says Notary Project was accepted into CNCF on October 24, 2017 at the Incubating maturity level.

Notation is the project's main command-line implementation. The notaryproject/notation repository describes Notation as a CLI for adding signatures as standard items in the OCI registry ecosystem and for signing and verifying those signatures. It implements the Notary Project specifications.

How It Works

The ordinary container flow is digest-centered. The Notary Project quickstart builds and pushes a container image, records its digest, signs it with notation sign, lists the attached signature, creates a trust policy, and verifies the image with notation verify. The quickstart also warns that when a tag is used, Notation resolves the tag to a digest before signing, and recommends using the immutable digest reference.

At the signature layer, the specification supports JWS and COSE envelopes. For OCI artifacts, a Notary Project signature is stored as an OCI image manifest that identifies itself as a signature, names the signed artifact as the subject, points to the signature envelope as a layer, and carries annotations. The signature discovery section says clients should be able to discover signatures for an artifact through the OCI Distribution Referrers API. The same specification also covers detached signatures for arbitrary blobs.

Verification is not only a math check. The trust-store and trust-policy specification says Notary Project currently supports X.509-based PKI and uses a trust store plus a trust policy to decide whether a signed artifact is authentic. The trust store contains trusted roots. The trust policy says which identities are trusted to produce artifacts and which verification level applies.

Agent Context

AI coding agents and deployment agents can create, pull, modify, and run containers at machine speed. That makes artifact identity a practical governance problem. A generated Dockerfile, a tool-server image, a model-serving image, or a batch job image may look ordinary while coming from the wrong builder, the wrong registry, or a mutable tag.

Notation gives the workflow a release gate: verify that the artifact digest has a signature that chains to a configured trust store and matches a configured policy before the artifact is used. This does not prove that the software is safe, unbiased, private, or free of vulnerabilities. It narrows one question: whether this exact artifact was signed by an identity the consumer has chosen to trust.

Governance Use

A governance-grade Notation record should preserve the artifact reference and digest, registry, signature digest, Notation version, signing mechanism, certificate chain or signing authority, trust store, trust policy, verification level, command output, policy exceptions, and reviewer decision. If a plugin or remote key-management service is used, the record should name it and preserve its version or provider evidence.

The trust-policy specification defines validation categories including integrity, authenticity, authentic timestamp, expiry, and revocation. It also defines strict, permissive, audit, and skip levels. In an AI supply chain, those levels should be explicit release policy, not tribal memory. A development cluster may log while teams migrate to signing; a production agent runtime may require strict verification for tool images and model-serving containers.

Notary Project belongs beside SLSA provenance, in-toto, Syft, Grype, Trivy, and AI bills of materials. Signing answers who vouched for this digest. It does not replace build provenance, SBOMs, vulnerability matching, model documentation, or deployment authorization.

Limits

A valid signature can wrap bad software. If a trusted builder signs a vulnerable image, Notation can verify the signature and still leave a vulnerable deployment. If a trust policy accepts too many identities or a root is mishandled, verification can become a ceremony with little control value.

Revocation and timestamp behavior also need operational design. The trust-policy specification treats revocation as a verification category, but external revocation checks can depend on network access and reliable infrastructure. Plugin-based signatures can add useful integrations while reducing portability if verifiers lack the plugin or cannot reproduce the plugin's checks.

Finally, registry behavior matters. OCI referrers make signatures discoverable alongside artifacts, but organizations should test the registries and copy tools they actually use. A migration that copies an image without its attached signatures can break a deployment gate or, worse, teach teams to disable the gate.

Source Discipline

Claims about Notary Project should cite the project site, the Notation repository, the Notary Project specifications, and the current Notary documentation. Audit notes should distinguish a successful cryptographic verification from a broader safety claim. The source trail should include the exact artifact digest and the exact trust policy used at verification time.

Spiralist Reading

Spiralism reads Notary Project as a discipline of names attached to artifacts. The container is not trusted because it appears in the right place or wears the right tag. It is trusted, if at all, because a specific digest is tied to a specific signing identity under a policy that can be inspected.

For agentic systems, that distinction is useful. The agent may move quickly, but the artifact should still leave a named mark before it receives power.

Sources

Return to Wiki