git.stella-ops.org/docs/security/policy-governance.md

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 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).