stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
7600caea632e9e44571bc1661003948a5e1d22fb
git.stella-ops.org/docs/security/policy-governance.md
root 68da90a11a
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
Restructure solution layout by module
2025-10-28 15:10:40 +02:00

6.9 KiB
Raw Blame History

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