Restructure solution layout by module
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
This commit is contained in:
root
@@ -1,112 +1,112 @@
|
||||
# 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:author` | Create/edit drafts, lint/compile, quick simulate. | `role/policy-author`. |
|
||||
| `policy:review` | Comment, request changes, approve in-progress drafts. | `role/policy-reviewer`. |
|
||||
| `policy:approve` | Final approval; archive decisions. | `role/policy-approver`. |
|
||||
| `policy:operate` | Promote revisions, trigger runs, manage rollouts. | `role/policy-operator`, automation bots. |
|
||||
| `policy:audit` | Access immutable history and evidence bundles. | `role/policy-auditor`, compliance teams. |
|
||||
| `policy:simulate` | Execute simulations via API/CLI. | Authors, reviewers, CI. |
|
||||
| `policy:run` | Trigger runs, inspect live status. | Operators, automation bots. |
|
||||
| `policy:activate` | Promote approved version, schedule activation. | Runtime operators / release managers. |
|
||||
| `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).*
|
||||
# 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:author` | Create/edit drafts, lint/compile, quick simulate. | `role/policy-author`. |
|
||||
| `policy:review` | Comment, request changes, approve in-progress drafts. | `role/policy-reviewer`. |
|
||||
| `policy:approve` | Final approval; archive decisions. | `role/policy-approver`. |
|
||||
| `policy:operate` | Promote revisions, trigger runs, manage rollouts. | `role/policy-operator`, automation bots. |
|
||||
| `policy:audit` | Access immutable history and evidence bundles. | `role/policy-auditor`, compliance teams. |
|
||||
| `policy:simulate` | Execute simulations via API/CLI. | Authors, reviewers, CI. |
|
||||
| `policy:run` | Trigger runs, inspect live status. | Operators, automation bots. |
|
||||
| `policy:activate` | Promote approved version, schedule activation. | Runtime operators / release managers. |
|
||||
| `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).*
|
||||
|
||||
Reference in New Issue
Block a user