This commit is contained in:
165
docs/security/pack-signing-and-rbac.md
Normal file
165
docs/security/pack-signing-and-rbac.md
Normal file
@@ -0,0 +1,165 @@
|
||||
> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
|
||||
|
||||
# Pack Signing & RBAC Controls
|
||||
|
||||
This document defines signing, verification, and authorization requirements for Task Packs across the CLI, Packs Registry, Task Runner, and Offline Kit. It aligns with Authority sprint tasks (`AUTH-PACKS-41-001`, `AUTH-PACKS-43-001`) and security guild expectations.
|
||||
|
||||
---
|
||||
|
||||
## 1 · Threat Model Highlights
|
||||
|
||||
| Threat | Mitigation |
|
||||
|--------|------------|
|
||||
| Unsigned or tampered pack uploaded to registry | Mandatory cosign/DSSE verification before acceptance. |
|
||||
| Unauthorized user publishing or promoting packs | Authority scopes (`Packs.Write`) + registry policy checks. |
|
||||
| Privilege escalation during approvals | Approval gates require `Packs.Approve` + audit logging; fresh-auth recommended. |
|
||||
| Secret exfiltration via pack steps | Secrets injection sandbox with redaction, sealed-mode network guardrails, evidence review. |
|
||||
| Replay of old approval tokens | Approval payloads carry plan hash + expiry; Task Runner rejects mismatches. |
|
||||
| Malicious pack in Offline Kit | Mirror verification using signed manifest and DSSE provenance. |
|
||||
|
||||
---
|
||||
|
||||
## 2 · Signing Requirements
|
||||
|
||||
- **Cosign** signatures required for all bundles. Keys can be:
|
||||
- Keyless (Fulcio OIDC).
|
||||
- KMS-backed (HSM, cloud KMS).
|
||||
- Offline keys stored in secure vault (air-gapped mode).
|
||||
- **DSSE Attestations** recommended to embed:
|
||||
- Manifest digest.
|
||||
- Build metadata (repo, commit, CI run).
|
||||
- CLI version (`stella/pack`).
|
||||
- Signatures stored alongside bundle in registry object storage.
|
||||
- `stella pack push` refuses to publish without signature (unless `--insecure-publish` used in dev).
|
||||
- Registry enforces trust policy:
|
||||
|
||||
| Policy | Description |
|
||||
|--------|-------------|
|
||||
| `anyOf` | Accepts any key in configured trust store. |
|
||||
| `keyRef` | Accepts specific key ID (`kid`). |
|
||||
| `oidcIssuer` | Accepts Fulcio certificates from allowed issuers (e.g., `https://fulcio.sigstore.dev`). |
|
||||
| `threshold` | Requires N-of-M signatures (future release). |
|
||||
|
||||
---
|
||||
|
||||
## 3 · RBAC & Scopes
|
||||
|
||||
Authority exposes pack-related scopes:
|
||||
|
||||
| Scope | Description |
|
||||
|-------|-------------|
|
||||
| `Packs.Read` | View packs, download manifests/bundles. |
|
||||
| `Packs.Write` | Publish, promote, deprecate packs. |
|
||||
| `Packs.Run` | Execute packs (Task Runner, CLI). |
|
||||
| `Packs.Approve` | Approve pack gates, override tenant visibility. |
|
||||
|
||||
### 3.1 Role Mapping
|
||||
|
||||
| Role | Scopes | Use Cases |
|
||||
|------|--------|-----------|
|
||||
| `pack.viewer` | `Packs.Read` | Inspect packs, plan runs. |
|
||||
| `pack.publisher` | `Packs.Read`, `Packs.Write` | Publish new versions, manage channels. |
|
||||
| `pack.operator` | `Packs.Read`, `Packs.Run` | Execute packs, monitor runs. |
|
||||
| `pack.approver` | `Packs.Read`, `Packs.Approve` | Fulfil approvals, authorize promotions. |
|
||||
| `pack.admin` | All | Full lifecycle management (rare). |
|
||||
|
||||
Roles are tenant-scoped; cross-tenant access requires explicit addition.
|
||||
|
||||
### 3.2 CLI Enforcement
|
||||
|
||||
- CLI requests scopes based on command:
|
||||
- `stella pack plan` → `Packs.Read`.
|
||||
- `stella pack run` → `Packs.Run`.
|
||||
- `stella pack push` → `Packs.Write`.
|
||||
- `stella pack approve` → `Packs.Approve`.
|
||||
- Offline tokens must include same scopes; CLI warns if missing.
|
||||
|
||||
---
|
||||
|
||||
## 4 · Approvals & Fresh Auth
|
||||
|
||||
- Approval commands require recent fresh-auth (< 5 minutes). CLI prompts automatically; Console enforces via Authority.
|
||||
- Approval payload includes:
|
||||
- `runId`
|
||||
- `gateId`
|
||||
- `planHash`
|
||||
- `approver`
|
||||
- `timestamp`
|
||||
- Task Runner logs approval event and verifies plan hash to prevent rerouting.
|
||||
|
||||
---
|
||||
|
||||
## 5 · Secret Management
|
||||
|
||||
- Secrets defined in pack manifest map to Authority secret providers (e.g., HSM, Vault).
|
||||
- Task Runner obtains secrets using service account with scoped access; CLI may prompt or read from profile.
|
||||
- Secret audit trail:
|
||||
- `secretRequested` event with reason, pack, step.
|
||||
- `secretDelivered` event omitted (only aggregate metrics) to avoid leakage.
|
||||
- Evidence bundle includes hashed secret metadata (no values).
|
||||
|
||||
Sealed mode requires secrets to originate from sealed vault; external endpoints blocked.
|
||||
|
||||
---
|
||||
|
||||
## 6 · Audit & Evidence
|
||||
|
||||
- Registry, Task Runner, and Authority emit audit events to central timeline.
|
||||
- Required events:
|
||||
- `pack.version.published`
|
||||
- `pack.version.promoted`
|
||||
- `pack.run.started/completed`
|
||||
- `pack.approval.requested/granted`
|
||||
- `pack.secret.requested`
|
||||
- Evidence Locker stores DSSE attestations and run bundles for 90 days (configurable).
|
||||
- Auditors can use `stella pack audit --run <id>` to retrieve audit trail.
|
||||
|
||||
---
|
||||
|
||||
## 7 · Offline / Air-Gap Policies
|
||||
|
||||
- Offline Kit includes:
|
||||
- Pack bundles + signatures.
|
||||
- Trusted key store (`trust-bundle.pem`).
|
||||
- Approval workflow instructions for manual signing.
|
||||
- Air-gapped approvals:
|
||||
- CLI generates approval request file (`.approval-request.json`).
|
||||
- Approver uses offline CLI to sign with offline key.
|
||||
- Response imported to Task Runner.
|
||||
- Mirror process verifies signatures prior to import; failure aborts import with `ERR_PACK_SIGNATURE_INVALID`.
|
||||
|
||||
---
|
||||
|
||||
## 8 · Incident Response
|
||||
|
||||
- Compromised pack signature:
|
||||
- Revoke key via Authority trust store.
|
||||
- Deprecate affected versions (`registry deprecate`).
|
||||
- Notify consumers via Notifier (`pack.security.alert`).
|
||||
- Forensically review run evidence for impacted tenants.
|
||||
- Unauthorized approval:
|
||||
- Review audit log for `Packs.Approve` events.
|
||||
- Trigger `pack.run.freeze` (pauses run pending investigation).
|
||||
- Rotate approver credentials and require fresh-auth.
|
||||
- Secret leak suspicion:
|
||||
- Quarantine evidence bundles.
|
||||
- Rotate secrets referenced by pack.
|
||||
- Run sealed-mode audit script to confirm guardrails.
|
||||
|
||||
---
|
||||
|
||||
## 9 · Compliance Checklist
|
||||
|
||||
- [ ] Signing requirements (cosign/DSSE, trust policies) documented.
|
||||
- [ ] Authority scope mapping and CLI enforcement captured.
|
||||
- [ ] Approval workflow + fresh-auth expectations defined.
|
||||
- [ ] Secret lifecycle (request, injection, audit) described.
|
||||
- [ ] Audit/evidence integration noted (timeline, Evidence Locker).
|
||||
- [ ] Offline/air-gap controls outlined.
|
||||
- [ ] Incident response playbook provided.
|
||||
- [ ] Imposed rule reminder retained at top.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-27 (Sprint 43).*
|
||||
|
||||
Reference in New Issue
Block a user