up

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

@@ -0,0 +1,183 @@
+# stella api — Command Guide
+
+## Overview
+
+The `stella api` command group provides API management capabilities including specification download and listing.
+
+## Commands
+
+### List API Specifications (CLI-SDK-63-001)
+
+```bash
+# List available API specifications
+stella api spec list \
+  [--tenant <id>] \
+  [--json]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--tenant` / `-t` | Tenant context for the operation |
+| `--json` | Output in JSON format |
+
+**Output:**
+- Aggregate API specification details (version, OpenAPI version, ETag, SHA-256)
+- Service-level specifications with version and format information
+
+### Download API Specification (CLI-SDK-63-001)
+
+```bash
+# Download API specification
+stella api spec download \
+  --output <path> \
+  [--tenant <id>] \
+  [--service <name>] \
+  [--format openapi-json|openapi-yaml] \
+  [--overwrite] \
+  [--etag <etag>] \
+  [--checksum <checksum>] \
+  [--checksum-algorithm sha256|sha384|sha512] \
+  [--json]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--output` / `-o` | Output path for the downloaded spec (file or directory) (required) |
+| `--service` / `-s` | Service to download spec for (e.g., concelier, scanner, policy). Omit for aggregate spec |
+| `--format` / `-f` | Output format: `openapi-json` (default) or `openapi-yaml` |
+| `--overwrite` | Overwrite existing file if present |
+| `--etag` | Expected ETag for conditional download (If-None-Match) |
+| `--checksum` | Expected checksum for verification after download |
+| `--checksum-algorithm` | Checksum algorithm: `sha256` (default), `sha384`, `sha512` |
+
+**Output:**
+- Downloaded file path
+- File size
+- API version (extracted from spec)
+- ETag for future conditional downloads
+- Checksum with verification status
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Error or download failure |
+| 130 | Operation cancelled by user |
+
+## JSON Schema: ApiSpecDownloadResult
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "success": { "type": "boolean" },
+    "path": { "type": "string" },
+    "sizeBytes": { "type": "integer" },
+    "fromCache": { "type": "boolean" },
+    "etag": { "type": "string" },
+    "checksum": { "type": "string" },
+    "checksumAlgorithm": { "type": "string" },
+    "checksumVerified": { "type": "boolean" },
+    "apiVersion": { "type": "string" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "error": { "type": "string" },
+    "errorCode": { "type": "string" }
+  }
+}
+```
+
+## Examples
+
+### List available API specifications
+
+```bash
+# List all specs
+stella api spec list
+
+# List specs as JSON
+stella api spec list --json
+```
+
+### Download aggregate specification
+
+```bash
+# Download aggregate OpenAPI spec to current directory
+stella api spec download --output ./
+
+# Download with checksum verification
+stella api spec download \
+  --output ./stellaops-api.json \
+  --checksum abc123def456... \
+  --checksum-algorithm sha256
+```
+
+### Download service-specific specification
+
+```bash
+# Download Scanner API spec
+stella api spec download \
+  --output ./scanner-api.yaml \
+  --service scanner \
+  --format openapi-yaml
+```
+
+### Conditional download with ETag
+
+```bash
+# First download captures ETag
+stella api spec download --output ./api.json --json > download-result.json
+
+# Subsequent downloads use ETag for cache validation
+ETAG=$(jq -r '.etag' download-result.json)
+stella api spec download \
+  --output ./api.json \
+  --etag "$ETAG"
+```
+
+### CI/CD Integration
+
+```bash
+#!/bin/bash
+# Download and validate API spec in CI
+
+stella api spec download \
+  --output ./openapi.json \
+  --checksum "$EXPECTED_CHECKSUM" \
+  --json > result.json
+
+if [ "$(jq -r '.checksumVerified' result.json)" != "true" ]; then
+  echo "API spec checksum verification failed!"
+  exit 1
+fi
+
+# Generate client code from spec
+npx openapi-generator-cli generate \
+  -i ./openapi.json \
+  -g typescript-fetch \
+  -o ./generated-client
+```
+
+## Available Services
+
+| Service | Description |
+|---------|-------------|
+| `aggregate` | Combined specification from all services (default) |
+| `concelier` | Vulnerability advisory and VEX management |
+| `scanner` | Container scanning and SBOM generation |
+| `policy` | Policy engine and evaluation |
+| `authority` | Authentication and authorization |
+| `attestor` | Attestation generation and verification |
+| `notify` | Notification delivery |
+| `scheduler` | Job scheduling |
+
+## Best Practices
+
+1. **Use ETag for conditional downloads** to minimize bandwidth and improve CI performance
+2. **Verify checksums** when downloading specs for code generation in production pipelines
+3. **Download aggregate spec** for general client generation; service-specific specs for targeted APIs
+4. **Store ETags** in CI cache to enable incremental downloads
+5. **Use YAML format** for human readability; JSON for programmatic processing

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

@@ -1,25 +1,332 @@
 # stella policy — Command Guide
 
+## Overview
+
+The `stella policy` command group provides comprehensive policy management capabilities for Policy Studio, including creation, simulation, workflow management, and lifecycle operations.
+
 ## Commands
-- `stella policy eval --input <bundle> --subject <sbom|vex|vuln> [--offline] [--output json|ndjson|table]`
-- `stella policy simulate --from <bundleA> --to <bundleB> [--budget <ms>] [--offline]`
-- `stella policy publish --input <bundle> --sign --attest`
 
-## Flags (common)
-- `--offline` / `STELLA_OFFLINE=1`: forbid network calls; use cached bundles only.
-- `--tenant <id>`: scope evaluation to tenant; RLS enforcement required on the server.
-- `--rationale`: include rationale IDs in responses.
-- `--output`: `json` (default), `ndjson`, or `table`.
+### Policy Creation & Scaffolding
 
-## Inputs/outputs
-- Inputs: policy bundles (signed), subject artifacts (SBOM/VEX/Vuln snapshots).
-- Outputs: deterministic JSON/NDJSON or tables; includes `correlationId`, `policyVersion`, `rationaleIds` when requested.
-- Exit codes follow `output-and-exit-codes.md`.
+```bash
+# Create a new policy from a template
+stella policy new <name> [--template <template>] [--output <path>] [--description <desc>] [--tags <tag1,tag2>] [--shadow-mode] [--create-fixtures] [--git-init]
+```
 
-## Determinism rules
-- Sort evaluation results by subject key; timestamps UTC ISO-8601.
-- No inferred verdicts beyond Policy Engine response.
+**Templates:** `basic`, `sbom-gate`, `vex-precedence`, `reachability`, `secret-detection`, `license-compliance`, `supply-chain`
 
-## Offline/air-gap notes
-- When `--offline`, evaluation must use locally cached bundles and subject artifacts; fail with exit code 5 if network would be needed.
-- Trust roots loaded from `STELLA_TRUST_ROOTS` when verifying signed bundles.
+### Policy Simulation (CLI-POLICY-27-003)
+
+```bash
+# Simulate policy changes with enhanced options
+stella policy simulate <policy-id> \
+  [--base <version>] \
+  [--candidate <version>] \
+  [--sbom <id1,id2,...>] \
+  [--env key=value] \
+  [--mode quick|batch] \
+  [--sbom-selector <pattern>] \
+  [--heatmap] \
+  [--manifest-download] \
+  [--reachability-state <id:state>] \
+  [--reachability-score <id:score>] \
+  [--with-exception <exc-id>] \
+  [--without-exception <exc-id>] \
+  [--explain] \
+  [--fail-on-diff] \
+  [--format json|table|markdown] \
+  [--output <path>]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--mode quick\|batch` | Simulation mode: `quick` samples SBOMs, `batch` evaluates all matching |
+| `--sbom-selector` | SBOM selector pattern (e.g., `registry:docker.io/*`, `tag:production`). Repeatable |
+| `--heatmap` | Include severity heatmap summary in output |
+| `--manifest-download` | Request manifest download URI for offline analysis |
+| `--reachability-state` | Override reachability state (format: `CVE-XXXX:reachable`). Repeatable |
+| `--reachability-score` | Override reachability score (format: `CVE-XXXX:0.85`). Repeatable |
+| `--format markdown` | Generate CI-friendly markdown report |
+
+### Policy Workflow (CLI-POLICY-27-002)
+
+```bash
+# Bump policy version
+stella policy version bump <policy-id> [--changelog <message>] [--major|--minor|--patch]
+
+# Submit policy for review
+stella policy submit <policy-id> [--version <ver>] [--reviewers <user1,user2>] [--changelog <message>]
+
+# Add review comment
+stella policy review comment <policy-id> [--version <ver>] --comment <text> [--line <num>] [--file <path>]
+
+# Approve policy review
+stella policy approve <policy-id> [--version <ver>] [--comment <text>]
+
+# Reject policy review
+stella policy reject <policy-id> [--version <ver>] --reason <text>
+
+# Get review status
+stella policy review status <policy-id> [--version <ver>]
+```
+
+### Policy Lifecycle (CLI-POLICY-27-004)
+
+```bash
+# Publish policy
+stella policy publish <policy-id> [--version <ver>] [--sign] [--attestation-type <type>] [--dry-run]
+
+# Promote policy to environment
+stella policy promote <policy-id> [--version <ver>] --env <environment> [--canary <percentage>] [--dry-run]
+
+# Rollback policy
+stella policy rollback <policy-id> [--to-version <ver>] [--reason <text>] [--force]
+
+# Sign policy
+stella policy sign <policy-id> [--version <ver>] [--key-id <key>] [--attestation-type <type>]
+
+# Verify policy signature
+stella policy verify-signature <policy-id> [--version <ver>] [--check-rekor]
+```
+
+### Policy History & Explain (CLI-POLICY-23-006)
+
+```bash
+# Get policy history
+stella policy history <policy-id> [--limit <num>] [--since <date>] [--until <date>]
+
+# Explain policy decision
+stella policy explain <policy-id> [--version <ver>] [--finding-id <id>] [--verbose]
+```
+
+### Policy Activation
+
+```bash
+# Activate an approved policy revision
+stella policy activate <policy-id> --version <ver> [--environment <env>] [--force] [--dry-run]
+```
+
+## Common Flags
+
+| Flag | Description |
+|------|-------------|
+| `--tenant` / `-t` | Tenant context for the operation |
+| `--json` | Output as JSON |
+| `--verbose` / `-v` | Enable verbose logging |
+| `--offline` | Forbid network calls; use cached bundles only |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 4 | Input validation error |
+| 5 | Network required but offline mode enabled |
+| 20 | Differences detected with `--fail-on-diff` |
+| 130 | Operation cancelled by user |
+
+## JSON Schemas
+
+### PolicySimulationResult
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "diff": {
+      "type": "object",
+      "properties": {
+        "schemaVersion": { "type": "string" },
+        "added": { "type": "integer" },
+        "removed": { "type": "integer" },
+        "unchanged": { "type": "integer" },
+        "bySeverity": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "up": { "type": "integer" },
+              "down": { "type": "integer" }
+            }
+          }
+        },
+        "ruleHits": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "ruleId": { "type": "string" },
+              "ruleName": { "type": "string" },
+              "up": { "type": "integer" },
+              "down": { "type": "integer" }
+            }
+          }
+        }
+      }
+    },
+    "explainUri": { "type": "string" },
+    "heatmap": {
+      "type": "object",
+      "properties": {
+        "buckets": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "severity": { "type": "string" },
+              "count": { "type": "integer" },
+              "percentage": { "type": "number" }
+            }
+          }
+        },
+        "total": { "type": "integer" }
+      }
+    },
+    "manifestDownloadUri": { "type": "string" },
+    "manifestDigest": { "type": "string" }
+  }
+}
+```
+
+### PolicyReviewSummary
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "policyId": { "type": "string" },
+    "version": { "type": "integer" },
+    "status": { "type": "string", "enum": ["pending", "approved", "rejected", "changes_requested"] },
+    "submittedBy": { "type": "string" },
+    "submittedAt": { "type": "string", "format": "date-time" },
+    "reviewers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "userId": { "type": "string" },
+          "status": { "type": "string" },
+          "reviewedAt": { "type": "string", "format": "date-time" }
+        }
+      }
+    },
+    "comments": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "commentId": { "type": "string" },
+          "author": { "type": "string" },
+          "text": { "type": "string" },
+          "createdAt": { "type": "string", "format": "date-time" },
+          "line": { "type": "integer" },
+          "file": { "type": "string" }
+        }
+      }
+    }
+  }
+}
+```
+
+## CI/CD Integration Examples
+
+### GitHub Actions
+
+```yaml
+name: Policy Simulation
+on:
+  pull_request:
+    paths:
+      - 'policies/**'
+
+jobs:
+  simulate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Stella CLI
+        run: |
+          curl -sSL https://get.stellaops.io | bash
+
+      - name: Simulate Policy Changes
+        run: |
+          stella policy simulate P-7 \
+            --base $(git merge-base HEAD origin/main) \
+            --candidate HEAD \
+            --mode batch \
+            --heatmap \
+            --format markdown \
+            --output simulation-report.md \
+            --fail-on-diff
+
+      - name: Upload Report
+        uses: actions/upload-artifact@v4
+        with:
+          name: policy-simulation-report
+          path: simulation-report.md
+```
+
+### GitLab CI
+
+```yaml
+policy-simulate:
+  stage: test
+  script:
+    - stella policy simulate P-7 --mode quick --heatmap --json > simulation.json
+    - |
+      if [ $(jq '.diff.added + .diff.removed' simulation.json) -gt 0 ]; then
+        echo "Policy changes detected"
+        stella policy simulate P-7 --format markdown --output report.md
+        exit 20
+      fi
+  artifacts:
+    paths:
+      - simulation.json
+      - report.md
+    when: always
+```
+
+### Azure DevOps
+
+```yaml
+- task: Bash@3
+  displayName: 'Policy Simulation'
+  inputs:
+    targetType: 'inline'
+    script: |
+      stella policy simulate P-7 \
+        --mode batch \
+        --sbom-selector "registry:$(ACR_REGISTRY)/*" \
+        --heatmap \
+        --json \
+        --output $(Build.ArtifactStagingDirectory)/simulation.json
+```
+
+## Determinism Rules
+
+- Sort evaluation results by subject key
+- Timestamps use UTC ISO-8601 format
+- No inferred verdicts beyond Policy Engine response
+- Hashes computed with SHA-256
+
+## Offline/Air-Gap Notes
+
+- When `--offline` is set, evaluation uses locally cached bundles and subject artifacts
+- Fails with exit code 5 if network would be needed
+- Trust roots loaded from `STELLA_TRUST_ROOTS` environment variable when verifying signed bundles
+- Signature verification can use local Rekor mirror via `STELLA_REKOR_MIRROR`
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `STELLAOPS_BACKEND_URL` | Backend API URL |
+| `STELLA_OFFLINE` | Set to `1` to enable offline mode |
+| `STELLA_TRUST_ROOTS` | Path to trust roots for signature verification |
+| `STELLA_REKOR_MIRROR` | Local Rekor transparency log mirror URL |
+| `STELLAOPS_TENANT` | Default tenant context |

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

@@ -0,0 +1,265 @@
+# stella reachability — Command Guide
+
+## Overview
+
+The `stella reachability` command group provides reachability analysis capabilities for vulnerability exploitability assessment. It supports call graph upload, analysis listing, and detailed reachability explanations.
+
+## Commands
+
+### Upload Call Graph (CLI-SIG-26-001)
+
+```bash
+# Upload a call graph for reachability analysis
+stella reachability upload-callgraph \
+  --path <call-graph-file> \
+  [--tenant <id>] \
+  [--scan-id <id>] \
+  [--asset-id <id>] \
+  [--format auto|json|proto|dot] \
+  [--json]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--path` / `-p` | Path to the call graph file (required) |
+| `--scan-id` | Scan identifier to associate with the call graph |
+| `--asset-id` / `-a` | Asset identifier to associate with the call graph |
+| `--format` / `-f` | Call graph format: `auto` (default), `json`, `proto`, `dot` |
+
+**Required:** At least one of `--scan-id` or `--asset-id`.
+
+**Supported Call Graph Formats:**
+- JSON (native format)
+- Protocol Buffers (proto)
+- DOT/GraphViz format
+
+### List Reachability Analyses (CLI-SIG-26-001)
+
+```bash
+# List reachability analyses
+stella reachability list \
+  [--tenant <id>] \
+  [--scan-id <id>] \
+  [--asset-id <id>] \
+  [--status pending|processing|completed|failed] \
+  [--limit <num>] \
+  [--offset <num>] \
+  [--json]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--scan-id` | Filter by scan identifier |
+| `--asset-id` / `-a` | Filter by asset identifier |
+| `--status` | Filter by analysis status |
+| `--limit` / `-l` | Maximum number of results (default 100) |
+| `--offset` / `-o` | Pagination offset |
+
+**Output Columns:**
+- Analysis ID
+- Asset name/ID
+- Status (pending, processing, completed, failed)
+- Reachable count
+- Unreachable count
+- Unknown count
+- Created timestamp
+
+### Explain Reachability (CLI-SIG-26-001)
+
+```bash
+# Explain reachability for a vulnerability or package
+stella reachability explain \
+  --analysis-id <id> \
+  [--tenant <id>] \
+  [--vuln-id <cve-id>] \
+  [--purl <package-url>] \
+  [--call-paths] \
+  [--json]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--analysis-id` / `-i` | Analysis identifier (required) |
+| `--vuln-id` / `-v` | Vulnerability identifier to explain |
+| `--purl` | Package URL to explain |
+| `--call-paths` | Include detailed call paths in the explanation |
+
+**Required:** At least one of `--vuln-id` or `--purl`.
+
+**Output:**
+- Reachability state (reachable, unreachable, unknown)
+- Reachability score (0-1)
+- Confidence level
+- Reasoning explanation
+- Affected functions list
+- Call paths (when `--call-paths` is used)
+
+## Integration with Policy Simulation (CLI-SIG-26-002)
+
+Reachability overrides can be applied during policy simulation:
+
+```bash
+stella policy simulate P-7 \
+  --reachability-state "CVE-2024-1234:unreachable" \
+  --reachability-state "pkg:npm/lodash@4.17.0:reachable" \
+  --reachability-score "CVE-2024-5678:0.25"
+```
+
+**Override Format:**
+- State: `<identifier>:<state>` where state is `reachable`, `unreachable`, `unknown`, or `indeterminate`
+- Score: `<identifier>:<score>` where score is a decimal between 0 and 1
+
+**Identifier Types:**
+- Vulnerability ID: `CVE-XXXX-XXXX`, `GHSA-xxxx-xxxx-xxxx`
+- Package URL: `pkg:npm/package@version`, `pkg:maven/group/artifact@version`
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Error or upload failure |
+| 4 | Input validation error |
+| 130 | Operation cancelled by user |
+
+## JSON Schema: ReachabilityExplainResult
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "analysisId": { "type": "string" },
+    "vulnerabilityId": { "type": "string" },
+    "packagePurl": { "type": "string" },
+    "reachabilityState": {
+      "type": "string",
+      "enum": ["reachable", "unreachable", "unknown", "indeterminate"]
+    },
+    "reachabilityScore": { "type": "number", "minimum": 0, "maximum": 1 },
+    "confidence": { "type": "string" },
+    "reasoning": { "type": "string" },
+    "callPaths": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "pathId": { "type": "string" },
+          "depth": { "type": "integer" },
+          "entryPoint": { "$ref": "#/$defs/function" },
+          "frames": { "type": "array", "items": { "$ref": "#/$defs/function" } },
+          "vulnerableFunction": { "$ref": "#/$defs/function" }
+        }
+      }
+    },
+    "affectedFunctions": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/function" }
+    }
+  },
+  "$defs": {
+    "function": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "signature": { "type": "string" },
+        "className": { "type": "string" },
+        "packageName": { "type": "string" },
+        "filePath": { "type": "string" },
+        "lineNumber": { "type": "integer" }
+      }
+    }
+  }
+}
+```
+
+## Examples
+
+### Upload a call graph
+
+```bash
+# Upload call graph for a specific scan
+stella reachability upload-callgraph \
+  --path ./callgraph.json \
+  --scan-id scan-12345 \
+  --format json
+
+# Upload with auto-detection
+stella reachability upload-callgraph \
+  --path ./app-callgraph.dot \
+  --asset-id my-application
+```
+
+### List recent analyses
+
+```bash
+# List all completed analyses for an asset
+stella reachability list \
+  --asset-id my-application \
+  --status completed \
+  --json
+
+# List analyses with pagination
+stella reachability list \
+  --limit 20 \
+  --offset 40
+```
+
+### Explain vulnerability reachability
+
+```bash
+# Explain with call paths
+stella reachability explain \
+  --analysis-id RA-abc123 \
+  --vuln-id CVE-2024-1234 \
+  --call-paths
+
+# Explain package reachability
+stella reachability explain \
+  --analysis-id RA-abc123 \
+  --purl "pkg:npm/lodash@4.17.21" \
+  --json
+```
+
+### Policy simulation with reachability overrides
+
+```bash
+# Mark specific vulnerability as unreachable
+stella policy simulate P-7 \
+  --reachability-state "CVE-2024-1234:unreachable" \
+  --explain
+
+# Set low reachability score
+stella policy simulate P-7 \
+  --reachability-score "pkg:npm/axios@0.21.0:0.1"
+```
+
+## Reachability States
+
+| State | Description |
+|-------|-------------|
+| `reachable` | Vulnerable code is reachable from application entry points |
+| `unreachable` | Vulnerable code cannot be reached during execution |
+| `unknown` | Reachability cannot be determined with available information |
+| `indeterminate` | Analysis inconclusive due to dynamic dispatch or reflection |
+
+## Call Graph Generation
+
+Call graphs can be generated using various tools:
+
+- **Java:** [WALA](https://github.com/wala/WALA), [Soot](https://github.com/soot-oss/soot)
+- **JavaScript/Node.js:** [callgraph](https://www.npmjs.com/package/callgraph)
+- **Python:** [pycg](https://github.com/vitsalis/pycg)
+- **Go:** `go build -gcflags="-m"` + static analysis
+- **C/C++:** [LLVM](https://llvm.org/) call graph pass
+
+## Best Practices
+
+1. **Upload call graphs after each build** to maintain accurate reachability data
+2. **Use asset IDs** for long-lived applications to track reachability changes over time
+3. **Include call paths** when debugging unexpected reachability results
+4. **Apply reachability overrides** in policy simulation to model remediation scenarios
+5. **Monitor unreachable counts** as a metric for dependency hygiene

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

@@ -0,0 +1,248 @@
+# stella risk — Command Guide
+
+## Overview
+
+The `stella risk` command group provides risk profile management, risk scoring simulation, and risk bundle verification capabilities.
+
+## Commands
+
+### Risk Profile Management (CLI-RISK-66-001)
+
+```bash
+# List risk profiles
+stella risk profile list \
+  [--tenant <id>] \
+  [--include-disabled] \
+  [--category <category>] \
+  [--limit <num>] \
+  [--offset <num>] \
+  [--json]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--include-disabled` | Include disabled profiles in listing |
+| `--category` | Filter by profile category |
+| `--limit` | Maximum number of results (default 100) |
+| `--offset` | Pagination offset |
+
+**Output Columns:**
+- Profile ID
+- Name
+- Category
+- Version
+- Rules count
+- Enabled status
+- Built-in indicator
+
+### Risk Simulation (CLI-RISK-66-002)
+
+```bash
+# Simulate risk scoring
+stella risk simulate \
+  [--tenant <id>] \
+  [--profile-id <id>] \
+  [--sbom-id <id>] \
+  [--sbom-path <path>] \
+  [--asset-id <id>] \
+  [--diff] \
+  [--baseline-profile-id <id>] \
+  [--json] \
+  [--csv] \
+  [--output <path>]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--profile-id` | Risk profile to use for simulation |
+| `--sbom-id` | SBOM identifier for risk evaluation |
+| `--sbom-path` | Local path to SBOM file |
+| `--asset-id` | Asset identifier for risk evaluation |
+| `--diff` | Enable diff mode to compare with baseline |
+| `--baseline-profile-id` | Baseline profile for diff comparison |
+
+**Required:** At least one of `--sbom-id`, `--sbom-path`, or `--asset-id`.
+
+**Output:**
+- Overall score and grade (A+ to F)
+- Findings summary by severity (critical, high, medium, low, info)
+- Component-level scores
+- Diff information when `--diff` is enabled
+
+### Risk Results (CLI-RISK-67-001)
+
+```bash
+# Get risk evaluation results
+stella risk results \
+  [--tenant <id>] \
+  [--asset-id <id>] \
+  [--sbom-id <id>] \
+  [--profile-id <id>] \
+  [--min-severity <severity>] \
+  [--max-score <score>] \
+  [--explain] \
+  [--limit <num>] \
+  [--offset <num>] \
+  [--json] \
+  [--csv]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--min-severity` | Minimum severity threshold (critical, high, medium, low, info) |
+| `--max-score` | Maximum score threshold (0-100) |
+| `--explain` | Include explainability information |
+
+**Output:**
+- Summary statistics (average, min, max score, asset count)
+- Results table with score, grade, severity, finding count
+- Explanation factors and recommendations when `--explain` is used
+
+### Risk Bundle Verification (CLI-RISK-68-001)
+
+```bash
+# Verify a risk bundle
+stella risk bundle verify \
+  [--tenant <id>] \
+  --bundle-path <path> \
+  [--signature-path <path>] \
+  [--check-rekor] \
+  [--json]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--bundle-path` | Path to the risk bundle file (required) |
+| `--signature-path` | Path to detached signature file |
+| `--check-rekor` | Verify transparency log entry in Sigstore Rekor |
+
+**Output:**
+- Bundle validation status (VALID/INVALID)
+- Bundle information (ID, version, profile count, rule count)
+- Signature verification status
+- Rekor transparency log verification status
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success (for verify: bundle is valid) |
+| 1 | Error or invalid bundle |
+| 4 | Input validation error |
+| 130 | Operation cancelled by user |
+
+## JSON Schema: RiskSimulateResult
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "success": { "type": "boolean" },
+    "profileId": { "type": "string" },
+    "profileName": { "type": "string" },
+    "overallScore": { "type": "number" },
+    "grade": { "type": "string" },
+    "findings": {
+      "type": "object",
+      "properties": {
+        "critical": { "type": "integer" },
+        "high": { "type": "integer" },
+        "medium": { "type": "integer" },
+        "low": { "type": "integer" },
+        "info": { "type": "integer" },
+        "total": { "type": "integer" }
+      }
+    },
+    "componentScores": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "componentId": { "type": "string" },
+          "componentName": { "type": "string" },
+          "score": { "type": "number" },
+          "grade": { "type": "string" },
+          "findingCount": { "type": "integer" }
+        }
+      }
+    },
+    "diff": {
+      "type": "object",
+      "properties": {
+        "baselineScore": { "type": "number" },
+        "candidateScore": { "type": "number" },
+        "delta": { "type": "number" },
+        "improved": { "type": "boolean" },
+        "findingsAdded": { "type": "integer" },
+        "findingsRemoved": { "type": "integer" }
+      }
+    },
+    "simulatedAt": { "type": "string", "format": "date-time" },
+    "errors": { "type": "array", "items": { "type": "string" } }
+  }
+}
+```
+
+## Examples
+
+### List all enabled risk profiles
+
+```bash
+stella risk profile list --json
+```
+
+### Simulate risk for a local SBOM
+
+```bash
+stella risk simulate \
+  --sbom-path ./my-sbom.json \
+  --profile-id RP-security-baseline \
+  --json
+```
+
+### Compare risk between profiles
+
+```bash
+stella risk simulate \
+  --asset-id my-app \
+  --profile-id RP-strict \
+  --diff \
+  --baseline-profile-id RP-permissive
+```
+
+### Get high-severity results with explanations
+
+```bash
+stella risk results \
+  --asset-id my-app \
+  --min-severity high \
+  --explain
+```
+
+### Verify a signed risk bundle
+
+```bash
+stella risk bundle verify \
+  --bundle-path ./risk-bundle.tar.gz \
+  --signature-path ./risk-bundle.sig \
+  --check-rekor
+```
+
+## Risk Grading Scale
+
+| Grade | Score Range | Description |
+|-------|-------------|-------------|
+| A+ | 95-100 | Excellent |
+| A | 90-94 | Very Good |
+| B+ | 85-89 | Good |
+| B | 80-84 | Above Average |
+| C+ | 75-79 | Average |
+| C | 70-74 | Below Average |
+| D+ | 65-69 | Poor |
+| D | 60-64 | Very Poor |
+| F | 0-59 | Failing |

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

@@ -0,0 +1,249 @@
+# stella sdk — Command Guide
+
+## Overview
+
+The `stella sdk` command group provides SDK management capabilities including update checking, changelog viewing, and deprecation notices.
+
+## Commands
+
+### Check for SDK Updates (CLI-SDK-64-001)
+
+```bash
+# Check for SDK updates
+stella sdk update \
+  [--tenant <id>] \
+  [--language <lang>] \
+  [--check-only] \
+  [--changelog] \
+  [--deprecations] \
+  [--json]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--tenant` / `-t` | Tenant context for the operation |
+| `--language` / `-l` | SDK language filter (typescript, go, csharp, python, java). Omit for all |
+| `--check-only` | Only check for updates, don't download |
+| `--changelog` | Show changelog for available updates |
+| `--deprecations` | Show deprecation notices |
+| `--json` | Output in JSON format |
+
+**Output:**
+- Available SDK updates with version comparison
+- Changelog entries for each update (when `--changelog` is used)
+- Deprecation notices with migration guidance (when `--deprecations` is used)
+
+### List Installed SDKs (CLI-SDK-64-001)
+
+```bash
+# List installed SDK versions
+stella sdk list \
+  [--tenant <id>] \
+  [--language <lang>] \
+  [--json]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--tenant` / `-t` | Tenant context for the operation |
+| `--language` / `-l` | SDK language filter |
+| `--json` | Output in JSON format |
+
+**Output:**
+- Language/platform
+- Package name
+- Installed version
+- Latest available version
+- API version compatibility range
+- Update status
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Error |
+| 130 | Operation cancelled by user |
+
+## JSON Schema: SdkUpdateResponse
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "success": { "type": "boolean" },
+    "updates": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "language": { "type": "string" },
+          "displayName": { "type": "string" },
+          "packageName": { "type": "string" },
+          "installedVersion": { "type": "string" },
+          "latestVersion": { "type": "string" },
+          "updateAvailable": { "type": "boolean" },
+          "minApiVersion": { "type": "string" },
+          "maxApiVersion": { "type": "string" },
+          "releaseDate": { "type": "string", "format": "date-time" },
+          "changelog": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "version": { "type": "string" },
+                "releaseDate": { "type": "string", "format": "date-time" },
+                "type": { "type": "string" },
+                "description": { "type": "string" },
+                "isBreaking": { "type": "boolean" },
+                "link": { "type": "string" }
+              }
+            }
+          },
+          "downloadUrl": { "type": "string" },
+          "registryUrl": { "type": "string" },
+          "docsUrl": { "type": "string" }
+        }
+      }
+    },
+    "deprecations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "language": { "type": "string" },
+          "feature": { "type": "string" },
+          "message": { "type": "string" },
+          "deprecatedInVersion": { "type": "string" },
+          "removedInVersion": { "type": "string" },
+          "replacement": { "type": "string" },
+          "migrationGuide": { "type": "string" },
+          "severity": { "type": "string", "enum": ["info", "warning", "critical"] }
+        }
+      }
+    },
+    "checkedAt": { "type": "string", "format": "date-time" },
+    "error": { "type": "string" }
+  }
+}
+```
+
+## Examples
+
+### Check for all SDK updates
+
+```bash
+# Check all SDKs
+stella sdk update
+
+# Check with changelog
+stella sdk update --changelog
+
+# Check with deprecation notices
+stella sdk update --deprecations
+
+# Full check with all details
+stella sdk update --changelog --deprecations
+```
+
+### Check specific language SDK
+
+```bash
+# Check TypeScript SDK only
+stella sdk update --language typescript
+
+# Check Go SDK with changelog
+stella sdk update --language go --changelog
+```
+
+### List installed SDKs
+
+```bash
+# List all installed SDKs
+stella sdk list
+
+# List specific language
+stella sdk list --language python
+
+# Output as JSON for CI
+stella sdk list --json
+```
+
+### CI/CD Integration
+
+```bash
+#!/bin/bash
+# Check for SDK updates in CI and fail on breaking changes
+
+stella sdk update --changelog --json > sdk-updates.json
+
+# Check for breaking changes
+BREAKING=$(jq '[.updates[].changelog[]? | select(.isBreaking == true)] | length' sdk-updates.json)
+if [ "$BREAKING" -gt 0 ]; then
+  echo "WARNING: $BREAKING breaking changes detected in available SDK updates"
+  jq '.updates[].changelog[] | select(.isBreaking == true)' sdk-updates.json
+fi
+
+# Check for critical deprecations
+CRITICAL=$(jq '[.deprecations[] | select(.severity == "critical")] | length' sdk-updates.json)
+if [ "$CRITICAL" -gt 0 ]; then
+  echo "ERROR: $CRITICAL critical deprecations require immediate attention"
+  jq '.deprecations[] | select(.severity == "critical")' sdk-updates.json
+  exit 1
+fi
+```
+
+### Automated notification script
+
+```bash
+#!/bin/bash
+# Send Slack notification when SDK updates are available
+
+UPDATES=$(stella sdk update --json)
+UPDATE_COUNT=$(echo "$UPDATES" | jq '[.updates[] | select(.updateAvailable == true)] | length')
+
+if [ "$UPDATE_COUNT" -gt 0 ]; then
+  curl -X POST -H 'Content-type: application/json' \
+    --data "{\"text\": \"StellaOps SDK Updates Available: $UPDATE_COUNT updates\"}" \
+    "$SLACK_WEBHOOK_URL"
+fi
+```
+
+## Supported SDKs
+
+| Language | Package Name | Registry |
+|----------|-------------|----------|
+| TypeScript | `@stellaops/sdk` | npm |
+| Go | `github.com/stellaops/sdk-go` | Go modules |
+| C# | `StellaOps.Sdk` | NuGet |
+| Python | `stellaops-sdk` | PyPI |
+| Java | `com.stellaops:sdk` | Maven Central |
+
+## Changelog Entry Types
+
+| Type | Icon | Description |
+|------|------|-------------|
+| `feature` | + | New feature or capability |
+| `fix` | ~ | Bug fix |
+| `breaking` | ! | Breaking change (major version) |
+| `deprecation` | ? | Deprecation notice |
+
+## Deprecation Severity Levels
+
+| Severity | Description |
+|----------|-------------|
+| `info` | Informational notice, no immediate action required |
+| `warning` | Feature will be removed in future version, plan migration |
+| `critical` | Feature removed or will be removed imminently, immediate action required |
+
+## Best Practices
+
+1. **Check for updates regularly** in CI to stay informed about new SDK versions
+2. **Review changelogs** before upgrading to understand new features and breaking changes
+3. **Monitor deprecations** to plan migrations before features are removed
+4. **Use `--check-only`** in automated pipelines to avoid unintended downloads
+5. **Filter by language** when working on specific platform integrations
+6. **Integrate with notifications** to alert teams about available updates