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

Least privilege by scope – API clients receive only the policy:* scopes required for their role; effective:write reserved for service identity.
Immutable history – All policy changes, approvals, runs, and suppressions produce audit artefacts retrievable offline.
Separation of duties – Authors cannot approve their own submissions; approvers require distinct scope and should not have deployment rights.
Deterministic verification – Simulations, determinism checks, and incident replay bundles provide reproducible evidence for auditors.
Tenant isolation – Policies, runs, and findings scoped to tenants; cross-tenant access requires explicit admin scopes and is logged.
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).