docs consolidation

docs/modules/cli/guides/commands/vuln.md

@@ -1,25 +1,206 @@
-# stella vuln — Command Guide
+# stella vuln - Command Guide
+
+## Overview
+
+The `stella vuln` command group is the operator surface for vulnerability triage workflows:
+- Query and inspect vulnerabilities (`list`, `show`)
+- Retrieve raw advisory observations for overlay consumers (`observations`)
+- Apply workflow actions (assign, comment, accept risk, verify fix, target fix, reopen)
+- Simulate policy/VEX changes (`simulate`)
+- Export offline evidence bundles and verify them (`export`, `export verify`)
+
+Unless otherwise noted, commands support formatted output by default and `--json` for automation-friendly output.
 
 ## Commands
-- `stella vuln list --query <filter> [--group-by <field>] [--output json|ndjson|table] [--offline]`
-- `stella vuln get --id <vulnId> [--output json|table] [--offline]`
-- `stella vuln simulate --from <policyA> --to <policyB> --subjects <path> [--offline]`
 
-## Flags (common)
-- `--offline`: read from cached snapshots; fail with exit code 5 if network would be used.
-- `--policy <id>`: scope queries to a policy projection.
-- `--page-size`, `--page-token`: deterministic pagination.
-- `--group-by`: `cve`, `package`, `status`, `advisory` (results stay stably ordered within groups).
+### observations
 
-## Inputs/outputs
-- Inputs: Vuln Explorer API; optional cached snapshots when offline.
-- Outputs: sorted lists or detail documents with provenance pointers (`advisoryId`, `evidenceIds`, `consensusId`).
-- Exit codes follow `output-and-exit-codes.md`; 4 for not found, 5 for offline violation.
+List raw advisory observations (useful for overlay consumers).
 
-## Determinism rules
-- Lists sorted by primary key then timestamp; group-by keeps stable ordering inside each bucket.
-- Timestamps UTC ISO-8601; hashes lower-case hex.
+```bash
+stella vuln observations \
+  --tenant acme \
+  --alias CVE-2024-1234 \
+  --limit 50 \
+  --json
+```
 
