Add Policy DSL Validator, Schema Exporter, and Simulation Smoke tools

- 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.
2025-10-27 08:00:11 +02:00
parent 651b8e0fa3
commit 96d52884e8
712 changed files with 49449 additions and 6124 deletions
--- a/docs/cli/policy.md
+++ b/docs/cli/policy.md
@@ -0,0 +1,284 @@
+# Stella CLI — Policy Commands
+
+> **Audience:** Policy authors, reviewers, operators, and CI engineers using the `stella` CLI to interact with Policy Engine.  
+> **Supported from:** `stella` CLI ≥ 0.20.0 (Policy Engine v2 sprint line).  
+> **Prerequisites:** Authority-issued bearer token with the scopes noted per command (export `STELLA_TOKEN` or pass `--token`).
+
+---
+
+## 1 · Global Options & Output Modes
+
+All `stella policy *` commands honour the common CLI options:
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--server <url>` | `https://stella.local` | Policy Engine gateway root. |
+| `--tenant <id>` | token default | Override tenant for multi-tenant installs. |
+| `--format <table\|json\|yaml>` | `table` for TTY, `json` otherwise | Output format for listings/diffs. |
+| `--output <file>` | stdout | Write full JSON payload to file. |
+| `--sealed` | false | Force sealed-mode behaviour (no outbound fetch). |
+| `--trace` | false | Emit verbose timing/log correlation info. |
+
+> **Tip:** Set `STELLA_PROFILE=policy` in CI to load saved defaults from `~/.stella/profiles/policy.toml`.
+
+---
+
+## 2 · Authoring & Drafting Commands
+
+### 2.1 `stella policy new`
+
+Create a draft policy from a template or scratch.
+
+```
+stella policy new --policy-id P-7 --name "Default Org Policy" \
+  --template baseline --output-path policies/P-7.stella
+```
+
+Options:
+
+| Flag | Description |
+|------|-------------|
+| `--policy-id` *(required)* | Stable identifier (e.g., `P-7`). |
+| `--name` | Friendly display name. |
+| `--template` | `baseline`, `serverless`, `blank`. |
+| `--from` | Start from existing version (`policyId@version`). |
+| `--open` | Launches `$EDITOR` after creation. |
+
+Writes DSL to local file and registers draft version (`status=draft`). Requires `policy:write`.
+
+### 2.2 `stella policy edit`
+
+Open an existing draft in the local editor.
+
+```
+stella policy edit P-7 --version 4
+```
+
+- Auto-checks out latest draft if `--version` omitted.
+- Saves to temp file, uploads on editor exit (unless `--no-upload`).
+- Use `--watch` to keep command alive and re-upload on every save.
+
+### 2.3 `stella policy lint`
+
+Static validation without submitting.
+
+```
+stella policy lint policies/P-7.stella --format json
+```
+
+Outputs diagnostics (line/column, code, message). Exit codes:
+
+| Code | Meaning |
+|------|---------|
+| `0` | No lint errors. |
+| `10` | Syntax/compile errors (`ERR_POL_001`). |
+| `11` | Unsupported syntax version. |
+
+### 2.4 `stella policy compile`
+
+Emits IR digest and rule summary.
+
+```
+stella policy compile P-7 --version 4
+```
+
+Returns JSON with `digest`, `rules.count`, action counts. Exit `0` success, `10` on compile errors.
+
+---
+
+## 3 · Lifecycle Workflow
+
+### 3.1 Submit
+
+```
+stella policy submit P-7 --version 4 \
+  --reviewer user:kay --reviewer group:sec-reviewers \
+  --note "Simulated against golden SBOM set" \
+  --attach sims/P-7-v4-vs-v3.json
+```
+
+Requires `policy:submit`. CLI validates that lint/compile run within 24 h and bundle attachments exist.
+
+### 3.2 Review
+
+```
+stella policy review P-7 --version 4 --approve \
+  --note "Looks good; ensure incident playbook updated."
+```
+
+- `--approve`, `--request-changes`, or `--comment`.
+- Provide `--blocking` to mark comment as blocking.
+- Requires `policy:review`.
+
+### 3.3 Approve
+
+```
+stella policy approve P-7 --version 4 \
+  --note "Determinism CI green; simulation diff attached." \
+  --attach sims/P-7-v4-vs-v3.json
+```
+
+Prompts for confirmation; refuses if approver == submitter. Requires `policy:approve`.
+
+### 3.4 Activate
+
+```
+stella policy activate P-7 --version 4 --run-now --priority high
+```
+
+- Optional `--scheduled-at 2025-10-27T02:00:00Z`.
+- Requires `policy:activate` and `policy:run`.
+
+### 3.5 Archive / Rollback
+
+```
+stella policy archive P-7 --version 3 --reason "Superseded by v4"
+stella policy activate P-7 --version 3 --rollback --incident INC-2025-104
+```
+
+---
+
+## 4 · Simulation & Runs
+
+### 4.1 Simulate
+
+```
+stella policy simulate P-7 \
+  --base 3 --candidate 4 \
+  --sbom sbom:S-42 --sbom sbom:S-318 \
+  --env exposure=internet --env sealed=false \
+  --format json --output sims/P-7-v4-vs-v3.json
+```
+
+Output fields (JSON):
+
+```json
+{
+  "diff": {
+    "added": 12,
+    "removed": 8,
+    "unchanged": 657,
+    "bySeverity": {
+      "Critical": {"up": 1, "down": 0},
+      "High": {"up": 3, "down": 4}
+    }
+  },
+  "explainUri": "blob://policy/P-7/simulations/2025-10-26.json"
+}
+```
+
+> Schema reminder: CLI commands surface objects defined in `src/StellaOps.Scheduler.Models/docs/SCHED-MODELS-20-001-POLICY-RUNS.md`; use the samples in `samples/api/scheduler/` for contract validation when extending output parsing.
+
+Exit codes:
+
+| Code | Meaning |
+|------|---------|
+| `0` | Simulation succeeded; diffs informational. |
+| `20` | Blocking delta (`--fail-on-diff` triggered). |
+| `21` | Simulation input missing (`ERR_POL_003`). |
+| `22` | Determinism guard (`ERR_POL_004`). |
+| `23` | API/permission error (`ERR_POL_002`, `ERR_POL_005`). |
+
+### 4.2 Run
+
+```
+stella policy run P-7 --mode full \
+  --sbom sbom:S-42 --env exposure=internal-only \
+  --wait --watch
+```
+
+Options:
+
+| Flag | Description |
+|------|-------------|
+| `--mode` | `full` or `incremental` (default incremental). |
+| `--sbom` | Explicit SBOM IDs (optional). |
+| `--priority` | `normal`, `high`, `emergency`. |
+| `--wait` | Poll run status until completion. |
+| `--watch` | Stream progress events (requires TTY). |
+
+`stella policy run status <runId>` retrieves run metadata.  
+`stella policy run list --status failed --limit 20` returns recent runs.
+
+### 4.3 Replay & Cancel
+
+```
+stella policy run replay run:P-7:2025-10-26:auto --output bundles/replay.tgz
+stella policy run cancel run:P-7:2025-10-26:auto
+```
+
+Replay downloads sealed bundle for deterministic verification.
+
+---
+
+## 5 · Findings & Explainability
+
+### 5.1 List Findings
+
+```
+stella findings ls --policy P-7 \
+  --sbom sbom:S-42 \
+  --status affected --severity High,Critical \
+  --format table
+```
+
+Common flags:
+
+| Flag | Description |
+|------|-------------|
+| `--page`, `--page-size` | Pagination (default page size 50). |
+| `--cursor` | Use cursor token from previous call. |
+| `--since` | ISO timestamp filter. |
+
+### 5.2 Fetch Explain
+
+```
+stella findings explain --policy P-7 --finding P-7:S-42:pkg:npm/lodash@4.17.21:CVE-2021-23337 \
+  --format json --output explains/lodash.json
+```
+
+Outputs ordered rule hits, inputs, and sealed-mode hints.
+
+---
+
+## 6 · Exit Codes Summary
+
+| Exit code | Description | Typical ERR codes |
+|-----------|-------------|-------------------|
+| `0` | Success (command completed, warnings only). | — |
+| `10` | DSL syntax/compile failure. | `ERR_POL_001` |
+| `11` | Unsupported DSL version / schema mismatch. | `ERR_POL_001` |
+| `12` | Approval/rbac failure. | `ERR_POL_002`, `ERR_POL_005` |
+| `20` | Simulation diff exceeded thresholds (`--fail-on-diff`). | — |
+| `21` | Required inputs missing (SBOM/advisory/VEX). | `ERR_POL_003` |
+| `22` | Determinism guard triggered. | `ERR_POL_004` |
+| `23` | Run canceled or timed out. | `ERR_POL_006` |
+| `30` | Network/transport error (non-HTTP success). | — |
+| `64` | CLI usage error (invalid flag/argument). | — |
+
+All non-zero exits emit structured error envelope on stderr when `--format json` or `STELLA_JSON_ERRORS=1`.
+
+---
+
+## 7 · Offline & Air-Gap Usage
+
+- Use `--sealed` to ensure commands avoid outbound calls; required for sealed enclaves.
+- `stella policy bundle export --policy P-7 --version 4 --output bundles/policy-P-7-v4.bundle` pairs with Offline Kit import.
+- Replay bundles (`run replay`) are DSSE-signed; verify with `stella offline verify`.
+- Store credentials in `~/.stella/offline.toml` for non-interactive air-gapped pipelines.
+
+---
+
+## 8 · Compliance Checklist
+
+- [ ] **Help text synced:** `stella policy --help` matches documented flags/examples (update during release pipeline).
+- [ ] **Exit codes mapped:** Table above reflects CLI implementation and CI asserts mapping for `ERR_POL_*`.
+- [ ] **JSON schemas verified:** Example payloads validated against OpenAPI/SDK contracts before publishing.
+- [ ] **Scope guidance present:** Each command lists required Authority scopes.
+- [ ] **Offline guidance included:** Sealed-mode steps and bundle workflows documented.
+- [ ] **Cross-links tested:** Links to DSL, lifecycle, runs, and API docs resolve locally (`yarn docs:lint`).
+- [ ] **Examples no-op safe:** Command examples either read-only or use placeholders (no destructive defaults).
+
+---
+
+*Last updated: 2025-10-26 (Sprint 20).*