feat(docs): Add comprehensive documentation for Vexer, Vulnerability Explorer, and Zastava modules
- Introduced AGENTS.md, README.md, TASKS.md, and implementation_plan.md for Vexer, detailing mission, responsibilities, key components, and operational notes. - Established similar documentation structure for Vulnerability Explorer and Zastava modules, including their respective workflows, integrations, and observability notes. - Created risk scoring profiles documentation outlining the core workflow, factor model, governance, and deliverables. - Ensured all modules adhere to the Aggregation-Only Contract and maintain determinism and provenance in outputs.
This commit is contained in:
318
docs/modules/cli/guides/policy.md
Normal file
318
docs/modules/cli/guides/policy.md
Normal file
@@ -0,0 +1,318 @@
|
||||
# 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`).
|
||||
> **2025-10-27 scope update:** CLI/CI tokens issued prior to Sprint 23 (AUTH-POLICY-23-001) must drop `policy:write`/`policy:submit`/`policy:edit` and instead request `policy:read`, `policy:author`, `policy:review`, and `policy:simulate` (plus `policy:approve`/`policy:operate`/`policy:activate` for promotion pipelines).
|
||||
|
||||
---
|
||||
|
||||
## 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`.
|
||||
|
||||
**Options**
|
||||
|
||||
- `--version <number>` (required) – target revision to promote.
|
||||
- `--note <text>` – record an activation note alongside the approval.
|
||||
- `--run-now` – enqueue an immediate full run after activation.
|
||||
- `--scheduled-at <timestamp>` – schedule activation for a specific UTC time (ISO-8601 format).
|
||||
- `--priority <label>` – optional scheduling priority hint (`low`, `standard`, `high`).
|
||||
- `--rollback` – mark the activation as a rollback of a previously active version.
|
||||
- `--incident <id>` – associate the activation with an incident identifier.
|
||||
|
||||
**Exit codes**
|
||||
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| `0` | Activation completed (or policy already active). |
|
||||
| `75` | Activation recorded but awaiting a second approver. |
|
||||
|
||||
### 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/Scheduler/__Libraries/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.
|
||||
|
||||
### 4.4 Schema artefacts for CLI validation
|
||||
|
||||
- CI publishes canonical JSON Schema exports for `PolicyRunRequest`, `PolicyRunStatus`, `PolicyDiffSummary`, and `PolicyExplainTrace` as the `policy-schema-exports` artifact (see `.gitea/workflows/build-test-deploy.yml`).
|
||||
- Each run writes the files to `artifacts/policy-schemas/<commit>/` and stores a unified diff (`policy-schema-diff.patch`) comparing them with the tracked baseline in `docs/schemas/`.
|
||||
- Schema changes trigger an alert in Slack `#policy-engine` via the `POLICY_ENGINE_SCHEMA_WEBHOOK` secret so CLI maintainers know to refresh fixtures or validation rules.
|
||||
- Consume these artefacts in CLI tests to keep payload validation aligned without committing generated files into the repo.
|
||||
|
||||
---
|
||||
|
||||
## 5 · Findings & Explainability
|
||||
|
||||
### 5.1 List Findings
|
||||
|
||||
```
|
||||
stella findings ls --policy P-7 \
|
||||
--sbom sbom:S-42 \
|
||||
--status affected --severity High,Critical \
|
||||
--since 2025-10-01T00:00:00Z \
|
||||
--page 2 --page-size 100 \
|
||||
--format table
|
||||
```
|
||||
|
||||
Common flags:
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--sbom` | Repeatable filter for SBOM identifiers. |
|
||||
| `--status` | Repeatable filter (`affected`, `quieted`, `mitigated`, `not_affected`, etc.). |
|
||||
| `--severity` | Repeatable filter using normalized labels (`Critical`, `High`, `Medium`, `Low`, `Unknown`). |
|
||||
| `--since` | Return findings updated on/after the ISO-8601 timestamp. |
|
||||
| `--cursor` | Resume listing using the opaque token from a prior page. |
|
||||
| `--page`, `--page-size` | Page-based pagination (page >=1, size <=500; falls back to backend defaults). |
|
||||
| `--output` | Persist JSON payload to disk (implied JSON rendering). |
|
||||
| `--format` | `table` (default for TTY) or `json`. |
|
||||
|
||||
### 5.2 Fetch Explain
|
||||
|
||||
```
|
||||
stella findings explain --policy P-7 \
|
||||
P-7:S-42:pkg:npm/lodash@4.17.21:CVE-2021-23337 \
|
||||
--mode verbose \
|
||||
--format json --output explains/lodash.json
|
||||
```
|
||||
|
||||
Outputs ordered rule hits, inputs, evidence snapshots, and sealed-mode hints. Supported `--mode` values mirror API contracts (for example `summary`, `verbose`); omit to use backend default.
|
||||
|
||||
---
|
||||
|
||||
## 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. (_CI now exports canonical schemas as `policy-schema-exports`; wire tests to consume them._)
|
||||
- [ ] **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-27 (Sprint 20).*
|
||||
Reference in New Issue
Block a user