master
96d52884e8
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- Implemented PolicyDslValidator with command-line options for strict mode and JSON output. - Created PolicySchemaExporter to generate JSON schemas for policy-related models. - Developed PolicySimulationSmoke tool to validate policy simulations against expected outcomes. - Added project files and necessary dependencies for each tool. - Ensured proper error handling and usage instructions across tools.
115 lines
6.9 KiB
Markdown
115 lines
6.9 KiB
Markdown
# Policy Governance & Least Privilege
|
||
|
||
> **Audience:** Security Guild, Policy Guild, Authority Core, auditors.
|
||
> **Scope:** Scopes, RBAC, approval controls, tenancy, auditing, and compliance requirements for Policy Engine v2.
|
||
|
||
---
|
||
|
||
## 1 · Governance Principles
|
||
|
||
1. **Least privilege by scope** – API clients receive only the `policy:*` scopes required for their role; `effective:write` reserved for service identity.
|
||
2. **Immutable history** – All policy changes, approvals, runs, and suppressions produce audit artefacts retrievable offline.
|
||
3. **Separation of duties** – Authors cannot approve their own submissions; approvers require distinct scope and should not have deployment rights.
|
||
4. **Deterministic verification** – Simulations, determinism checks, and incident replay bundles provide reproducible evidence for auditors.
|
||
5. **Tenant isolation** – Policies, runs, and findings scoped to tenants; cross-tenant access requires explicit admin scopes and is logged.
|
||
6. **Offline parity** – Air-gapped sites follow the same governance workflow with sealed-mode safeguards and signed bundles.
|
||
|
||
---
|
||
|
||
## 2 · Authority Scopes & Role Mapping
|
||
|
||
| Scope | Description | Recommended role |
|
||
|-------|-------------|------------------|
|
||
| `policy:read` | View policies, revisions, runs, findings. | Readers, auditors. |
|
||
| `policy:write` | Create/edit drafts, run lint/compile. | Authors (SecOps engineers). |
|
||
| `policy:submit` | Move draft → submitted, attach simulations. | Authors with submission rights. |
|
||
| `policy:review` | Comment/approve/request changes (non-final). | Reviewers (peer security, product). |
|
||
| `policy:approve` | Final approval; can archive. | Approval board/security lead. |
|
||
| `policy:activate` | Promote approved version, schedule activation. | Runtime operators / release managers. |
|
||
| `policy:run` | Trigger runs, inspect live status. | Operators, automation bots. |
|
||
| `policy:runs` | Read run history, replay bundles. | Operators, auditors. |
|
||
| `policy:archive` | Retire versions, perform rollbacks. | Approvers, operators. |
|
||
| `policy:simulate` | Execute simulations via API/CLI. | Authors, reviewers, CI. |
|
||
| `policy:operate` | Activate incident mode, toggle sampling. | SRE/on-call. |
|
||
| `findings:read` | View effective findings/explain. | Analysts, auditors, CLI. |
|
||
| `effective:write` | **Service only** – materialise findings. | Policy Engine service principal. |
|
||
|
||
> Map organisation roles to scopes via Authority issuer config (`authority.tenants[].roles`). Document assignments in tenant onboarding checklist.
|
||
|
||
> **Authority configuration tip:** the Policy Engine service client must include `properties.serviceIdentity: policy-engine` and a tenant hint in `authority.yaml`. Authority rejects `effective:write` tokens that lack this marker. See [Authority scopes](authority-scopes.md) for the full scope catalogue.
|
||
|
||
---
|
||
|
||
## 3 · Workflow Controls
|
||
|
||
- **Submit gate:** CLI/UI require fresh lint + simulation artefacts (<24 h). Submissions store reviewer list and diff attachments.
|
||
- **Review quorum:** Authority policy enforces minimum reviewers (e.g., 2) and optional separation between functional/security domains.
|
||
- **Approval guard:** Approvers must acknowledge simulation + determinism check completion. CLI enforces `--note` and `--attach` fields.
|
||
- **Activation guard:** Policy Engine refuses activation when latest full run status ≠ success or incremental backlog aged > SLA.
|
||
- **Rollback policy:** Rollbacks require incident reference and produce `policy.rollback` audit events.
|
||
|
||
---
|
||
|
||
## 4 · Tenancy & Data Access
|
||
|
||
- Policies stored per tenant; `tenant-global` used for shared baselines.
|
||
- API filters all requests by `X-Stella-Tenant` (default from token). Cross-tenant requests require `policy:tenant-admin`.
|
||
- Effective findings collections include `tenant` field and unique indexes preventing cross-tenant writes.
|
||
- CLI/Console display tenant context prominently; switching tenant triggers warnings when active policy differs.
|
||
- Offline bundles encode tenant metadata; import commands validate compatibility before applying.
|
||
|
||
---
|
||
|
||
## 5 · Audit & Evidence
|
||
|
||
- **Collections:** `policies`, `policy_reviews`, `policy_history`, `policy_runs`, `policy_run_events`, `effective_finding_*_history`.
|
||
- **Events:** `policy.submitted`, `policy.review.requested`, `policy.approved`, `policy.activated`, `policy.archived`, `policy.run.*`, `policy.incident.*`.
|
||
- **Explain traces:** Stored for critical findings (sampled); available via CLI/UI for auditors (requires `findings:read`).
|
||
- **Offline evidence:** `stella policy bundle export` produces DSSE-signed packages containing DSL, IR digest, simulations, approval notes, run summaries, trace metadata.
|
||
- **Retention:** Default 365 days for run history, extendable per compliance requirements; incident mode extends to 30 days minimum.
|
||
|
||
---
|
||
|
||
## 6 · Secrets & Configuration Hygiene
|
||
|
||
- Policy Engine configuration loaded from environment/secret stores; no secrets in repo.
|
||
- CLI profiles should store tokens encrypted (`stella profile set --secret`).
|
||
- UI/CLI logs redact tokens, reviewer emails, and attachments.
|
||
- Rotating tokens/keys: Authority exposes `policy scopes` in discovery docs; follow `/docs/security/authority-scopes.md` for rotation.
|
||
- Use `policy:operate` to disable self-service simulation temporarily during incident response if needed.
|
||
|
||
---
|
||
|
||
## 7 · Incident Response
|
||
|
||
- Trigger incident mode for determinism violations, backlog surges, or suspected policy abuse.
|
||
- Capture replay bundles and run `stella policy run replay` for affected runs.
|
||
- Coordinate with Observability dashboards (see `/docs/observability/policy.md`) to monitor queue depth, failures.
|
||
- After resolution, document remediation in Lifecycle guide (§8) and attach to approval history.
|
||
|
||
---
|
||
|
||
## 8 · Offline / Air-Gapped Governance
|
||
|
||
- Same scopes apply; tokens issued by local Authority.
|
||
- Approvers must use offline UI/CLI to sign submissions; attachments stored locally.
|
||
- Bundle import/export must be signed (DSSE + cosign). CLI warns if signatures missing.
|
||
- Sealed-mode banner reminds operators to refresh bundles when staleness thresholds exceeded.
|
||
- Offline audits rely on evidence bundles and local `policy_runs` snapshot.
|
||
|
||
---
|
||
|
||
## 9 · Compliance Checklist
|
||
|
||
- [ ] **Scope mapping reviewed:** Authority issuer config updated; RBAC matrix stored with change request.
|
||
- [ ] **Separation enforced:** Automated checks block self-approval; review quorum satisfied.
|
||
- [ ] **Activation guard documented:** Operators trained on run health checks before promoting.
|
||
- [ ] **Audit exports tested:** Evidence bundles verified (hash/signature) and stored per compliance policy.
|
||
- [ ] **Incident drills rehearsed:** Replay/rollback procedures executed and logged.
|
||
- [ ] **Offline parity confirmed:** Air-gapped site executes submit/approve flow with sealed-mode guidance.
|
||
- [ ] **Documentation cross-links:** References to lifecycle, runs, observability, CLI, and API docs validated.
|
||
|
||
---
|
||
|
||
*Last updated: 2025-10-26 (Sprint 20).*
|