-## Offline/air-gap notes
-- Use cached snapshots (`--offline`) when remote Explorer is unavailable; commands must not attempt network calls in this mode.
-- Simulation must read local policy snapshots and subjects when offline.
+Options:
+
+| Flag | Description |
+| --- | --- |
+| `--tenant` | Tenant identifier (required). |
+| `--observation-id` | Filter by observation id (repeatable). |
+| `--alias` | Filter by vulnerability alias (repeatable). |
+| `--purl` | Filter by Package URL (repeatable). |
+| `--cpe` | Filter by CPE value (repeatable). |
+| `--limit` | Max items (default 200, max 500). |
+| `--cursor` | Opaque cursor token from a previous page. |
+| `--json` | Emit raw JSON payload instead of a table. |
+
+### list
+
+List vulnerabilities with filters, grouping, and pagination.
+
+```bash
+stella vuln list \
+  --severity high \
+  --status open \
+  --group-by package \
+  --limit 50
+```
+
+Options:
+
+| Flag | Description |
+| --- | --- |
+| `--vuln-id` | Filter by vulnerability identifier (e.g., `CVE-2024-1234`). |
+| `--severity` | Filter by severity (`critical`, `high`, `medium`, `low`). |
+| `--status` | Filter by status (`open`, `triaged`, `accepted`, `fixed`, etc.). |
+| `--purl` | Filter by Package URL. |
+| `--cpe` | Filter by CPE value. |
+| `--sbom-id` | Filter by SBOM identifier. |
+| `--policy-id` | Filter by policy identifier. |
+| `--policy-version` | Filter by policy version. |
+| `--group-by` | Group by (`vuln`, `package`, `severity`, `status`). |
+| `--limit` | Max items (default 50, max 500). |
+| `--offset` | Offset paging (skip N). |
+| `--cursor` | Opaque cursor token from a previous page. |
+| `--tenant` | Tenant identifier (overrides profile/environment). |
+| `--json` | Emit raw JSON payload instead of a table. |
+| `--csv` | Emit CSV instead of a table. |
+
+### show
+
+Show details for a specific vulnerability id.
+
+```bash
+stella vuln show CVE-2024-1234 --json
+```
+
+Options:
+
+| Flag | Description |
+| --- | --- |
+| `--tenant` | Tenant identifier (overrides profile/environment). |
+| `--json` | Emit raw JSON payload instead of formatted output. |
+
+### Workflow commands
+
+Workflow commands operate on either:
+- Explicit selection: repeat `--vuln-id <id>`
+- Filtered selection: `--filter-*` options
+
+Shared options:
+
+| Flag | Description |
+| --- | --- |
+| `--vuln-id` | Vulnerability ids to operate on (repeatable). |
+| `--filter-severity` | Filter by severity (`critical`, `high`, `medium`, `low`). |
+| `--filter-status` | Filter by current status. |
+| `--filter-purl` | Filter by Package URL. |
+| `--filter-sbom` | Filter by SBOM id. |
+| `--tenant` | Tenant identifier (overrides profile/environment). |
+| `--idempotency-key` | Idempotency key for retry-safe operations. |
+| `--json` | Emit raw JSON response. |
+
+Commands:
+
+```bash
+# Assign selected vulns to an assignee
+stella vuln assign alice@example.com --vuln-id CVE-2024-1234
+
+# Add a comment
+stella vuln comment "triage started" --vuln-id CVE-2024-1234
+
+# Accept risk with optional due date (ISO-8601)
+stella vuln accept-risk "risk accepted for legacy system" \
+  --due-date 2026-12-31 \
+  --vuln-id CVE-2024-1234
+
+# Mark as fixed and verified
+stella vuln verify-fix \
+  --fix-version 1.2.3 \
+  --comment "patched in release 1.2.3" \
+  --vuln-id CVE-2024-1234
+
+# Set a target fix date
+stella vuln target-fix 2026-12-31 \
+  --comment "scheduled in next maintenance window" \
+  --vuln-id CVE-2024-1234
+
+# Reopen a previously closed/accepted vuln
+stella vuln reopen --comment "regression observed" --vuln-id CVE-2024-1234
+```
+
+### simulate
+
+Simulate policy/VEX changes and show delta summaries.
+
+```bash
+stella vuln simulate \
+  --policy-id policy://tenant-default/runtime-hardening \
+  --policy-version 7 \
+  --vex-override "CVE-2024-1234=not_affected" \
+  --severity-threshold high \
+  --sbom-id sbom-001 \
+  --markdown \
+  --output ./vuln-sim-report.md
+```
+
+Options:
+
+| Flag | Description |
+| --- | --- |
+| `--policy-id` | Policy id to simulate (uses different version or a new policy). |
+| `--policy-version` | Policy version to simulate against. |
+| `--vex-override` | VEX status overrides (`vulnId=status`, repeatable). |
+| `--severity-threshold` | Threshold (`critical`, `high`, `medium`, `low`). |
+| `--sbom-id` | SBOM ids to include (repeatable). |
+| `--markdown` | Include Markdown report suitable for CI pipelines. |
+| `--changed-only` | Only show items that changed. |
+| `--tenant` | Tenant identifier for multi-tenant environments. |
+| `--json` | Output JSON for automation. |
+| `--output` | Write Markdown report to file instead of stdout. |
+
+### export
+
+Export vulnerability evidence bundles (optionally signed) for offline review and audit workflows.
+
+```bash
+stella vuln export \
+  --vuln-id CVE-2024-1234 \
+  --format ndjson \
+  --output ./vuln-export.ndjson
+```
+
+Options:
+
+| Flag | Description |
+| --- | --- |
+| `--vuln-id` | Vulnerability ids to include (repeatable). |
+| `--sbom-id` | SBOM ids to include (repeatable). |
+| `--policy-id` | Policy id for export filtering. |
+| `--format` | `ndjson` (default) or `json`. |
+| `--include-evidence` | Include evidence data (default: true). |
+| `--include-ledger` | Include workflow ledger (default: true). |
+| `--signed` | Request signed export bundle (default: true). |
+| `--output` | Output file path for the export bundle (required). |
+| `--tenant` | Tenant identifier for multi-tenant environments. |
+
+### export verify
+
+Verify signature and digest of an exported vulnerability bundle.
+
+```bash
+stella vuln export verify ./vuln-export.ndjson \
+  --expected-digest sha256:deadbeef... \
+  --public-key ./authority-public.pem
+```
+
+Options:
+
+| Flag | Description |
+| --- | --- |
+| `--expected-digest` | Expected digest to verify (`sha256:<hex>`). |
+| `--public-key` | Public key path for signature verification. |