9f6e6f7fb3
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Signals CI & Image / signals-ci (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Policy Simulation / policy-simulate (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
devportal-offline / build-offline (push) Has been cancelled
47 lines
2.9 KiB
Markdown
47 lines
2.9 KiB
Markdown
# Policy Signing & Attestation (DevOps)
|
||
|
||
## Purpose
|
||
- Keep policy artefacts (DSL files, bundles) signed with a short‑lived cosign key (or OIDC workload identity) so promotion is verifiable offline.
|
||
- Provide deterministic, reproducible signing/attestation flows that runners can execute without external registries.
|
||
- Make key rotation and verification one-liners for on-call and CI.
|
||
|
||
## Scripts
|
||
- `scripts/policy/rotate-key.sh` – generate cosign keypair, emit base64 values for CI secrets in `out/policy-sign/keys/`.
|
||
- `scripts/policy/sign-policy.sh` – sign a policy blob with `COSIGN_KEY_B64` and verify the signature; emits signature + public key to `out/policy-sign/`.
|
||
- `scripts/policy/attest-verify.sh` – create a DSSE attestation for a policy blob and verify it against the generated bundle/public key.
|
||
|
||
## Local / CI workflow
|
||
1. **Generate key (ephemeral or rotated):**
|
||
```bash
|
||
OUT_DIR=out/policy-sign/keys PREFIX=ci-policy COSIGN_PASSWORD= scripts/policy/rotate-key.sh
|
||
```
|
||
Copy the base64 strings from `out/policy-sign/keys/README.txt` into `POLICY_COSIGN_KEY_B64` / `POLICY_COSIGN_PUB_B64` secrets.
|
||
2. **Sign a policy:**
|
||
```bash
|
||
export COSIGN_KEY_B64=$(base64 -w0 out/policy-sign/keys/ci-policy-cosign.key)
|
||
COSIGN_PASSWORD= scripts/policy/sign-policy.sh --file docs/examples/policies/baseline.stella --out-dir out/policy-sign
|
||
```
|
||
Outputs: `baseline.stella.sig`, `cosign.pub`.
|
||
3. **Attest + verify:**
|
||
```bash
|
||
export COSIGN_KEY_B64=$(base64 -w0 out/policy-sign/keys/ci-policy-cosign.key)
|
||
COSIGN_PASSWORD= scripts/policy/attest-verify.sh --file docs/examples/policies/baseline.stella --out-dir out/policy-sign
|
||
```
|
||
Outputs: DSSE bundle `.attestation.sigstore` and re-verifies it with the public key.
|
||
4. **CI stage:** `.gitea/workflows/policy-simulate.yml` now installs cosign, runs the three steps above, and publishes `out/policy-sign/` as an artifact alongside simulation outputs.
|
||
|
||
## OIDC / workload identity
|
||
- Runners with keyless cosign enabled can skip `COSIGN_KEY_B64` and rely on `COSIGN_EXPERIMENTAL=1` + `COSIGN_FULCIO_URL`/`COSIGN_REKOR_URL`; keep offline jobs on key mode.
|
||
- Rotate keys per environment; keep prod keys in Gitea secrets and staging keys in repo‑local `out/` for reproducibility.
|
||
|
||
## Verification quick check
|
||
- To verify a policy blob from artifacts:
|
||
```bash
|
||
cosign verify-blob --key out/policy-sign/cosign.pub --signature out/policy-sign/baseline.stella.sig docs/examples/policies/baseline.stella
|
||
cosign verify-blob-attestation --key out/policy-sign/cosign.pub --type stella.policy --bundle out/policy-sign/baseline.stella.attestation.sigstore docs/examples/policies/baseline.stella
|
||
```
|
||
|
||
## Notes
|
||
- All outputs are deterministic (UTC timestamps, fixed file names) to stay audit-friendly and offline-ready.
|
||
- Attestation predicate captures filename + SHA256 + timestamp for traceability. Update predicate schema if promotion metadata expands.
|