docs consolidation
This commit is contained in:
StellaOps Bot
374
docs/modules/attestor/cosign-verification-examples.md
Normal file
374
docs/modules/attestor/cosign-verification-examples.md
Normal file
@@ -0,0 +1,374 @@
|
||||
# Cosign Verification Examples
|
||||
|
||||
This document provides examples for verifying StellaOps DSSE attestations using Sigstore cosign.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Install Cosign
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install cosign
|
||||
|
||||
# Linux (download latest release)
|
||||
curl -sSfL https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64 -o cosign
|
||||
chmod +x cosign
|
||||
sudo mv cosign /usr/local/bin/
|
||||
|
||||
# Windows (download from releases page)
|
||||
# https://github.com/sigstore/cosign/releases
|
||||
|
||||
# Verify installation
|
||||
cosign version
|
||||
```
|
||||
|
||||
### Required Files
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `attestation.json` | DSSE envelope exported from StellaOps |
|
||||
| `public.key` | Public key for keyful verification |
|
||||
| `trusted_root.json` | Sigstore TUF root for keyless verification |
|
||||
|
||||
## Export Attestation from StellaOps
|
||||
|
||||
```bash
|
||||
# Export attestation for a specific artifact
|
||||
stellaops attestation export \
|
||||
--artifact sha256:abc123... \
|
||||
--output attestation.json
|
||||
|
||||
# Export with certificate chain
|
||||
stellaops attestation export \
|
||||
--artifact sha256:abc123... \
|
||||
--include-certificate-chain \
|
||||
--output attestation-bundle.json
|
||||
|
||||
# Export as Sigstore bundle
|
||||
stellaops attestation export \
|
||||
--artifact sha256:abc123... \
|
||||
--format sigstore-bundle \
|
||||
--output attestation.sigstore.json
|
||||
```
|
||||
|
||||
## Keyful Verification (KMS/HSM Keys)
|
||||
|
||||
### Verify with Public Key
|
||||
|
||||
```bash
|
||||
# Basic verification
|
||||
cosign verify-attestation \
|
||||
--key public.key \
|
||||
--type custom \
|
||||
sha256:abc123...
|
||||
|
||||
# Verify from exported attestation file
|
||||
cosign verify-attestation \
|
||||
--key public.key \
|
||||
--type custom \
|
||||
--attestation attestation.json \
|
||||
sha256:abc123...
|
||||
```
|
||||
|
||||
### Verify with KMS Key
|
||||
|
||||
```bash
|
||||
# AWS KMS
|
||||
cosign verify-attestation \
|
||||
--key awskms:///arn:aws:kms:us-east-1:123456789:key/abc-123 \
|
||||
--type custom \
|
||||
sha256:abc123...
|
||||
|
||||
# GCP KMS
|
||||
cosign verify-attestation \
|
||||
--key gcpkms://projects/my-project/locations/global/keyRings/my-ring/cryptoKeys/my-key \
|
||||
--type custom \
|
||||
sha256:abc123...
|
||||
|
||||
# Azure Key Vault
|
||||
cosign verify-attestation \
|
||||
--key azurekms://mykeyvault.vault.azure.net/keys/mykey \
|
||||
--type custom \
|
||||
sha256:abc123...
|
||||
|
||||
# HashiCorp Vault
|
||||
cosign verify-attestation \
|
||||
--key hashivault://transit/keys/my-key \
|
||||
--type custom \
|
||||
sha256:abc123...
|
||||
```
|
||||
|
||||
## Keyless Verification (Fulcio/OIDC)
|
||||
|
||||
### Verify with Certificate Identity
|
||||
|
||||
```bash
|
||||
# Verify with issuer and subject
|
||||
cosign verify-attestation \
|
||||
--certificate-identity "signer@example.com" \
|
||||
--certificate-oidc-issuer "https://accounts.google.com" \
|
||||
--type custom \
|
||||
sha256:abc123...
|
||||
|
||||
# Verify with identity regex
|
||||
cosign verify-attestation \
|
||||
--certificate-identity-regexp ".*@stellaops\.io" \
|
||||
--certificate-oidc-issuer "https://github.com/login/oauth" \
|
||||
--type custom \
|
||||
sha256:abc123...
|
||||
```
|
||||
|
||||
### Verify GitHub Actions Workload Identity
|
||||
|
||||
```bash
|
||||
cosign verify-attestation \
|
||||
--certificate-identity "https://github.com/org/repo/.github/workflows/build.yml@refs/heads/main" \
|
||||
--certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
|
||||
--type custom \
|
||||
sha256:abc123...
|
||||
```
|
||||
|
||||
## Verify Specific Predicate Types
|
||||
|
||||
### StellaOps Attestation Types
|
||||
|
||||
```bash
|
||||
# Verify SBOM attestation
|
||||
cosign verify-attestation \
|
||||
--key public.key \
|
||||
--type "https://spdx.dev/Document" \
|
||||
sha256:abc123...
|
||||
|
||||
# Verify SLSA Provenance
|
||||
cosign verify-attestation \
|
||||
--key public.key \
|
||||
--type "https://slsa.dev/provenance/v1" \
|
||||
sha256:abc123...
|
||||
|
||||
# Verify StellaOps scan results
|
||||
cosign verify-attestation \
|
||||
--key public.key \
|
||||
--type "https://stella-ops.org/attestation/scan-results/v1" \
|
||||
sha256:abc123...
|
||||
|
||||
# Verify StellaOps policy evaluation
|
||||
cosign verify-attestation \
|
||||
--key public.key \
|
||||
--type "https://stella-ops.org/attestation/policy-evaluation/v1" \
|
||||
sha256:abc123...
|
||||
|
||||
# Verify graph root attestation
|
||||
cosign verify-attestation \
|
||||
--key public.key \
|
||||
--type "https://stella-ops.org/attestation/graph-root/v1" \
|
||||
sha256:abc123...
|
||||
```
|
||||
|
||||
## Offline Verification
|
||||
|
||||
### Verify with Cached Bundle
|
||||
|
||||
```bash
|
||||
# Verify using a Sigstore bundle (includes certificate and Rekor entry)
|
||||
cosign verify-attestation \
|
||||
--bundle attestation.sigstore.json \
|
||||
--certificate-identity "signer@example.com" \
|
||||
--certificate-oidc-issuer "https://accounts.google.com" \
|
||||
sha256:abc123...
|
||||
```
|
||||
|
||||
### Verify with Local TUF Root
|
||||
|
||||
```bash
|
||||
# Initialize TUF root (run once)
|
||||
cosign initialize --mirror https://tuf-repo.sigstore.dev --root root.json
|
||||
|
||||
# Verify using local TUF data
|
||||
SIGSTORE_ROOT_FILE=trusted_root.json \
|
||||
cosign verify-attestation \
|
||||
--certificate-identity "signer@example.com" \
|
||||
--certificate-oidc-issuer "https://accounts.google.com" \
|
||||
sha256:abc123...
|
||||
```
|
||||
|
||||
### Air-Gapped Verification
|
||||
|
||||
```bash
|
||||
# 1. On connected machine: download required artifacts
|
||||
cosign download attestation sha256:abc123... > attestation.json
|
||||
cosign download signature sha256:abc123... > signature.sig
|
||||
|
||||
# 2. Transfer files to air-gapped environment
|
||||
|
||||
# 3. On air-gapped machine: verify with public key
|
||||
cosign verify-attestation \
|
||||
--key public.key \
|
||||
--offline \
|
||||
--type custom \
|
||||
--attestation attestation.json \
|
||||
sha256:abc123...
|
||||
```
|
||||
|
||||
## Verify with Policy
|
||||
|
||||
### CUE Policy
|
||||
|
||||
```cue
|
||||
// policy.cue
|
||||
package attestation
|
||||
|
||||
predicateType: "https://stella-ops.org/attestation/scan-results/v1"
|
||||
predicate: {
|
||||
severity: *"low" | "medium" | "high" | "critical"
|
||||
vulnerabilities: [...{
|
||||
id: =~"^CVE-"
|
||||
severity: !="critical"
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
cosign verify-attestation \
|
||||
--key public.key \
|
||||
--type custom \
|
||||
--policy policy.cue \
|
||||
sha256:abc123...
|
||||
```
|
||||
|
||||
### Rego Policy
|
||||
|
||||
```rego
|
||||
# policy.rego
|
||||
package attestation
|
||||
|
||||
default allow = false
|
||||
|
||||
allow {
|
||||
input.predicateType == "https://stella-ops.org/attestation/policy-evaluation/v1"
|
||||
input.predicate.verdict == "PASS"
|
||||
input.predicate.score >= 7.0
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
cosign verify-attestation \
|
||||
--key public.key \
|
||||
--type custom \
|
||||
--policy policy.rego \
|
||||
sha256:abc123...
|
||||
```
|
||||
|
||||
## Multi-Signature Verification
|
||||
|
||||
```bash
|
||||
# Verify that multiple signatures are present
|
||||
cosign verify-attestation \
|
||||
--key builder.pub \
|
||||
--type custom \
|
||||
sha256:abc123... && \
|
||||
cosign verify-attestation \
|
||||
--key witness.pub \
|
||||
--type custom \
|
||||
sha256:abc123...
|
||||
```
|
||||
|
||||
## Output Formats
|
||||
|
||||
### JSON Output
|
||||
|
||||
```bash
|
||||
cosign verify-attestation \
|
||||
--key public.key \
|
||||
--type custom \
|
||||
--output-file verification-result.json \
|
||||
sha256:abc123...
|
||||
```
|
||||
|
||||
### Text Output with Details
|
||||
|
||||
```bash
|
||||
cosign verify-attestation \
|
||||
--key public.key \
|
||||
--type custom \
|
||||
-v \
|
||||
sha256:abc123...
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Errors
|
||||
|
||||
| Error | Cause | Solution |
|
||||
|-------|-------|----------|
|
||||
| `no matching attestation found` | No attestation attached to image | Verify attestation was uploaded |
|
||||
| `key verification failed` | Wrong key or corrupted signature | Check key matches signer |
|
||||
| `certificate expired` | Signing certificate past validity | Use Rekor timestamp verification |
|
||||
| `OIDC issuer mismatch` | Wrong issuer in verify command | Check certificate's issuer field |
|
||||
| `predicate type mismatch` | Wrong --type argument | Use correct predicate URI |
|
||||
|
||||
### Debug Commands
|
||||
|
||||
```bash
|
||||
# List all attestations on an image
|
||||
cosign tree sha256:abc123...
|
||||
|
||||
# Download and inspect attestation
|
||||
cosign download attestation sha256:abc123... | jq .
|
||||
|
||||
# Verify with verbose output
|
||||
cosign verify-attestation \
|
||||
--key public.key \
|
||||
--type custom \
|
||||
-v \
|
||||
sha256:abc123... 2>&1 | tee verify.log
|
||||
|
||||
# Check certificate chain
|
||||
cosign download attestation sha256:abc123... | \
|
||||
jq -r '.payload' | base64 -d | jq -r '.subject'
|
||||
```
|
||||
|
||||
### Verify Certificate Details
|
||||
|
||||
```bash
|
||||
# Extract and inspect the signing certificate
|
||||
cosign download attestation sha256:abc123... | \
|
||||
jq -r '.signatures[0].cert' | base64 -d | \
|
||||
openssl x509 -noout -text
|
||||
```
|
||||
|
||||
## Integration with CI/CD
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
```yaml
|
||||
- name: Verify attestation
|
||||
uses: sigstore/cosign-installer@main
|
||||
|
||||
- name: Verify StellaOps attestation
|
||||
run: |
|
||||
cosign verify-attestation \
|
||||
--certificate-identity "https://github.com/${{ github.repository }}/.github/workflows/build.yml@${{ github.ref }}" \
|
||||
--certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
|
||||
--type "https://stella-ops.org/attestation/scan-results/v1" \
|
||||
${{ env.IMAGE_DIGEST }}
|
||||
```
|
||||
|
||||
### GitLab CI
|
||||
|
||||
```yaml
|
||||
verify-attestation:
|
||||
image: bitnami/cosign:latest
|
||||
script:
|
||||
- cosign verify-attestation
|
||||
--certificate-identity "https://gitlab.com/${CI_PROJECT_PATH}/.gitlab-ci.yml@${CI_COMMIT_REF_NAME}"
|
||||
--certificate-oidc-issuer "https://gitlab.com"
|
||||
--type "https://stella-ops.org/attestation/scan-results/v1"
|
||||
${IMAGE_DIGEST}
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [DSSE Round-Trip Verification](./dsse-roundtrip-verification.md)
|
||||
- [Transparency Log Integration](./transparency.md)
|
||||
- [Air-Gap Operation](./airgap.md)
|
||||
- [Sigstore Documentation](https://docs.sigstore.dev)
|
||||
Reference in New Issue
Block a user