stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity

up

Browse Source
This commit is contained in:
StellaOps Bot
2025-11-27 21:10:06 +02:00
parent cfa2274d31
commit 8abbf9574d
106 changed files with 7078 additions and 3197 deletions
Download Patch File Download Diff File Expand all files Collapse all files

142
docs/policy/lifecycle.md
View File

@@ -3,19 +3,19 @@
> **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.
> **Imposed rule:** New or significantly changed policies must run in **shadow mode** with coverage fixtures before activation. Promotions are blocked until shadow + coverage gates pass.
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.
> **Imposed rule:** New or significantly changed policies must run in **shadow mode** with coverage fixtures before activation. Promotions are blocked until shadow + coverage gates pass.
---
## 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.
- Shadow mode runs capture findings without enforcement; shadow exit requires coverage + twin-run determinism checks.
- 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.
- Shadow mode runs capture findings without enforcement; shadow exit requires coverage + twin-run determinism checks.
```mermaid
stateDiagram-v2
@@ -55,9 +55,9 @@ stateDiagram-v2
- **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.
- Add/refresh coverage fixtures under `tests/policy/<policyId>/cases/*.json`; run `stella policy test`.
- Keep `settings.shadow = true` until coverage + shadow gates pass.
- Run `stella policy lint` and `stella policy simulate --sbom <fixtures>` locally.
- Add/refresh coverage fixtures under `tests/policy/<policyId>/cases/*.json`; run `stella policy test`.
- Keep `settings.shadow = true` until coverage + shadow gates pass.
- Attach rationale metadata (`metadata.description`, tags).
- **Artefacts:**
- `policies` document with `status=draft`, `version=n`, `provenance.created_by`.
@@ -71,8 +71,8 @@ stateDiagram-v2
- **Who:** Authors (`policy:author`).
- **Tools:** Console “Submit for review” button, `stella policy submit <policyId> --reviewers ...`.
- **Actions:**
- Provide review notes and required simulations (CLI uploads attachments).
- Attach coverage results (shadow mode + `stella policy test`).
- Provide review notes and required simulations (CLI uploads attachments).
- Attach coverage results (shadow mode + `stella policy test`).
- 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.
@@ -101,8 +101,8 @@ stateDiagram-v2
- **Who:** Approvers (`policy:approve`).
- **Tools:** Console “Approve”, CLI `stella policy approve <id> --version n --note "rationale"`.
- **Actions:**
- Confirm compliance checks (see §6) all green.
- Verify shadow gate + coverage suite passed in CI.
- Confirm compliance checks (see §6) all green.
- Verify shadow gate + coverage suite passed in CI.
- Provide approval note (mandatory string captured in audit trail).
- **Artefacts:**
- Policy `status=approved`, `approved_by`, `approved_at`, `approval_note`.
@@ -112,23 +112,23 @@ stateDiagram-v2
- Approver cannot be same identity as author (enforced by Authority config).
- Approver must attest to successful simulation diff review (`--attach diff.json`).
### 3.5 Signing & Publication
- **Who:** Operators with fresh-auth (`policy:publish`, `policy:promote`) and approval backing.
- **Tools:** Console “Publish & Sign” wizard, CLI `stella policy publish`, `stella policy promote`.
- **Actions:**
- Execute `stella policy publish <id> --version n --reason "<why>" --ticket SEC-123 --sign` to produce a DSSE attestation capturing IR digest + approval metadata.
- Provide required metadata headers (`policy_reason`, `policy_ticket`, `policy_digest`), enforced by Authority; CLI flags map to headers automatically.
- Promote the signed version to targeted environments (`stella policy promote <id> --version n --environment stage`).
- **Artefacts:**
- DSSE payload stored in `policy_attestations`, containing SHA-256 digest, signer, reason, ticket, promoted environment.
- Audit events `policy.published`, `policy.promoted` including metadata snapshot and attestation reference.
- **Guards:**
- Publish requires a fresh-auth window (<5 minutes) and interactive identity (client-credentials tokens are rejected).
- Metadata headers must be present; missing values return `policy_attestation_metadata_missing`.
- Signing key rotation enforced via Authority JWKS; CLI refuses to publish if attestation verification fails.
### 3.6 Activation & Runs
### 3.5 Signing & Publication
- **Who:** Operators with fresh-auth (`policy:publish`, `policy:promote`) and approval backing.
- **Tools:** Console “Publish & Sign” wizard, CLI `stella policy publish`, `stella policy promote`.
- **Actions:**
- Execute `stella policy publish <id> --version n --reason "<why>" --ticket SEC-123 --sign` to produce a DSSE attestation capturing IR digest + approval metadata.
- Provide required metadata headers (`policy_reason`, `policy_ticket`, `policy_digest`), enforced by Authority; CLI flags map to headers automatically.
- Promote the signed version to targeted environments (`stella policy promote <id> --version n --environment stage`).
- **Artefacts:**
- DSSE payload stored in `policy_attestations`, containing SHA-256 digest, signer, reason, ticket, promoted environment.
- Audit events `policy.published`, `policy.promoted` including metadata snapshot and attestation reference.
- **Guards:**
- Publish requires a fresh-auth window (<5 minutes) and interactive identity (client-credentials tokens are rejected).
- Metadata headers must be present; missing values return `policy_attestation_metadata_missing`.
- Signing key rotation enforced via Authority JWKS; CLI refuses to publish if attestation verification fails.
### 3.6 Activation & Runs
- **Who:** Operators (`policy:operate`, `policy:run`, `policy:activate`).
- **Tools:** Console “Promote to active”, CLI `stella policy activate <id> --version n`, `stella policy run`.
@@ -144,7 +144,7 @@ stateDiagram-v2
- 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.7 Archival / Rollback
### 3.7 Archival / Rollback
- **Who:** Approvers or Operators with `policy:archive`.
- **Tools:** Console menu, CLI `stella policy archive <id> --version n --reason`.
@@ -165,7 +165,7 @@ stateDiagram-v2
| Stage | Console | CLI | API |
|-------|---------|-----|-----|
| Draft | Inline linting, simulation panel | `stella policy lint`, `edit`, `simulate` | `POST /policies`, `PUT /policies/{id}/versions/{v}` |
| Draft | Inline linting, simulation panel | `stella policy lint`, `edit`, `test`, `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` |
@@ -174,6 +174,40 @@ stateDiagram-v2
All CLI commands emit structured JSON by default; use `--format table` for human review.
### 4.1 · CLI Command Reference
#### `stella policy edit <file>`
Open a policy DSL file in your configured editor (`$EDITOR` or `$VISUAL`), validate after editing, and optionally commit with SemVer metadata.
**Options:**
- `-c, --commit` - Commit changes after successful validation
- `-V, --version <semver>` - SemVer version for commit metadata (e.g., `1.2.0`)
- `-m, --message <msg>` - Custom commit message (auto-generated if not provided)
- `--no-validate` - Skip validation after editing (not recommended)
**Example:**
```bash
# Edit and commit with version metadata
stella policy edit policies/my-policy.dsl --commit --version 1.2.0
```
#### `stella policy test <file>`
Run coverage test fixtures against a policy DSL file to validate rule behavior.
**Options:**
- `-d, --fixtures <dir>` - Path to fixtures directory (defaults to `tests/policy/<policy-name>/cases`)
- `--filter <pattern>` - Run only fixtures matching this pattern
- `-f, --format <fmt>` - Output format: `table` (default) or `json`
- `-o, --output <file>` - Write test results to a file
- `--fail-fast` - Stop on first test failure
**Example:**
```bash
stella policy test policies/vuln-policy.dsl --filter critical
```
---
## 5 · Audit & Observability
@@ -194,25 +228,25 @@ All CLI commands emit structured JSON by default; use `--format table` for human
---
## 6 · Compliance Gates
## 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. |
| **Shadow run** | Submit → Approve | Policy Engine / CI | Shadow mode enabled (`settings.shadow=true`) with findings recorded; must execute once per change. |
| **Coverage suite** | Submit → Approve | CI (`stella policy test`) | Coverage fixtures present and passing; artefact attached to submission. |
| **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`). |
| **Attestation metadata** | Approve → Publish | Authority / CLI | `policy:publish` executed with reason & ticket metadata; DSSE attestation verified. |
| **Activation health** | Publish/Promote → Activate | Policy Engine | Last run status succeeded; orchestrator queue healthy. |
| 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. |
| **Shadow run** | Submit → Approve | Policy Engine / CI | Shadow mode enabled (`settings.shadow=true`) with findings recorded; must execute once per change. |
| **Coverage suite** | Submit → Approve | CI (`stella policy test`) | Coverage fixtures present and passing; artefact attached to submission. |
| **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`). |
| **Attestation metadata** | Approve → Publish | Authority / CLI | `policy:publish` executed with reason & ticket metadata; DSSE attestation verified. |
| **Activation health** | Publish/Promote → 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
## 7 · Offline / Air-Gap Considerations
- Offline Kit bundles include:
- Approved policy packs (`.policy.bundle` + DSSE signatures).
@@ -225,7 +259,7 @@ Failure of any gate emits a `policy.lifecycle.violation` event and blocks transi
---
## 8 · Incident Response & Rollback
## 8 · Incident Response & Rollback
- Incident mode (triggered via `policy incident activate`) forces:
- Immediate incremental run to evaluate mitigation policies.
@@ -239,7 +273,7 @@ Failure of any gate emits a `policy.lifecycle.violation` event and blocks transi
---
## 9 · CI/CD Integration (Reference)
## 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.
@@ -248,18 +282,18 @@ Failure of any gate emits a `policy.lifecycle.violation` event and blocks transi
---
## 10 · Compliance Checklist
## 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.
- [ ] **Publish attestation signed:** `stella policy publish` executed by interactive operator, metadata (`policy_reason`, `policy_ticket`, `policy_digest`) present, DSSE attestation stored.
- [ ] **Promotion recorded:** Target environment promoted via CLI/Console with audit event linking to attestation.
- [ ] **Activation guard passed:** Latest run status success, orchestrator queue healthy, determinism job green.
- [ ] **Approval note logged:** Approver justification recorded in audit trail alongside IR checksum.
- [ ] **Publish attestation signed:** `stella policy publish` executed by interactive operator, metadata (`policy_reason`, `policy_ticket`, `policy_digest`) present, DSSE attestation stored.
- [ ] **Promotion recorded:** Target environment promoted via CLI/Console with audit event linking to attestation.
- [ ] **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-11-03 (Sprint 100).*
*Last updated: 2025-11-27 (Sprint 401).*