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.
This commit is contained in:
master
284
docs/cli/cli-reference.md
Normal file
284
docs/cli/cli-reference.md
Normal file
@@ -0,0 +1,284 @@
|
||||
# CLI AOC Commands Reference
|
||||
|
||||
> **Audience:** DevEx engineers, operators, and CI authors integrating the `stella` CLI with Aggregation-Only Contract (AOC) workflows.
|
||||
> **Scope:** Command synopsis, options, exit codes, and offline considerations for `stella sources ingest --dry-run` and `stella aoc verify` as introduced in Sprint 19.
|
||||
|
||||
Both commands are designed to enforce the AOC guardrails documented in the [aggregation-only reference](../ingestion/aggregation-only-contract.md) and the [architecture overview](../architecture/overview.md). They consume Authority-issued tokens with tenant scopes and never mutate ingestion stores.
|
||||
|
||||
---
|
||||
|
||||
## 1 · Prerequisites
|
||||
|
||||
- CLI version: `stella` ≥ 0.19.0 (AOC feature gate enabled).
|
||||
- Required scopes (DPoP-bound):
|
||||
- `advisory:verify` for Concelier sources.
|
||||
- `vex:verify` for Excititor sources (optional but required for VEX checks).
|
||||
- `tenant:select` if your deployment uses tenant switching.
|
||||
- Connectivity: direct access to Concelier/Excititor APIs or Offline Kit snapshot (see § 4).
|
||||
- Environment: set `STELLA_AUTHORITY_URL`, `STELLA_TENANT`, and export a valid OpTok via `stella auth login` or existing token cache.
|
||||
|
||||
---
|
||||
|
||||
## 2 · `stella sources ingest --dry-run`
|
||||
|
||||
### 2.1 Synopsis
|
||||
|
||||
```bash
|
||||
stella sources ingest --dry-run \
|
||||
--source <source-key> \
|
||||
--input <path-or-uri> \
|
||||
[--tenant <tenant-id>] \
|
||||
[--format json|table] \
|
||||
[--no-color] \
|
||||
[--output <file>]
|
||||
```
|
||||
|
||||
### 2.2 Description
|
||||
|
||||
Previews an ingestion write without touching MongoDB. The command loads an upstream advisory or VEX document, computes the would-write payload, runs it through the `AOCWriteGuard`, and reports any forbidden fields, provenance gaps, or idempotency issues. Use it during connector development, CI validation, or while triaging incidents.
|
||||
|
||||
### 2.3 Options
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--source <source-key>` | Logical source name (`redhat`, `ubuntu`, `osv`, etc.). Mirrors connector configuration. |
|
||||
| `--input <path-or-uri>` | Path to local CSAF/OSV/VEX file or HTTPS URI. CLI normalises transport (gzip/base64) before guard evaluation. |
|
||||
| `--tenant <tenant-id>` | Overrides default tenant for multi-tenant deployments. Mandatory when `STELLA_TENANT` is not set. |
|
||||
| `--format json|table` | Output format. `table` (default) prints summary with highlighted violations; `json` emits machine-readable report (see below). |
|
||||
| `--no-color` | Disables ANSI colour output for CI logs. |
|
||||
| `--output <file>` | Writes the JSON report to file while still printing human-readable summary to stdout. |
|
||||
|
||||
### 2.4 Output schema (JSON)
|
||||
|
||||
```json
|
||||
{
|
||||
"source": "redhat",
|
||||
"tenant": "default",
|
||||
"guardVersion": "1.0.0",
|
||||
"status": "ok",
|
||||
"document": {
|
||||
"contentHash": "sha256:…",
|
||||
"supersedes": null,
|
||||
"provenance": {
|
||||
"signature": { "format": "pgp", "present": true }
|
||||
}
|
||||
},
|
||||
"violations": []
|
||||
}
|
||||
```
|
||||
|
||||
When violations exist, `status` becomes `error` and `violations` contains entries with `code` (`ERR_AOC_00x`), a short `message`, and JSON Pointer `path` values indicating offending fields.
|
||||
|
||||
### 2.5 Exit codes
|
||||
|
||||
| Exit code | Meaning |
|
||||
|-----------|---------|
|
||||
| `0` | Guard passed; would-write payload is AOC compliant. |
|
||||
| `11` | `ERR_AOC_001` – Forbidden field (`severity`, `cvss`, etc.) detected. |
|
||||
| `12` | `ERR_AOC_002` – Merge attempt (multiple upstream sources fused). |
|
||||
| `13` | `ERR_AOC_003` – Idempotency violation (duplicate without supersedes). |
|
||||
| `14` | `ERR_AOC_004` – Missing provenance fields. |
|
||||
| `15` | `ERR_AOC_005` – Signature/checksum mismatch. |
|
||||
| `16` | `ERR_AOC_006` – Effective findings present (Policy-only data). |
|
||||
| `17` | `ERR_AOC_007` – Unknown top-level fields / schema violation. |
|
||||
| `70` | Transport error (network, auth, malformed input). |
|
||||
|
||||
> Exit codes map directly to the `ERR_AOC_00x` table for scripting consistency. Multiple violations yield the highest-priority code (e.g., 11 takes precedence over 14).
|
||||
|
||||
### 2.6 Examples
|
||||
|
||||
Dry-run a local CSAF file:
|
||||
|
||||
```bash
|
||||
stella sources ingest --dry-run \
|
||||
--source redhat \
|
||||
--input ./fixtures/redhat/RHSA-2025-1234.json
|
||||
```
|
||||
|
||||
Stream from HTTPS and emit JSON for CI:
|
||||
|
||||
```bash
|
||||
stella sources ingest --dry-run \
|
||||
--source osv \
|
||||
--input https://osv.dev/vulnerability/GHSA-aaaa-bbbb \
|
||||
--format json \
|
||||
--output artifacts/osv-dry-run.json
|
||||
|
||||
cat artifacts/osv-dry-run.json | jq '.violations'
|
||||
```
|
||||
|
||||
### 2.7 Offline notes
|
||||
|
||||
When operating in sealed/offline mode:
|
||||
|
||||
- Use `--input` paths pointing to Offline Kit snapshots (`offline-kit/advisories/*.json`).
|
||||
- Provide `--tenant` explicitly if the offline bundle contains multiple tenants.
|
||||
- The command does not attempt network access when given a file path.
|
||||
- Store reports with `--output` to include in transfer packages for policy review.
|
||||
|
||||
---
|
||||
|
||||
## 3 · `stella aoc verify`
|
||||
|
||||
### 3.1 Synopsis
|
||||
|
||||
```bash
|
||||
stella aoc verify \
|
||||
[--since <iso8601|duration>] \
|
||||
[--limit <count>] \
|
||||
[--sources <list>] \
|
||||
[--codes <ERR_AOC_00x,...>] \
|
||||
[--format table|json] \
|
||||
[--export <file>] \
|
||||
[--tenant <tenant-id>] \
|
||||
[--no-color]
|
||||
```
|
||||
|
||||
### 3.2 Description
|
||||
|
||||
Replays the AOC guard against stored raw documents. By default it checks all advisories and VEX statements ingested in the last 24 hours for the active tenant, reporting totals, top violation codes, and sample documents. Use it in CI pipelines, scheduled verifications, or during incident response.
|
||||
|
||||
### 3.3 Options
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--since <value>` | Verification window. Accepts ISO 8601 timestamp (`2025-10-25T12:00:00Z`) or duration (`48h`, `7d`). Defaults to `24h`. |
|
||||
| `--limit <count>` | Maximum number of violations to display (per code). `0` means show all. Defaults to `20`. |
|
||||
| `--sources <list>` | Comma-separated list of sources (`redhat,ubuntu,osv`). Filters both advisories and VEX entries. |
|
||||
| `--codes <list>` | Restricts output to specific `ERR_AOC_00x` codes. Useful for regression tracking. |
|
||||
| `--format table|json` | `table` (default) prints summary plus top violations; `json` outputs machine-readable report identical to the `/aoc/verify` API. |
|
||||
| `--export <file>` | Writes the JSON report to disk (useful for audits/offline uploads). |
|
||||
| `--tenant <tenant-id>` | Overrides tenant context. Required for cross-tenant verifications when run by platform operators. |
|
||||
| `--no-color` | Disables ANSI colours. |
|
||||
|
||||
### 3.4 Report structure (JSON)
|
||||
|
||||
```json
|
||||
{
|
||||
"tenant": "default",
|
||||
"window": {
|
||||
"from": "2025-10-25T12:00:00Z",
|
||||
"to": "2025-10-26T12:00:00Z"
|
||||
},
|
||||
"checked": {
|
||||
"advisories": 482,
|
||||
"vex": 75
|
||||
},
|
||||
"violations": [
|
||||
{
|
||||
"code": "ERR_AOC_001",
|
||||
"count": 2,
|
||||
"examples": [
|
||||
{
|
||||
"source": "redhat",
|
||||
"documentId": "advisory_raw:redhat:RHSA-2025:1",
|
||||
"contentHash": "sha256:…",
|
||||
"path": "/content/raw/cvss"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"metrics": {
|
||||
"ingestion_write_total": 557,
|
||||
"aoc_violation_total": 2
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.5 Exit codes
|
||||
|
||||
| Exit code | Meaning |
|
||||
|-----------|---------|
|
||||
| `0` | Verification succeeded with zero violations. |
|
||||
| `11…17` | Same mapping as § 2.5 when violations are detected. Highest-priority code returned. |
|
||||
| `18` | Verification ran but results truncated (limit reached) – treat as warning; rerun with higher `--limit`. |
|
||||
| `70` | Transport/authentication error. |
|
||||
| `71` | CLI misconfiguration (missing tenant, invalid `--since`, etc.). |
|
||||
|
||||
### 3.6 Examples
|
||||
|
||||
Daily verification across all sources:
|
||||
|
||||
```bash
|
||||
stella aoc verify --since 24h --format table
|
||||
```
|
||||
|
||||
CI pipeline focusing on errant sources and exporting evidence:
|
||||
|
||||
```bash
|
||||
stella aoc verify \
|
||||
--sources redhat,ubuntu \
|
||||
--codes ERR_AOC_001,ERR_AOC_004 \
|
||||
--format json \
|
||||
--limit 100 \
|
||||
--export artifacts/aoc-verify.json
|
||||
|
||||
jq '.violations[] | {code, count}' artifacts/aoc-verify.json
|
||||
```
|
||||
|
||||
Air-gapped verification using Offline Kit snapshot (example script):
|
||||
|
||||
```bash
|
||||
stella aoc verify \
|
||||
--since 7d \
|
||||
--format json \
|
||||
--export /mnt/offline/aoc-verify-$(date +%F).json
|
||||
|
||||
sha256sum /mnt/offline/aoc-verify-*.json > /mnt/offline/checksums.txt
|
||||
```
|
||||
|
||||
### 3.7 Automation tips
|
||||
|
||||
- Schedule with `cron` or platform scheduler and fail the job when exit code ≥ 11.
|
||||
- Pair with `stella sources ingest --dry-run` for pre-flight validation before re-enabling a paused source.
|
||||
- Push JSON exports to observability pipelines for historical tracking of violation counts.
|
||||
|
||||
### 3.8 Offline notes
|
||||
|
||||
- Works against Offline Kit Mongo snapshots when CLI is pointed at the local API gateway included in the bundle.
|
||||
- When fully disconnected, run against exported `aoc verify` reports generated on production and replay them using `--format json --export` (automation recipe above).
|
||||
- Include verification output in compliance packages alongside Offline Kit manifests.
|
||||
|
||||
---
|
||||
|
||||
## 4 · Global exit-code reference
|
||||
|
||||
| Code | Summary |
|
||||
|------|---------|
|
||||
| `0` | Success / no violations. |
|
||||
| `11` | `ERR_AOC_001` – Forbidden field present. |
|
||||
| `12` | `ERR_AOC_002` – Merge attempt detected. |
|
||||
| `13` | `ERR_AOC_003` – Idempotency violation. |
|
||||
| `14` | `ERR_AOC_004` – Missing provenance/signature metadata. |
|
||||
| `15` | `ERR_AOC_005` – Signature/checksum mismatch. |
|
||||
| `16` | `ERR_AOC_006` – Effective findings in ingestion payload. |
|
||||
| `17` | `ERR_AOC_007` – Schema violation / unknown fields. |
|
||||
| `18` | Partial verification (limit reached). |
|
||||
| `70` | Transport or HTTP failure. |
|
||||
| `71` | CLI usage error (invalid arguments, missing tenant). |
|
||||
|
||||
Use these codes in CI to map outcomes to build statuses or alert severities.
|
||||
|
||||
---
|
||||
|
||||
## 5 · Related references
|
||||
|
||||
- [Aggregation-Only Contract reference](../ingestion/aggregation-only-contract.md)
|
||||
- [Architecture overview](../architecture/overview.md)
|
||||
- [Console AOC dashboard](../ui/console.md)
|
||||
- [Authority scopes](../ARCHITECTURE_AUTHORITY.md)
|
||||
|
||||
---
|
||||
|
||||
## 6 · Compliance checklist
|
||||
|
||||
- [ ] Usage documented for both table and JSON formats.
|
||||
- [ ] Exit-code mapping matches `ERR_AOC_00x` definitions and automation guidance.
|
||||
- [ ] Offline/air-gap workflow captured for both commands.
|
||||
- [ ] References to AOC architecture and console docs included.
|
||||
- [ ] Examples validated against current CLI syntax (update post-implementation).
|
||||
- [ ] Docs guild screenshot/narrative placeholder logged for release notes (pending CLI team capture).
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26 (Sprint 19).*
|
||||
284
docs/cli/policy.md
Normal file
284
docs/cli/policy.md
Normal file
@@ -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).*
|
||||
Reference in New Issue
Block a user