Implementing Sigstore for Software Signing
When to Use
- Signing container images and software artifacts without managing long-lived cryptographic keys
- Establishing verifiable provenance for build outputs in CI/CD pipelines using OIDC identity binding
- Querying the Rekor transparency log to audit when and by whom an artifact was signed
- Verifying that container images pulled from registries were signed by authorized identities and issuers
- Integrating Sigstore verification into Kubernetes admission controllers to enforce signed-image policies
Do not use for signing artifacts that require air-gapped or offline signing workflows where OIDC authentication is unavailable, for environments that cannot reach the public Sigstore infrastructure (Fulcio, Rekor) and have no private instance deployed, or as a replacement for traditional PGP/GPG signing where regulatory compliance mandates specific key management procedures.
Prerequisites
- Cosign CLI v2.4+ installed (
go install github.com/sigstore/cosign/v2/cmd/cosign@latest or binary release)
- Access to an OIDC identity provider supported by Fulcio (Google, GitHub, Microsoft, or a custom OIDC issuer)
- Container registry credentials (for signing container images) with push access to store signature objects
- Python 3.9+ with
sigstore, requests, and cryptography packages for the automation agent
- Network access to
fulcio.sigstore.dev, rekor.sigstore.dev, and tuf-repo-cdn.sigstore.dev (or private Sigstore instance URLs)
Workflow
Step 1: Install and Configure Cosign
Install Cosign and verify it can reach the Sigstore infrastructure:
- Install from binary release: Download the appropriate binary from the Cosign GitHub releases page and verify its checksum. On Linux:
curl -LO https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64 && chmod +x cosign-linux-amd64 && sudo mv cosign-linux-amd64 /usr/local/bin/cosign
- Verify installation: Run
cosign version to confirm the version and check connectivity to Sigstore services with cosign initialize which fetches the TUF root of trust
- Configure custom infrastructure (optional): If running a private Sigstore stack, set
--fulcio-url, --rekor-url, and --oidc-issuer flags or use environment variables COSIGN_REKOR_URL and COSIGN_FULCIO_URL
Step 2: Keyless Signing with Cosign and Fulcio
Perform identity-based signing where Fulcio issues a short-lived certificate bound to your OIDC identity:
Step 3: Verify Signed Artifacts
Verify that artifacts were signed by expected identities from expected OIDC issuers:
Step 4: Query the Rekor Transparency Log
Search and verify entries in the Rekor transparency log to audit signing events:
- Search by email identity: Use
rekor-cli search --email user@example.com to find all signing events for an identity
- Search by artifact hash: Use
rekor-cli search --sha sha256:<hash> to find signing events for a specific artifact
- Retrieve and verify an entry: Use
rekor-cli get --uuid <entry_uuid> to retrieve full entry details including the certificate, signature, and artifact hash
- Verify log inclusion: Use
rekor-cli verify --entry-uuid <uuid> to verify the entry's inclusion proof against the signed tree head, confirming the entry exists in the append-only log and has not been tampered with
- REST API queries: Query
https://rekor.sigstore.dev/api/v1/index/retrieve with POST body {"hash": "sha256:<hash>"} to retrieve entry UUIDs, then fetch full entries from /api/v1/log/entries/<uuid>
- Monitor for consistency: Use the rekor-monitor tool or Omniwitness to continuously verify the log remains append-only and entries are never mutated or removed
Step 5: Integrate into CI/CD Pipelines
Embed signing and verification into build and deployment pipelines:
- GitHub Actions: Use
sigstore/cosign-installer action to install Cosign, then sign images using the GitHub OIDC token as the identity. The signing identity will be the workflow URL (e.g., https://github.com/org/repo/.github/workflows/build.yml@refs/heads/main).
- Kubernetes admission enforcement: Deploy Sigstore Policy Controller or Kyverno with Cosign verification policies to reject unsigned or incorrectly signed images at admission time
- Supply chain metadata: Use
cosign attest to attach in-toto attestations (SLSA provenance, SBOM, vulnerability scan results) to images, signed with the same keyless flow, enabling consumers to verify both the artifact and its build metadata
Key Concepts
| Term |
Definition |
| Keyless Signing |
Identity-based signing that uses short-lived certificates from Fulcio bound to OIDC identities instead of long-lived cryptographic keys, eliminating key management overhead |
| Fulcio |
Sigstore's certificate authority that issues short-lived X.509 certificates after verifying OIDC tokens, binding an ephemeral public key to a verified identity |
| Rekor |
Sigstore's immutable, append-only transparency log that records signing events with timestamps, enabling auditors to verify when and by whom an artifact was signed |
| Cosign |
The primary CLI tool for signing and verifying container images and blobs using the Sigstore infrastructure (Fulcio + Rekor) |
| TUF Root of Trust |
The Update Framework distribution mechanism for Sigstore's root CA certificate and Rekor public key, ensuring clients trust the correct Sigstore infrastructure |
| OIDC Identity Binding |
The process where Fulcio verifies a user's identity through an OpenID Connect token and binds it to a short-lived signing certificate |
| Inclusion Proof |
A cryptographic proof from Rekor demonstrating that a signing event entry exists within the transparency log's Merkle tree |
Tools & Systems
- Cosign: CLI tool for signing containers and blobs, verifying signatures, and attaching attestations using Sigstore keyless signing or traditional key-based signing
- Fulcio: Free root certificate authority for code signing certificates issued based on OIDC identity verification with a validity period of approximately 10 minutes
- Rekor: Transparency log server providing tamper-evident storage of signing metadata, searchable by identity, artifact hash, or public key
- Sigstore Policy Controller: Kubernetes admission webhook that enforces image signing policies by verifying Cosign signatures and attestations before allowing pod creation
- rekor-cli: Command-line client for querying, uploading, and verifying entries in the Rekor transparency log
Common Scenarios
Scenario: Securing a Container Image Build Pipeline with Keyless Signing
Context: A DevOps team builds container images in GitHub Actions and deploys to a Kubernetes cluster. They need to ensure only images built by their CI pipeline can be deployed, preventing supply chain attacks from compromised registries or unauthorized pushes.
Approach:
- Add
sigstore/cosign-installer@v3 to the GitHub Actions workflow and enable OIDC token permissions with id-token: write
- After building and pushing the image, sign it with
cosign sign $IMAGE_DIGEST using the GitHub Actions OIDC identity automatically
- Deploy Sigstore Policy Controller to the Kubernetes cluster with a ClusterImagePolicy requiring signatures from
--certificate-identity-regexp=https://github.com/myorg/myrepo/.* and --certificate-oidc-issuer=https://token.actions.githubusercontent.com
- Verify the signing entry appears in Rekor by querying with the image digest hash to confirm the transparency log recorded the event
- Test the admission controller by attempting to deploy an unsigned image and confirming it is rejected with a policy violation error
Pitfalls:
- Signing the image tag instead of the digest (
cosign sign myimage:latest vs cosign sign myimage@sha256:abc...) means verification breaks when the tag is updated to point to a different digest
- Not pinning the
--certificate-oidc-issuer during verification allows signatures from any OIDC provider to pass, defeating the purpose of identity binding
- Forgetting to set
id-token: write permission in GitHub Actions results in OIDC token retrieval failure and signing errors
- Using
--certificate-identity-regexp=.* in production verification policies effectively disables identity verification
Output Format
## Sigstore Signing Verification Report
**Artifact**: ghcr.io/myorg/myapp@sha256:a1b2c3d4...
**Verification Status**: PASSED
**Certificate Details**:
Subject: https://github.com/myorg/myapp/.github/workflows/build.yml@refs/heads/main
Issuer: https://token.actions.githubusercontent.com
Valid From: 2026-03-19T10:00:00Z
Valid To: 2026-03-19T10:10:00Z
**Rekor Entry**:
UUID: 24296fb24b8ad77a8d52...
Log Index: 89234567
Integrated Time: 2026-03-19T10:00:05Z
Inclusion Proof: VERIFIED (tree size: 92000000, root hash: e4f5a6...)
**Policy Check**: Image signed by authorized CI workflow identity
1---2name: implementing-sigstore-for-software-signing3description: 'Implements Sigstore-based software signing and verification using Cosign4 keyless signing, Rekor transparency log verification, and Fulcio certificate authority5 integration to establish cryptographic provenance for container images, binaries,6 and software artifacts, including OIDC-based identity binding and CI/CD pipeline7 integration. Use when setting up keyless container/artifact signing, verifying8 signatures against the Rekor transparency log, or deploying Sigstore in a supply-chain9 security workflow.1011 '12domain: cybersecurity13subdomain: supply-chain-security14tags:15- sigstore16- cosign17- rekor18- fulcio19- software-signing20- supply-chain21- keyless-signing22- OIDC23- transparency-log24version: 1.0.025author: mukul97526license: Apache-2.027nist_csf:28- GV.SC-0129- GV.SC-0330- GV.SC-0631- GV.SC-0732mitre_attack:33- T107834- T119035- T105936- T161037- T161138mitre_f3:39 version: '1.1'40 tactics:41 - resource-development42 - initial-access43 - stealth44 techniques:45 - id: T119546 name: Supply Chain Compromise47 tactic: initial-access48 source: attack49 - id: T160850 name: Stage Capabilities51 tactic: resource-development52 source: attack53 - id: T1608.00654 name: 'Stage Capabilities: SEO Poisoning'55 tactic: resource-development56 source: attack57 - id: T158658 name: Compromise Accounts59 tactic: resource-development60 source: attack61 - id: T107062 name: Indicator Removal63 tactic: stealth64 source: attack65metadata:66 source: https://skillmd.com/skills/26zl/implementing-sigstore-for-software-signing67---6869# Implementing Sigstore for Software Signing7071## When to Use7273- Signing container images and software artifacts without managing long-lived cryptographic keys74- Establishing verifiable provenance for build outputs in CI/CD pipelines using OIDC identity binding75- Querying the Rekor transparency log to audit when and by whom an artifact was signed76- Verifying that container images pulled from registries were signed by authorized identities and issuers77- Integrating Sigstore verification into Kubernetes admission controllers to enforce signed-image policies7879**Do not use** for signing artifacts that require air-gapped or offline signing workflows where OIDC authentication is unavailable, for environments that cannot reach the public Sigstore infrastructure (Fulcio, Rekor) and have no private instance deployed, or as a replacement for traditional PGP/GPG signing where regulatory compliance mandates specific key management procedures.8081## Prerequisites8283- Cosign CLI v2.4+ installed (`go install github.com/sigstore/cosign/v2/cmd/cosign@latest` or binary release)84- Access to an OIDC identity provider supported by Fulcio (Google, GitHub, Microsoft, or a custom OIDC issuer)85- Container registry credentials (for signing container images) with push access to store signature objects86- Python 3.9+ with `sigstore`, `requests`, and `cryptography` packages for the automation agent87- Network access to `fulcio.sigstore.dev`, `rekor.sigstore.dev`, and `tuf-repo-cdn.sigstore.dev` (or private Sigstore instance URLs)8889## Workflow9091### Step 1: Install and Configure Cosign9293Install Cosign and verify it can reach the Sigstore infrastructure:9495- **Install from binary release**: Download the appropriate binary from the Cosign GitHub releases page and verify its checksum. On Linux: `curl -LO https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64 && chmod +x cosign-linux-amd64 && sudo mv cosign-linux-amd64 /usr/local/bin/cosign`96- **Verify installation**: Run `cosign version` to confirm the version and check connectivity to Sigstore services with `cosign initialize` which fetches the TUF root of trust97- **Configure custom infrastructure** (optional): If running a private Sigstore stack, set `--fulcio-url`, `--rekor-url`, and `--oidc-issuer` flags or use environment variables `COSIGN_REKOR_URL` and `COSIGN_FULCIO_URL`9899### Step 2: Keyless Signing with Cosign and Fulcio100101Perform identity-based signing where Fulcio issues a short-lived certificate bound to your OIDC identity:102103- **Sign a container image**: Run `cosign sign <IMAGE_DIGEST>` which triggers an OIDC authentication flow. Cosign generates an ephemeral key pair, obtains a short-lived certificate from Fulcio binding the public key to the OIDC identity, signs the image digest, and records the signing event in Rekor. The private key is destroyed immediately after signing.104- **Sign a blob (file)**: Run `cosign sign-blob <file> --bundle artifact.sigstore.json` to sign arbitrary files. The bundle contains the signature, certificate, timestamp, and Rekor inclusion proof.105- **Non-interactive signing in CI**: Set `SIGSTORE_ID_TOKEN` environment variable with a valid OIDC token (e.g., from GitHub Actions OIDC or GCP workload identity) to skip the browser-based authentication flow:106 ```bash107 export SIGSTORE_ID_TOKEN=$(curl -sH "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \108 "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=sigstore" | jq -r '.value')109 cosign sign $IMAGE_DIGEST110 ```111- **Supported OIDC providers**: Google (`https://accounts.google.com`), GitHub (`https://github.com/login/oauth`), Microsoft (`https://login.microsoftonline.com`), GitLab (`https://gitlab.com`), and custom providers registered with a private Fulcio instance112113### Step 3: Verify Signed Artifacts114115Verify that artifacts were signed by expected identities from expected OIDC issuers:116117- **Verify a container image**: Run `cosign verify <IMAGE_URI> --certificate-identity=name@example.com --certificate-oidc-issuer=https://accounts.google.com` to confirm the image was signed by the specified identity. Cosign validates the certificate chain, checks the Rekor inclusion proof, and verifies the signature matches the current image digest.118- **Verify a signed blob**: Run `cosign verify-blob <file> --bundle artifact.sigstore.json --certificate-identity=name@example.com --certificate-oidc-issuer=https://accounts.google.com`119- **Regex matching for CI identities**: Use `--certificate-identity-regexp` to match CI workflow identities:120 ```bash121 cosign verify $IMAGE --certificate-identity-regexp="https://github.com/myorg/myrepo/.*" \122 --certificate-oidc-issuer=https://token.actions.githubusercontent.com123 ```124- **Verification failure modes**: Cosign returns a non-zero exit code on failure. Common failures include certificate identity mismatch, expired certificates without a valid Rekor timestamp, missing Rekor entry, and image digest mismatch (image was modified after signing).125126### Step 4: Query the Rekor Transparency Log127128Search and verify entries in the Rekor transparency log to audit signing events:129130- **Search by email identity**: Use `rekor-cli search --email user@example.com` to find all signing events for an identity131- **Search by artifact hash**: Use `rekor-cli search --sha sha256:<hash>` to find signing events for a specific artifact132- **Retrieve and verify an entry**: Use `rekor-cli get --uuid <entry_uuid>` to retrieve full entry details including the certificate, signature, and artifact hash133- **Verify log inclusion**: Use `rekor-cli verify --entry-uuid <uuid>` to verify the entry's inclusion proof against the signed tree head, confirming the entry exists in the append-only log and has not been tampered with134- **REST API queries**: Query `https://rekor.sigstore.dev/api/v1/index/retrieve` with POST body `{"hash": "sha256:<hash>"}` to retrieve entry UUIDs, then fetch full entries from `/api/v1/log/entries/<uuid>`135- **Monitor for consistency**: Use the rekor-monitor tool or Omniwitness to continuously verify the log remains append-only and entries are never mutated or removed136137### Step 5: Integrate into CI/CD Pipelines138139Embed signing and verification into build and deployment pipelines:140141- **GitHub Actions**: Use `sigstore/cosign-installer` action to install Cosign, then sign images using the GitHub OIDC token as the identity. The signing identity will be the workflow URL (e.g., `https://github.com/org/repo/.github/workflows/build.yml@refs/heads/main`).142- **Kubernetes admission enforcement**: Deploy Sigstore Policy Controller or Kyverno with Cosign verification policies to reject unsigned or incorrectly signed images at admission time143- **Supply chain metadata**: Use `cosign attest` to attach in-toto attestations (SLSA provenance, SBOM, vulnerability scan results) to images, signed with the same keyless flow, enabling consumers to verify both the artifact and its build metadata144145## Key Concepts146147| Term | Definition |148|------|------------|149| **Keyless Signing** | Identity-based signing that uses short-lived certificates from Fulcio bound to OIDC identities instead of long-lived cryptographic keys, eliminating key management overhead |150| **Fulcio** | Sigstore's certificate authority that issues short-lived X.509 certificates after verifying OIDC tokens, binding an ephemeral public key to a verified identity |151| **Rekor** | Sigstore's immutable, append-only transparency log that records signing events with timestamps, enabling auditors to verify when and by whom an artifact was signed |152| **Cosign** | The primary CLI tool for signing and verifying container images and blobs using the Sigstore infrastructure (Fulcio + Rekor) |153| **TUF Root of Trust** | The Update Framework distribution mechanism for Sigstore's root CA certificate and Rekor public key, ensuring clients trust the correct Sigstore infrastructure |154| **OIDC Identity Binding** | The process where Fulcio verifies a user's identity through an OpenID Connect token and binds it to a short-lived signing certificate |155| **Inclusion Proof** | A cryptographic proof from Rekor demonstrating that a signing event entry exists within the transparency log's Merkle tree |156157## Tools & Systems158159- **Cosign**: CLI tool for signing containers and blobs, verifying signatures, and attaching attestations using Sigstore keyless signing or traditional key-based signing160- **Fulcio**: Free root certificate authority for code signing certificates issued based on OIDC identity verification with a validity period of approximately 10 minutes161- **Rekor**: Transparency log server providing tamper-evident storage of signing metadata, searchable by identity, artifact hash, or public key162- **Sigstore Policy Controller**: Kubernetes admission webhook that enforces image signing policies by verifying Cosign signatures and attestations before allowing pod creation163- **rekor-cli**: Command-line client for querying, uploading, and verifying entries in the Rekor transparency log164165## Common Scenarios166167### Scenario: Securing a Container Image Build Pipeline with Keyless Signing168169**Context**: A DevOps team builds container images in GitHub Actions and deploys to a Kubernetes cluster. They need to ensure only images built by their CI pipeline can be deployed, preventing supply chain attacks from compromised registries or unauthorized pushes.170171**Approach**:1721. Add `sigstore/cosign-installer@v3` to the GitHub Actions workflow and enable OIDC token permissions with `id-token: write`1732. After building and pushing the image, sign it with `cosign sign $IMAGE_DIGEST` using the GitHub Actions OIDC identity automatically1743. Deploy Sigstore Policy Controller to the Kubernetes cluster with a ClusterImagePolicy requiring signatures from `--certificate-identity-regexp=https://github.com/myorg/myrepo/.*` and `--certificate-oidc-issuer=https://token.actions.githubusercontent.com`1754. Verify the signing entry appears in Rekor by querying with the image digest hash to confirm the transparency log recorded the event1765. Test the admission controller by attempting to deploy an unsigned image and confirming it is rejected with a policy violation error177178**Pitfalls**:179- Signing the image tag instead of the digest (`cosign sign myimage:latest` vs `cosign sign myimage@sha256:abc...`) means verification breaks when the tag is updated to point to a different digest180- Not pinning the `--certificate-oidc-issuer` during verification allows signatures from any OIDC provider to pass, defeating the purpose of identity binding181- Forgetting to set `id-token: write` permission in GitHub Actions results in OIDC token retrieval failure and signing errors182- Using `--certificate-identity-regexp=.*` in production verification policies effectively disables identity verification183184## Output Format185186```187## Sigstore Signing Verification Report188189**Artifact**: ghcr.io/myorg/myapp@sha256:a1b2c3d4...190**Verification Status**: PASSED191192**Certificate Details**:193 Subject: https://github.com/myorg/myapp/.github/workflows/build.yml@refs/heads/main194 Issuer: https://token.actions.githubusercontent.com195 Valid From: 2026-03-19T10:00:00Z196 Valid To: 2026-03-19T10:10:00Z197198**Rekor Entry**:199 UUID: 24296fb24b8ad77a8d52...200 Log Index: 89234567201 Integrated Time: 2026-03-19T10:00:05Z202 Inclusion Proof: VERIFIED (tree size: 92000000, root hash: e4f5a6...)203204**Policy Check**: Image signed by authorized CI workflow identity205```