f98cea3bcf
- Introduced AuthorityAdvisoryAiOptions and related classes for managing advisory AI configurations, including remote inference options and tenant-specific settings. - Added AuthorityApiLifecycleOptions to control API lifecycle settings, including legacy OAuth endpoint configurations. - Implemented validation and normalization methods for both advisory AI and API lifecycle options to ensure proper configuration. - Created AuthorityNotificationsOptions and its related classes for managing notification settings, including ack tokens, webhooks, and escalation options. - Developed IssuerDirectoryClient and related models for interacting with the issuer directory service, including caching mechanisms and HTTP client configurations. - Added support for dependency injection through ServiceCollectionExtensions for the Issuer Directory Client. - Updated project file to include necessary package references for the new Issuer Directory Client library.
166 lines
6.4 KiB
Markdown
166 lines
6.4 KiB
Markdown
> **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`
|
||
- Dashboards should track the `authority.pack_scope_violation` tag alongside `authority.aoc_scope_violation` to highlight mis-scoped automation clients. Break down counts by `authority.client_id` to surface stale Task Runner or registry configurations quickly.
|
||
- 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).*
|