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.
240 lines
12 KiB
Markdown
240 lines
12 KiB
Markdown
# Policy Lifecycle & Approvals
|
||
|
||
> **Audience:** Policy authors, reviewers, security approvers, release engineers.
|
||
> **Scope:** End-to-end flow for `stella-dsl@1` policies from draft through archival, including CLI/Console touch-points, Authority scopes, audit artefacts, and offline considerations.
|
||
|
||
This guide explains how a policy progresses through Stella Ops, which roles are involved, and the artefacts produced at every step. Pair it with the [Policy Engine Overview](overview.md), [DSL reference](dsl.md), and upcoming run documentation to ensure consistent authoring and rollout.
|
||
|
||
---
|
||
|
||
## 1 · Protocol Summary
|
||
|
||
- Policies are **immutable versions** attached to a stable `policy_id`.
|
||
- Lifecycle states: `draft → submitted → approved → active → archived`.
|
||
- Every transition requires explicit Authority scopes and produces structured events + storage artefacts (`policies`, `policy_runs`, audit log collections).
|
||
- Simulation and CI gating happen **before** approvals can be granted.
|
||
- Activation triggers (runs, bundle exports, CLI `promote`) operate on the **latest approved** version per tenant.
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> Draft
|
||
Draft --> Draft: edit/save (policy:write)
|
||
Draft --> Submitted: submit(reviewers) (policy:submit)
|
||
Submitted --> Draft: requestChanges (policy:write)
|
||
Submitted --> Approved: approve (policy:approve)
|
||
Approved --> Active: activate/run (policy:run)
|
||
Active --> Archived: archive (policy:archive)
|
||
Approved --> Archived: superseded/explicit archive
|
||
Archived --> [*]
|
||
```
|
||
|
||
---
|
||
|
||
## 2 · Roles & Authority Scopes
|
||
|
||
| Role (suggested) | Required scopes | Responsibilities |
|
||
|------------------|-----------------|------------------|
|
||
| **Policy Author** | `policy:write`, `policy:submit`, `policy:simulate` | Draft DSL, run local/CI simulations, submit for review. |
|
||
| **Policy Reviewer** | `policy:review`, `policy:simulate`, `policy:runs` | Comment on submissions, demand additional simulations, request changes. |
|
||
| **Policy Approver** | `policy:approve`, `policy:runs`, `policy:audit` | Grant final approval, ensure sign-off evidence captured. |
|
||
| **Policy Operator** | `policy:run`, `policy:activate`, `findings:read` | Trigger full/incremental runs, monitor results, roll back to previous version. |
|
||
| **Policy Auditor** | `policy:audit`, `findings:read`, `policy:history` | Review past versions, verify attestations, respond to compliance requests. |
|
||
| **Policy Engine Service** | `effective:write`, `findings:read` | Materialise effective findings during runs; no approval capabilities. |
|
||
|
||
> Scopes are issued by Authority (`AUTH-POLICY-20-001`). Tenants may map organisational roles (e.g., `secops.approver`) to these scopes via issuer policy.
|
||
|
||
---
|
||
|
||
## 3 · Lifecycle Stages in Detail
|
||
|
||
### 3.1 Draft
|
||
|
||
- **Who:** Authors (policy:write).
|
||
- **Tools:** Console editor, `stella policy edit`, policy DSL files.
|
||
- **Actions:**
|
||
- Author DSL leveraging [stella-dsl@1](dsl.md).
|
||
- Run `stella policy lint` and `stella policy simulate --sbom <fixtures>` locally.
|
||
- Attach rationale metadata (`metadata.description`, tags).
|
||
- **Artefacts:**
|
||
- `policies` document with `status=draft`, `version=n`, `provenance.created_by`.
|
||
- Local IR cache (`.stella.ir.json`) generated by CLI compile.
|
||
- **Guards:**
|
||
- Draft versions never run in production.
|
||
- CI must lint drafts before allowing submission PRs (see `DEVOPS-POLICY-20-001`).
|
||
|
||
### 3.2 Submission
|
||
|
||
- **Who:** Authors with `policy:submit`.
|
||
- **Tools:** Console “Submit for review” button, `stella policy submit <policyId> --reviewers ...`.
|
||
- **Actions:**
|
||
- Provide review notes and required simulations (CLI uploads attachments).
|
||
- Choose reviewer groups; Authority records them in submission metadata.
|
||
- **Artefacts:**
|
||
- Policy document transitions to `status=submitted`, capturing `submitted_by`, `submitted_at`, reviewer list, simulation digest references.
|
||
- Audit event `policy.submitted` (Authority timeline / Notifier integration).
|
||
- **Guards:**
|
||
- Submission blocked unless latest lint + compile succeed (<24 h freshness).
|
||
- Must reference at least one simulation artefact (CLI enforces via `--attach`).
|
||
|
||
### 3.3 Review (Submitted)
|
||
|
||
- **Who:** Reviewers (`policy:review`), optionally authors responding.
|
||
- **Tools:** Console review pane (line comments, overall verdict), `stella policy review`.
|
||
- **Actions:**
|
||
- Inspect DSL diff vs previous approved version.
|
||
- Run additional `simulate` jobs (UI button or CLI).
|
||
- Request changes → policy returns to `draft` with comment log.
|
||
- **Artefacts:**
|
||
- Comments stored in `policy_reviews` collection with timestamps, resolved flag.
|
||
- Additional simulation run records appended to submission metadata.
|
||
- **Guards:**
|
||
- Approval cannot proceed until all blocking comments resolved.
|
||
- Required reviewers (Authority rule) must vote before approver sees “Approve” button.
|
||
|
||
### 3.4 Approval
|
||
|
||
- **Who:** Approvers (`policy:approve`).
|
||
- **Tools:** Console “Approve”, CLI `stella policy approve <id> --version n --note "rationale"`.
|
||
- **Actions:**
|
||
- Confirm compliance checks (see §6) all green.
|
||
- Provide approval note (mandatory string captured in audit trail).
|
||
- **Artefacts:**
|
||
- Policy `status=approved`, `approved_by`, `approved_at`, `approval_note`.
|
||
- Audit event `policy.approved` plus optional Notifier broadcast.
|
||
- Immutable approval record stored in `policy_history`.
|
||
- **Guards:**
|
||
- Approver cannot be same identity as author (enforced by Authority config).
|
||
- Approver must attest to successful simulation diff review (`--attach diff.json`).
|
||
|
||
### 3.5 Activation & Runs
|
||
|
||
- **Who:** Operators (`policy:run`, `policy:activate`).
|
||
- **Tools:** Console “Promote to active”, CLI `stella policy activate <id> --version n`, `stella policy run`.
|
||
- **Actions:**
|
||
- Mark approved version as tenant’s active policy.
|
||
- Trigger full run or rely on orchestrator for incremental runs.
|
||
- Monitor results via Console dashboards or CLI run logs.
|
||
- **Artefacts:**
|
||
- `policy_runs` entries with `mode=full|incremental`, `policy_version=n`.
|
||
- Effective findings collections updated; explain traces stored.
|
||
- Activation event `policy.activated` with `runId`.
|
||
- **Guards:**
|
||
- Activation blocked if previous full run <24 h old failed or is pending.
|
||
- Selection of SBOM/advisory snapshots uses consistent cursors recorded for reproducibility.
|
||
|
||
### 3.6 Archival / Rollback
|
||
|
||
- **Who:** Approvers or Operators with `policy:archive`.
|
||
- **Tools:** Console menu, CLI `stella policy archive <id> --version n --reason`.
|
||
- **Actions:**
|
||
- Retire policies superseded by newer versions or revert to older approved version (`stella policy activate <id> --version n-1`).
|
||
- Export archived version for audit bundles (Offline Kit integration).
|
||
- **Artefacts:**
|
||
- Policy `status=archived`, `archived_by`, `archived_at`, reason.
|
||
- Audit event `policy.archived`.
|
||
- Exported DSSE-signed policy pack stored if requested.
|
||
- **Guards:**
|
||
- Archival cannot proceed while runs using that version are in-flight.
|
||
- Rollback requires documented incident reference.
|
||
|
||
---
|
||
|
||
## 4 · Tooling Touchpoints
|
||
|
||
| Stage | Console | CLI | API |
|
||
|-------|---------|-----|-----|
|
||
| Draft | Inline linting, simulation panel | `stella policy lint`, `edit`, `simulate` | `POST /policies`, `PUT /policies/{id}/versions/{v}` |
|
||
| Submit | Submit modal (attach simulations) | `stella policy submit` | `POST /policies/{id}/submit` |
|
||
| Review | Comment threads, diff viewer | `stella policy review --approve/--request-changes` | `POST /policies/{id}/reviews` |
|
||
| Approve | Approve dialog | `stella policy approve` | `POST /policies/{id}/approve` |
|
||
| Activate | Promote button, run scheduler | `stella policy activate`, `run`, `simulate` | `POST /policies/{id}/run`, `POST /policies/{id}/activate` |
|
||
| Archive | Archive / rollback menu | `stella policy archive` | `POST /policies/{id}/archive` |
|
||
|
||
All CLI commands emit structured JSON by default; use `--format table` for human review.
|
||
|
||
---
|
||
|
||
## 5 · Audit & Observability
|
||
|
||
- **Storage:**
|
||
- `policies` retains all versions with provenance metadata.
|
||
- `policy_reviews` stores reviewer comments, timestamps, attachments.
|
||
- `policy_history` summarises transitions (state, actor, note, diff digest).
|
||
- `policy_runs` retains input cursors and determinism hash per run.
|
||
- **Events:**
|
||
- `policy.submitted`, `policy.review.requested`, `policy.approved`, `policy.activated`, `policy.archived`, `policy.rollback`.
|
||
- Routed to Notifier + Timeline Indexer; offline deployments log to local event store.
|
||
- **Logs & metrics:**
|
||
- Policy Engine logs include `policyId`, `policyVersion`, `runId`, `approvalNote`.
|
||
- Observability dashboards (see forthcoming `/docs/observability/policy.md`) highlight pending approvals, run SLA, VEX overrides.
|
||
- **Reproducibility:**
|
||
- Each state transition stores IR checksum and simulation diff digests, enabling offline audit replay.
|
||
|
||
---
|
||
|
||
## 6 · Compliance Gates
|
||
|
||
| Gate | Stage | Enforced by | Requirement |
|
||
|------|-------|-------------|-------------|
|
||
| **DSL lint** | Draft → Submit | CLI/CI | `stella policy lint` successful within 24 h. |
|
||
| **Simulation evidence** | Submit | CLI/Console | Attach diff from `stella policy simulate` covering baseline SBOM set. |
|
||
| **Reviewer quorum** | Submit → Approve | Authority | Minimum approver/reviewer count configurable per tenant. |
|
||
| **Determinism CI** | Approve | DevOps job | Twin run diff passes (`DEVOPS-POLICY-20-003`). |
|
||
| **Activation health** | Approve → Activate | Policy Engine | Last run status succeeded; orchestrator queue healthy. |
|
||
| **Export validation** | Archive | Offline Kit | DSSE-signed policy pack generated for long-term retention. |
|
||
|
||
Failure of any gate emits a `policy.lifecycle.violation` event and blocks transition until resolved.
|
||
|
||
---
|
||
|
||
## 7 · Offline / Air-Gap Considerations
|
||
|
||
- Offline Kit bundles include:
|
||
- Approved policy packs (`.policy.bundle` + DSSE signatures).
|
||
- Submission/approval audit logs.
|
||
- Simulation diff JSON for reproducibility.
|
||
- Air-gapped sites operate with the same lifecycle:
|
||
- Approvals happen locally; Authority runs in enclave.
|
||
- Rollout requires manual import of policy packs from connected environment via signed bundles.
|
||
- `stella policy simulate --sealed` ensures no outbound calls; required before approval in sealed mode.
|
||
|
||
---
|
||
|
||
## 8 · Incident Response & Rollback
|
||
|
||
- Incident mode (triggered via `policy incident activate`) forces:
|
||
- Immediate incremental run to evaluate mitigation policies.
|
||
- Expanded trace retention for affected runs.
|
||
- Automatic snapshot of currently active policies for evidence locker.
|
||
- Rollback path:
|
||
1. `stella policy activate <id> --version <previous>` with incident note.
|
||
2. Orchestrator schedules full run to ensure findings align.
|
||
3. Archive problematic version with reason referencing incident ticket.
|
||
- Post-incident review must confirm new version passes gates before re-activation.
|
||
|
||
---
|
||
|
||
## 9 · CI/CD Integration (Reference)
|
||
|
||
- **Pre-merge:** run lint + simulation jobs against golden SBOM fixtures.
|
||
- **Post-merge (main):** compile, compute IR checksum, stage for Offline Kit.
|
||
- **Nightly:** determinism replay, `policy simulate` diff drift alerts, backlog of pending approvals.
|
||
- **Notifications:** Slack/Email via Notifier when submissions await review > SLA or approvals succeed.
|
||
|
||
---
|
||
|
||
## 10 · Compliance Checklist
|
||
|
||
- [ ] **Role mapping validated:** Authority issuer config maps organisational roles to required `policy:*` scopes (per tenant).
|
||
- [ ] **Submission evidence attached:** Latest simulation diff and lint artefacts linked to submission.
|
||
- [ ] **Reviewer quorum met:** All required reviewers approved or acknowledged; no unresolved blocking comments.
|
||
- [ ] **Approval note logged:** Approver justification recorded in audit trail alongside IR checksum.
|
||
- [ ] **Activation guard passed:** Latest run status success, orchestrator queue healthy, determinism job green.
|
||
- [ ] **Archive bundles produced:** When archiving, DSSE-signed policy pack exported and stored for offline retention.
|
||
- [ ] **Offline parity proven:** For sealed deployments, `--sealed` simulations executed and logged before approval.
|
||
|
||
---
|
||
|
||
*Last updated: 2025-10-26 (Sprint 20).*
|
||
|