up

ops/devops/policy-signing.md

@@ -0,0 +1,46 @@
+# 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.