Supply chain security
Image Signing: Sigstore and Notation
1.What a signature proves
- Binds an identity to one digest, never a tag.
- Both tools resolve a tag and warn : use
@sha256:. - Sigstore : cosign, an OIDC identity, a public log.
- Notary Project : Notation, your own X.509 PKI.
Digest, not tag
- Verifying by tag checks whatever the tag points at now. See the tag-swap advisory in Crossplane.
- How a signature finds its digest (
subject, referrers) : Images, Registries and Pulls.
2.cosign with a key
cosign generate-key-pair: encrypted key file, or a KMS.- Sign and verify
IMAGE@sha256:...with--key. - Key mode still logs to public Rekor by default.
- Private : signing config without
rekorTlogUrls, verify with--insecure-ignore-tlog. - v3.0.6+ :
--keyplus identity flags is an error.
| Key URI | Holds |
|---|---|
cosign.key | file, plus cosign.pub |
awskms:///alias/x | AWS KMS, by alias |
gcpkms:// | Google Cloud KMS |
hashivault://, openbao:// | Vault transit (OpenBao v3.0.6) |
k8s://ns/name | a Secret : key, password, pub |
3.Keyless, step by step
- Fulcio : OIDC token to a 10-minute cert. Identity in the SAN, issuer in OID
1..3. 6. 1. 4. 1. 57264. 1. 8 - Signed : a DSSE in-toto Statement, predicate type
https://.sigstore. dev/ cosign/ sign/ v1
Bundle v0.3 = leaf cert + tlog entry + timestamp + DSSE envelope. The identity stays in public logs for good.
4.Reading the identity
- A reusable workflow puts its own path in the SAN. cosign pins the caller only by deprecated OID
.5(--certificate-github-workflow-repository). - The caller sits in OIDs
.12(source repo) and.18(build config) : that needs a policy engine.
| Signer | --certificate-oidc-issuer | SAN (--certificate-identity) |
|---|---|---|
| GitHub Actions | https:// | https:// |
| GitLab CI | https:// | https:// |
| Google SA | https:// | krel-trust@k8s-releng-prod. |
| Kubernetes SA | your cluster issuer | https:// (RBAC) |
| SPIFFE | your configured issuer | spiffe://... from sub (SPIFFE, SPIRE) |
5.Trust roots, Rekor v1 and v2
- Trust : TUF ships
trusted_root.json. Itstimestamp.jsonlives a week, so air-gapped verifiers pass--trusted-root. - Public default : Rekor v1, for the foreseeable future. v2 is opt-in (
signing-config create --with-default-rekor-v2). - Rekor v2 has no SET, so a TSA is mandatory. Shards rotate : never hardcode
log2025-1. - No revocation : short certs plus log monitoring. Private instance :
cosign trusted-root create.
In short : Sign the digest, not the tag. Keyless signing turns a CI identity into a 10-minute certificate and a public log entry, so the identity you pin when verifying is the whole security story.
1.Where signatures live
- cosign v3 : a bundle as an OCI 1.1 referrer, type
....sigstore. bundle. v0. 3+json - Legacy cosign (v2 default) : tag
sha256-<hex>., nosig subject, so the Referrers API never lists it. .sigtag and fallback indexsha256-<hex>differ. The index is a racy read-modify-write.--registry-referrers-mode=oci-1-1is not the v3 switch : experimental, legacy-format writes only.
| Format | Tag | subject | Listed | Written by |
|---|---|---|---|---|
| Legacy cosign | sha256-<hex>. | no | no | v2 default; v3 with 2 legacy flags |
| cosign v3 bundle | none | yes | yes | v3 default; v2.6 with a flag |
| Notation | none | yes | yes | notation |
| Fallback index | sha256-<hex> | n/a | n/a | both, without the API; notation v1.x always |
2.Verifying with cosign
- Keyless verify requires an identity and an issuer flag (or their
-regexpforms). - The regexps are unanchored : write
^...$. A.*accepted a stranger's bundle in the lab : any Sigstore user passes. - One identity per run. Always verify
IMAGE@sha256:....
Anchored GitHub Actions verify
$ cosign verify ghcr.io/ORG/REPO@sha256:<d> \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
--certificate-identity-regexp '^https://github\.com/ORG/REPO/\.github/workflows/release\.yml@refs/tags/v[0-9.]+$'
3.What "verified" means
- cosign runs eight checks, in the order on the right.
- Key mode swaps cert, SCT and identity for the key, and needs no timestamp.
- The predicate type is not checked. An SBOM attestation from the pinned identity passes
cosign verify(see SBOMs, Provenance and Attestations). --insecure-ignore-tlogstill prints "verified offline". Never scrape stderr.
4.Old and new verifiers
- Old verifiers say
Error: no signatures found(exit 10) on a v3 signature. - If any bundle exists, v3 ignores legacy
.sigsignatures. - Floor : cosign v3.1.3+ or v2.6.5+. GHSA-fx35-mq7g-6g98 has no CVE ID, so CVE scanners miss it.
- CI lags :
cosign-installerv4.1.2 defaults to v3.0.6, Alpine 3.20 ships 2.2.1. Pin it and printcosign version.
| Signed with | < v2.6.0 | v2.6.0 to v2.6.2 | v2.6.3 to v2.6.5 | v3.x |
|---|---|---|---|---|
Legacy .sig | yes | yes | yes | yes, if no bundles |
| v3 bundle referrer | no | only with --new-bundle-format | yes (auto-detect) | yes |
| Both on one image | .sig only | .sig only | bundles only | bundles only |
5.Commands
| Command | What it shows |
|---|---|
cosign sign --yes IMAGE@sha256:<d> | Keyless sign, bundle pushed as a referrer |
cosign sign --key cosign.key IMAGE@sha256:<d>cosign verify --key cosign.pub IMAGE@sha256:<d> | Key mode, sign and verify |
cosign tree IMAGE | .sig and .att tags, plus referrers |
cosign bundle inspect b.sigstore.json | Cert extensions, SCTs, tlog, timestamps (no crypto checks) |
cosign version | Client version : check it in every CI image |
In short : cosign v3 stores a bundle as a referrer of the digest, old verifiers cannot see it, and a verify is only as strong as an anchored identity plus issuer.
1.Notation : your own PKI
- Keys via plugins : azure-kv v1.2.1, AWS Signer.
notation sign: JWS (default) or COSE envelope, optional RFC 3161 countersignature.- v1.3.2 writes a referrer with
config.mediaType...(nonotary. signature artifactType) and thesha256-<hex>index.
2.trustpolicy.json, trust stores
- Stores hold root certs only, in
~/..config/ notation/ truststore/ x509/ - Policy pick : exact repo, then one
"*", else fail. - Identities need C, ST, O. No
serverAuthEKU, unlike cert-manager TLS certs. notation policy import trustpolicy.json, thennotation verify -vby digest.
One strict statement
{"version": "1.0", "trustPolicies": [{
"name": "app",
"registryScopes": ["example.com/app"],
"signatureVerification": {"level": "strict"},
"trustStores": ["ca:acme", "tsa:my-tsa"],
"trustedIdentities": [
"x509.subject: C=US, ST=WA, O=acme.io"]
}]}
3.Verification levels
auditpasses a wrong signer with exit 0.skipwith"*": v1.3.2 accepts it, the spec forbids it.- No TSA : a signature dies with its leaf cert.
- Unknown revocation fails
strict(OCSP 2s, CRL 5s).
E enforce (fails), L log and go on, - skipped.
| Check | strict | permis. | audit | skip |
|---|---|---|---|---|
| Integrity | E | E | E | - |
| Authenticity | E | E | L | - |
| Timestamp | E | L | L | - |
| Expiry | E | L | L | - |
| Revocation | E | L | L | - |
4.cosign or Notation ?
Notation v1.3.2 (2025-04-27) is current (v2 : alpha). Flux checks both on OCI sources. Cluster : Image Policy.
| Aspect | cosign v3.1 | Notation v1.3 |
|---|---|---|
| Root of trust | TUF trusted_root.json or --trusted-root | Root certs in trust stores |
| Identity check | SAN + issuer (OID .8), or a raw key | trustedIdentities x509 subject, or a plugin identity |
| Signing time | Rekor v1 SET, or RFC 3161 (must with Rekor v2) | Optional RFC 3161 countersignature |
| Transparency | Rekor + CT log by default | None built in |
| Revocation | None : short certs, log monitoring | OCSP first, CRL fallback |
5.Copy, then verify again
oras cp -r(preview) misses legacy.sig.cosign copy(deprecated v3.0.5) misses v3 bundles.regctl image copy --referrers --digest-tags SRC DSTcarries both. Keep the digest unchanged.- Re-verify at the destination. Notation also needs the new repository in
registryScopes.
6.Worked example : Kubernetes v1.37.1
- Images :
krel-trust@k8s-releng-prod., issuer Google, legacyiam. gserviceaccount. com .sig. - That
.sigholds krel-staging and krel-trust signatures : either passes. Pin the digest (Deployments). - Binaries : krel-staging, with flags deprecated and due to go in v4. No
.sigstore.jsonyet.
$ cosign verify registry.k8s.io/kubectl@sha256:b7cab618... --certificate-identity krel-trust@... --certificate-oidc-issuer https://accounts.google.com $ for f in kubectl kubectl.sig kubectl.cert; do curl -sSfLO "https://dl.k8s.io/release/v1.37.1/bin/linux/amd64/$f"; done $ cosign verify-blob kubectl --signature kubectl.sig --certificate kubectl.cert --certificate-identity krel-staging@... --certificate-oidc-issuer https://accounts.google.com
In short : Notation trades the public log for your own CA and a trust policy. Either way, copy signatures with the image, verify again, and check Kubernetes against the krel identities by digest.