diff --git a/docs/implplan/SPRINT_0115_0001_0004_concelier_iv.md b/docs/implplan/SPRINT_0115_0001_0004_concelier_iv.md index 9f0a8ca6d..a3a5a3396 100644 --- a/docs/implplan/SPRINT_0115_0001_0004_concelier_iv.md +++ b/docs/implplan/SPRINT_0115_0001_0004_concelier_iv.md @@ -30,10 +30,10 @@ | 3 | CONCELIER-POLICY-23-001 | DONE (2025-11-28) | Implemented migration `20251128_policy_lookup_indexes` with alias multikey, confidence, and severity indexes. Query patterns documented in migration XML docs. | Concelier Core Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Secondary indexes/materialized views (alias, provider severity, confidence) to keep policy lookups fast without cached verdicts; document query patterns. | | 4 | CONCELIER-POLICY-23-002 | DONE (2025-11-28) | Enhanced `AdvisoryLinksetUpdatedEvent` with `IdempotencyKey` (SHA256), `ConfidenceSummary` (tier/factors), and `TenantMetadata`. | Concelier Core Guild · Platform Events Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Ensure `advisory.linkset.updated` events carry idempotent IDs, confidence summaries, tenant metadata for safe policy replay. | | 5 | CONCELIER-RISK-66-001 | DONE (2025-11-28) | Created `VendorRiskSignal`, `VendorCvssScore`, `VendorKevStatus`, `VendorFixAvailability` models with provenance. Extractor parses OSV/NVD formats. | Concelier Core Guild · Risk Engine Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Surface vendor-provided CVSS/KEV/fix data exactly as published with provenance anchors via provider APIs. | -| 6 | CONCELIER-RISK-66-002 | TODO | Upstream 66-001 DONE. Ready to emit fix-availability metadata. | Concelier Core Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Emit structured fix-availability metadata per observation/linkset (release version, advisory link, evidence timestamp) without guessing exploitability. | -| 7 | CONCELIER-RISK-67-001 | TODO | Upstream 66-001 DONE. Ready to publish coverage/conflict metrics. | Concelier Core Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Publish per-source coverage/conflict metrics (counts, disagreements) so explainers cite which upstream statements exist; no weighting applied. | +| 6 | CONCELIER-RISK-66-002 | DONE (2025-11-28) | Implemented `FixAvailabilityMetadata`, `FixRelease`, `FixAdvisoryLink` models + `IFixAvailabilityEmitter` interface + `FixAvailabilityEmitter` implementation in `src/Concelier/__Libraries/StellaOps.Concelier.Core/Risk/`. DI registration via `AddConcelierRiskServices()`. | Concelier Core Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Emit structured fix-availability metadata per observation/linkset (release version, advisory link, evidence timestamp) without guessing exploitability. | +| 7 | CONCELIER-RISK-67-001 | DONE (2025-11-28) | Implemented `SourceCoverageMetrics`, `SourceContribution`, `SourceConflict` models + `ISourceCoverageMetricsPublisher` interface + `SourceCoverageMetricsPublisher` implementation + `InMemorySourceCoverageMetricsStore` in `src/Concelier/__Libraries/StellaOps.Concelier.Core/Risk/`. DI registration via `AddConcelierRiskServices()`. | Concelier Core Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Publish per-source coverage/conflict metrics (counts, disagreements) so explainers cite which upstream statements exist; no weighting applied. | | 8 | CONCELIER-RISK-68-001 | BLOCKED | Blocked on POLICY-RISK-68-001. | Concelier Core Guild · Policy Studio Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Wire advisory signal pickers into Policy Studio; validate selected fields are provenance-backed. | -| 9 | CONCELIER-RISK-69-001 | BLOCKED | Blocked on 66-002. | Concelier Core Guild · Notifications Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Emit notifications on upstream advisory field changes (e.g., fix availability) with observation IDs + provenance; no severity inference. | +| 9 | CONCELIER-RISK-69-001 | DONE (2025-11-28) | Implemented `AdvisoryFieldChangeNotification`, `AdvisoryFieldChange` models + `IAdvisoryFieldChangeEmitter` interface + `AdvisoryFieldChangeEmitter` implementation + `InMemoryAdvisoryFieldChangeNotificationPublisher` in `src/Concelier/__Libraries/StellaOps.Concelier.Core/Risk/`. Detects fix availability, KEV status, severity changes with provenance. | Concelier Core Guild · Notifications Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Emit notifications on upstream advisory field changes (e.g., fix availability) with observation IDs + provenance; no severity inference. | | 10 | CONCELIER-SIG-26-001 | BLOCKED | Blocked on SIGNALS-24-002. | Concelier Core Guild · Signals Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Expose upstream-provided affected symbol/function lists via APIs for reachability scoring; maintain provenance, no exploitability inference. | | 11 | CONCELIER-STORE-AOC-19-005-DEV | BLOCKED (2025-11-04) | Waiting on staging dataset hash + rollback rehearsal using prep doc | Concelier Storage Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Storage.Mongo`) | Execute raw-linkset backfill/rollback plan so Mongo reflects Link-Not-Merge data; rehearse rollback (dev/staging). | | 12 | CONCELIER-TEN-48-001 | DONE (2025-11-28) | Created Tenancy module with `TenantScope`, `TenantCapabilities`, `TenantCapabilitiesResponse`, `ITenantCapabilitiesProvider`, and `TenantScopeNormalizer` per AUTH-TEN-47-001. | Concelier Core Guild (`src/Concelier/__Libraries/StellaOps.Concelier.Core`) | Enforce tenant scoping through normalization/linking; expose capability endpoint advertising `merge=false`; ensure events include tenant IDs. | @@ -42,6 +42,9 @@ ## Execution Log | Date (UTC) | Update | Owner | | --- | --- | --- | +| 2025-11-28 | Completed CONCELIER-RISK-69-001: implemented `AdvisoryFieldChangeNotification`, `AdvisoryFieldChange`, `AdvisoryFieldChangeProvenance` models + `IAdvisoryFieldChangeEmitter` interface + `AdvisoryFieldChangeEmitter` implementation + `IAdvisoryFieldChangeNotificationPublisher` interface + `InMemoryAdvisoryFieldChangeNotificationPublisher`. Detects changes in fix availability, KEV status, severity, CVSS score, and observation status with full provenance. DI registration via `AddConcelierRiskServices()`. Sprint 0115 RISK tasks now complete (66-001, 66-002, 67-001, 69-001 DONE; 68-001 BLOCKED on POLICY-RISK-68-001). | Implementer | +| 2025-11-28 | Completed CONCELIER-RISK-66-002: implemented `FixAvailabilityMetadata`, `FixRelease`, `FixAdvisoryLink` models with provenance anchors + `IFixAvailabilityEmitter` interface + `FixAvailabilityEmitter` implementation for emitting structured fix-availability metadata per observation/linkset. DI registration via `AddConcelierRiskServices()`. Unblocked CONCELIER-RISK-69-001. | Implementer | +| 2025-11-28 | Completed CONCELIER-RISK-67-001: implemented `SourceCoverageMetrics`, `SourceContribution`, `SourceCoverageDetail`, `SourceAgreementSummary`, `SourceConflict` models + `ISourceCoverageMetricsPublisher` interface + `SourceCoverageMetricsPublisher` implementation + `InMemorySourceCoverageMetricsStore` for per-source coverage/conflict metrics. No weighting applied; fact-only counts and disagreements. DI registration via `AddConcelierRiskServices()`. | Implementer | | 2025-11-28 | Completed CONCELIER-TEN-48-001: created Tenancy module with `TenantScope`, `TenantCapabilities`, `TenantCapabilitiesResponse`, `ITenantCapabilitiesProvider`, `LinkNotMergeTenantCapabilitiesProvider`, and `TenantScopeNormalizer`. Implements AUTH-TEN-47-001 contract with capabilities endpoint response and tenant ID normalization. Build green. | Implementer | | 2025-11-28 | Completed CONCELIER-RISK-66-001: created Risk module with `VendorRiskSignal`, `VendorCvssScore`, `VendorKevStatus`, `VendorFixAvailability` models + `IVendorRiskSignalProvider` interface + `VendorRiskSignalExtractor` for OSV/NVD parsing. All with provenance anchors. Build green. Tasks 6 and 7 now TODO. | Implementer | | 2025-11-28 | Unblocked CONCELIER-RISK-66-001 and CONCELIER-TEN-48-001 after POLICY chain completion. Tasks 5 and 12 moved to TODO. | Implementer | diff --git a/docs/implplan/SPRINT_0190_0001_0001_cvss_v4_receipts.md b/docs/implplan/SPRINT_0190_0001_0001_cvss_v4_receipts.md index 5179aa45e..bf2c1359f 100644 --- a/docs/implplan/SPRINT_0190_0001_0001_cvss_v4_receipts.md +++ b/docs/implplan/SPRINT_0190_0001_0001_cvss_v4_receipts.md @@ -24,9 +24,9 @@ ## Delivery Tracker | # | Task ID | Status | Key dependency / next step | Owners | Task Definition | | --- | --- | --- | --- | --- | --- | -| 1 | CVSS-MODEL-190-001 | TODO | None; foundational. | Policy Guild · Signals Guild (`src/Policy/StellaOps.Policy.Scoring`) | Design and implement CVSS v4.0 data model: `CvssScoreReceipt`, `BaseMetrics`, `ThreatMetrics`, `EnvironmentalMetrics`, `SupplementalMetrics`, `EvidenceItem`, `CvssPolicy`, `ReceiptHistoryEntry`. Include EF Core mappings and MongoDB schema. | -| 2 | CVSS-ENGINE-190-002 | TODO | Depends on 190-001 for types. | Policy Guild (`src/Policy/StellaOps.Policy.Scoring/Engine`) | Implement `CvssV4Engine` with: `ParseVector()`, `ComputeBaseScore()`, `ComputeThreatAdjustedScore()`, `ComputeEnvironmentalAdjustedScore()`, `BuildVector()`. Follow FIRST spec v4.0 exactly for math/rounding. | -| 3 | CVSS-TESTS-190-003 | TODO | Depends on 190-002. | Policy Guild · QA Guild (`src/Policy/__Tests/StellaOps.Policy.Scoring.Tests`) | Unit tests for CVSS v4.0 engine using official FIRST sample vectors; edge cases for missing threat/env; determinism tests (same input → same output). | +| 1 | CVSS-MODEL-190-001 | DONE (2025-11-28) | None; foundational. | Policy Guild · Signals Guild (`src/Policy/StellaOps.Policy.Scoring`) | Design and implement CVSS v4.0 data model: `CvssScoreReceipt`, `BaseMetrics`, `ThreatMetrics`, `EnvironmentalMetrics`, `SupplementalMetrics`, `EvidenceItem`, `CvssPolicy`, `ReceiptHistoryEntry`. Include EF Core mappings and MongoDB schema. Evidence: Created `StellaOps.Policy.Scoring` project with `CvssMetrics.cs` (all CVSS v4.0 metric enums/records), `CvssScoreReceipt.cs` (receipt model with scores, evidence, history), `CvssPolicy.cs` (policy configuration), JSON schemas `cvss-policy-schema@1.json` and `cvss-receipt-schema@1.json`, and `AGENTS.md`. | +| 2 | CVSS-ENGINE-190-002 | DONE (2025-11-28) | Depends on 190-001 for types. | Policy Guild (`src/Policy/StellaOps.Policy.Scoring/Engine`) | Implement `CvssV4Engine` with: `ParseVector()`, `ComputeBaseScore()`, `ComputeThreatAdjustedScore()`, `ComputeEnvironmentalAdjustedScore()`, `BuildVector()`. Follow FIRST spec v4.0 exactly for math/rounding. Evidence: `ICvssV4Engine.cs` interface, `CvssV4Engine.cs` implementation with MacroVector computation (EQ1-EQ6), threat/environmental modifiers, vector string building/parsing, `MacroVectorLookup.cs` with score tables. | +| 3 | CVSS-TESTS-190-003 | DONE (2025-11-28) | Depends on 190-002. | Policy Guild · QA Guild (`src/Policy/__Tests/StellaOps.Policy.Scoring.Tests`) | Unit tests for CVSS v4.0 engine using official FIRST sample vectors; edge cases for missing threat/env; determinism tests (same input → same output). Evidence: Created `StellaOps.Policy.Scoring.Tests` project with `CvssV4EngineTests.cs` containing tests for base/threat/environmental/full scores, vector string building/parsing, severity thresholds, determinism, and FIRST sample vectors. | | 4 | CVSS-POLICY-190-004 | TODO | Depends on 190-002. | Policy Guild (`src/Policy/StellaOps.Policy.Scoring/Policies`) | Implement `CvssPolicy` loader and validator: JSON schema for policy files, policy versioning, hash computation for determinism tracking. | | 5 | CVSS-RECEIPT-190-005 | TODO | Depends on 190-002, 190-004. | Policy Guild (`src/Policy/StellaOps.Policy.Scoring/Receipts`) | Implement `ReceiptBuilder` service: `CreateReceipt(vulnId, input, policyId, userId)` that computes scores, builds vector, hashes inputs, and persists receipt with evidence links. | | 6 | CVSS-DSSE-190-006 | TODO | Depends on 190-005; uses Attestor primitives. | Policy Guild · Attestor Guild (`src/Policy/StellaOps.Policy.Scoring`, `src/Attestor/StellaOps.Attestor.Envelope`) | Attach DSSE attestations to score receipts: create `stella.ops/cvssReceipt@v1` predicate type, sign receipts, store envelope references. | @@ -72,3 +72,7 @@ | Date (UTC) | Update | Owner | | --- | --- | --- | | 2025-11-27 | Sprint created from product advisory `25-Nov-2025 - Add CVSS v4.0 Score Receipts for Transparency.md`; 12 tasks defined across 4 waves. | Product Mgmt | +| 2025-11-28 | CVSS-MODEL-190-001 DONE: Created `StellaOps.Policy.Scoring` project with complete CVSS v4.0 data model per FIRST spec. Includes `CvssMetrics.cs` (Base/Threat/Environmental/Supplemental metrics with all enum values), `CvssScoreReceipt.cs` (receipt with scores, evidence, history, DSSE refs), `CvssPolicy.cs` (policy configuration with overrides, thresholds, attestation requirements), JSON schemas for validation, and `AGENTS.md`. | Implementer | +| 2025-11-28 | Started CVSS-ENGINE-190-002: Implementing scoring engine with MacroVector lookup tables per FIRST CVSS v4.0 specification. | Implementer | +| 2025-11-28 | CVSS-ENGINE-190-002 DONE: Implemented `ICvssV4Engine` interface and `CvssV4Engine` class with full scoring logic. EQ1-EQ6 equivalence class computation, MacroVector lookup table with score interpolation, threat/environmental score modifiers, round-up per FIRST spec, vector string building/parsing with regex. Started CVSS-TESTS-190-003. | Implementer | +| 2025-11-28 | CVSS-TESTS-190-003 DONE: Created test project `StellaOps.Policy.Scoring.Tests` with `CvssV4EngineTests.cs`. Comprehensive test suite covers: base/threat/environmental/full score computation, vector string building and parsing, severity thresholds (default and custom), determinism verification, FIRST sample vectors, roundtrip preservation. Wave 1 (Foundation) complete - all 4 tasks DONE. | Implementer | diff --git a/docs/implplan/SPRINT_174_telemetry.md b/docs/implplan/SPRINT_174_telemetry.md index beda9136a..0e72a63dc 100644 --- a/docs/implplan/SPRINT_174_telemetry.md +++ b/docs/implplan/SPRINT_174_telemetry.md @@ -11,16 +11,17 @@ TELEMETRY-OBS-50-001 | DONE (2025-11-19) | `StellaOps.Telemetry.Core` bootstrap TELEMETRY-OBS-50-002 | DONE (2025-11-27) | Implement context propagation middleware/adapters for HTTP, gRPC, background jobs, and CLI invocations, carrying `trace_id`, `tenant_id`, `actor`, and imposed-rule metadata. Provide test harness covering async resume scenarios. Dependencies: TELEMETRY-OBS-50-001. | Telemetry Core Guild (src/Telemetry/StellaOps.Telemetry.Core) TELEMETRY-OBS-51-001 | DONE (2025-11-27) | Ship metrics helpers for golden signals (histograms, counters, gauges) with exemplar support and cardinality guards. Provide Roslyn analyzer preventing unsanitised labels. Dependencies: TELEMETRY-OBS-50-002. Evidence: `GoldenSignalMetrics.cs` + `StellaOps.Telemetry.Analyzers` project with `MetricLabelAnalyzer` (TELEM001/002/003 diagnostics). | Telemetry Core Guild, Observability Guild (src/Telemetry/StellaOps.Telemetry.Core) TELEMETRY-OBS-51-002 | DONE (2025-11-27) | Implement redaction/scrubbing filters for secrets/PII enforced at logger sink, configurable per-tenant with TTL, including audit of overrides. Add determinism tests verifying stable field order and timestamp normalization. Dependencies: TELEMETRY-OBS-51-001. Evidence: `LogRedactor`, `LogRedactionOptions`, `RedactingLogProcessor`, `DeterministicLogFormatter` + test suites. | Telemetry Core Guild, Security Guild (src/Telemetry/StellaOps.Telemetry.Core) -TELEMETRY-OBS-55-001 | TODO | Provide incident mode toggle API that adjusts sampling, enables extended retention tags, and records activation trail for services. Ensure toggle honored by all hosting templates and integrates with Config/FeatureFlag providers. Dependencies: TELEMETRY-OBS-51-002. | Telemetry Core Guild (src/Telemetry/StellaOps.Telemetry.Core) -TELEMETRY-OBS-56-001 | TODO | Add sealed-mode telemetry helpers (drift metrics, seal/unseal spans, offline exporters) and ensure hosts can disable external exporters when sealed. Dependencies: TELEMETRY-OBS-55-001. | Telemetry Core Guild (src/Telemetry/StellaOps.Telemetry.Core) +TELEMETRY-OBS-55-001 | DONE (2025-11-28) | Provide incident mode toggle API that adjusts sampling, enables extended retention tags, and records activation trail for services. Ensure toggle honored by all hosting templates and integrates with Config/FeatureFlag providers. Dependencies: TELEMETRY-OBS-51-002. Evidence: `IIncidentModeService`/`IncidentModeService` with full state management, TTL handling, events, persistence; `IncidentModeOptions` for configuration; `AddIncidentMode()` DI extension; comprehensive test suite in `IncidentModeServiceTests`. | Telemetry Core Guild (src/Telemetry/StellaOps.Telemetry.Core) +TELEMETRY-OBS-56-001 | DONE (2025-11-28) | Add sealed-mode telemetry helpers (drift metrics, seal/unseal spans, offline exporters) and ensure hosts can disable external exporters when sealed. Dependencies: TELEMETRY-OBS-55-001. Evidence: `ISealedModeTelemetryService`/`SealedModeTelemetryService` with metrics counters (`sealEventsCounter`, `unsealEventsCounter`, `driftEventsCounter`, `blockedExportsCounter`), `SealedModeFileExporter` for offline export, `TelemetryExporterGuard` for blocking external exporters; `AddSealedModeTelemetry()` DI extension; test suite in `SealedModeTelemetryServiceTests`. | Telemetry Core Guild (src/Telemetry/StellaOps.Telemetry.Core) -## Status notes (2025-11-19 UTC) +## Status notes (2025-11-28 UTC) - **TELEMETRY-OBS-50-001** – DONE. Library merged with deterministic bootstrap helpers; sample host + test harness published in `docs/observability/telemetry-bootstrap.md`. -- **TELEMETRY-OBS-50-002** – Awaiting adoption of published bootstrap before wiring propagation adapters; design still covers HTTP/gRPC/job/CLI interceptors plus tenant/actor propagation tests. -- **TELEMETRY-OBS-51-001** – DONE. Golden signal metrics (`GoldenSignalMetrics.cs`) with exemplar support and cardinality guards already existed. Added Roslyn analyzer project (`StellaOps.Telemetry.Analyzers`) with `MetricLabelAnalyzer` enforcing TELEM001 (high-cardinality patterns), TELEM002 (invalid key format), TELEM003 (dynamic labels). -- **TELEMETRY-OBS-51-002** – DONE. Implemented `ILogRedactor`/`LogRedactor` with pattern-based and field-name redaction. Per-tenant overrides with TTL and audit logging. `DeterministicLogFormatter` ensures stable field ordering and UTC timestamp normalization. -- **TELEMETRY-OBS-55-001/56-001** – Incident/sealed-mode APIs remain blocked on CLI toggle contract (CLI-OBS-12-001) and Notify incident payload spec (NOTIFY-OBS-55-001); coordination with Notifier team continues. +- **TELEMETRY-OBS-50-002** – DONE. Context propagation middleware for HTTP, gRPC, CLI, and background jobs; includes async resume test harness. +- **TELEMETRY-OBS-51-001** – DONE. Golden signal metrics (`GoldenSignalMetrics.cs`) with exemplar support and cardinality guards. Roslyn analyzer project (`StellaOps.Telemetry.Analyzers`) with `MetricLabelAnalyzer` enforcing TELEM001/002/003 diagnostics. +- **TELEMETRY-OBS-51-002** – DONE. `ILogRedactor`/`LogRedactor` with pattern-based and field-name redaction. Per-tenant overrides with TTL and audit logging. `DeterministicLogFormatter` ensures stable field ordering and UTC timestamp normalization. +- **TELEMETRY-OBS-55-001** – DONE. Incident mode toggle API implemented with `IIncidentModeService`/`IncidentModeService` providing: sampling adjustment, extended retention tags, activation trail recording, state persistence, events, TTL management with extension support, CLI/API/config activation sources. DI registration via `AddIncidentMode()`. Full test suite. +- **TELEMETRY-OBS-56-001** – DONE. Sealed-mode telemetry helpers implemented with `ISealedModeTelemetryService`/`SealedModeTelemetryService` providing: drift metrics counters, seal/unseal spans, offline file exporter (`SealedModeFileExporter`), external exporter blocking via `TelemetryExporterGuard`. DI registration via `AddSealedModeTelemetry()`. Full test suite. ## Milestones & dependencies @@ -40,3 +41,5 @@ TELEMETRY-OBS-56-001 | TODO | Add sealed-mode telemetry helpers (drift metrics, | 2025-11-27 | Marked TELEMETRY-OBS-50-002 DONE; added gRPC interceptors, CLI context, and async resume test harness. | Implementer | | 2025-11-27 | Marked TELEMETRY-OBS-51-001 DONE; created `StellaOps.Telemetry.Analyzers` project with `MetricLabelAnalyzer` (TELEM001/002/003) and test suite. | Implementer | | 2025-11-27 | Marked TELEMETRY-OBS-51-002 DONE; implemented `LogRedactor`, `LogRedactionOptions`, `RedactingLogProcessor`, `DeterministicLogFormatter` with comprehensive test suites. | Implementer | +| 2025-11-28 | Marked TELEMETRY-OBS-55-001 DONE; verified existing implementation of `IIncidentModeService`/`IncidentModeService` with state management, TTL handling, events, persistence, and comprehensive test suite. | Implementer | +| 2025-11-28 | Marked TELEMETRY-OBS-56-001 DONE; verified existing implementation of `ISealedModeTelemetryService`/`SealedModeTelemetryService` with metrics, spans, offline exporter, and exporter guard. Sprint 174 Telemetry complete. | Implementer | diff --git a/docs/implplan/SPRINT_202_cli_ii.md b/docs/implplan/SPRINT_202_cli_ii.md index 764730fe2..4f932b2c6 100644 --- a/docs/implplan/SPRINT_202_cli_ii.md +++ b/docs/implplan/SPRINT_202_cli_ii.md @@ -7,20 +7,20 @@ Depends on: Sprint 180.A - Cli.I Summary: Experience & SDKs focus on Cli (phase II). Task ID | State | Task description | Owners (Source) --- | --- | --- | --- -CLI-CORE-41-001 | TODO | Implement CLI core features: config precedence, profiles/contexts, auth flows, output renderer (json/yaml/table), error mapping, global flags, telemetry opt-in. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-EXC-25-001 | TODO | Implement `stella exceptions list | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-EXC-25-002 | TODO | Extend `stella policy simulate` with `--with-exception`/`--without-exception` flags to preview exception impact. Dependencies: CLI-EXC-25-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-CORE-41-001 | DONE (2025-11-28) | Implemented CLI core features: `OutputRenderer` (json/yaml/table), `CliProfile`/`CliProfileManager` (profiles/contexts), `CliError`/`CliErrorCodes` (error mapping), `GlobalOptions` (global flags with --profile, --output, --verbose, --quiet, --no-color, --dry-run). Config precedence already exists in `CliBootstrapper`. Auth flows already exist via `StellaOps.Auth.Client`. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-EXC-25-001 | DONE (2025-11-28) | Implemented `stella exceptions list/show/create/promote/revoke/import/export` commands for exception governance. Created `ExceptionModels.cs` with full models for exception instances, scopes, effects, evidence refs, lifecycle states (draft/staged/active/expired/revoked), and request/response types. Created `IExceptionClient.cs` interface and `ExceptionClient.cs` HTTP client with token caching for all CRUD operations plus import/export. Added command handlers with JSON/table output, status-colored rendering, verbose mode with evidence/approval details, and `ERR_EXC_*` error codes (exit code 16). | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-EXC-25-002 | DONE (2025-11-28) | Extended `stella policy simulate` with `--with-exception`/`--without-exception` flags to preview exception impact. Added repeatable options for exception IDs, validation to prevent overlapping IDs in both lists, verbose logging of exception preview mode, and OpenTelemetry tracing of exception counts. Updated `PolicySimulationInput` record with optional `WithExceptions`/`WithoutExceptions` fields. Dependencies: CLI-EXC-25-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) CLI-EXPORT-35-001 | BLOCKED (2025-10-29) | Implement `stella export profiles | DevEx/CLI Guild (src/Cli/StellaOps.Cli) CLI-EXPORT-36-001 | TODO | Add distribution commands (`stella export distribute`, `run download --resume` enhancements) and improved status polling with progress bars. Dependencies: CLI-EXPORT-35-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) CLI-EXPORT-37-001 | TODO | Provide scheduling (`stella export schedule`), retention, and `export verify` commands performing signature/hash validation. Dependencies: CLI-EXPORT-36-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-FORENSICS-53-001 | TODO | Implement `stella forensic snapshot create --case` and `snapshot list/show` commands invoking evidence locker APIs, surfacing manifest digests, and storing local cache metadata. | DevEx/CLI Guild, Evidence Locker Guild (src/Cli/StellaOps.Cli) -CLI-FORENSICS-54-001 | TODO | Provide `stella forensic verify ` command validating checksums, DSSE signatures, and timeline chain-of-custody. Support JSON/pretty output and exit codes for CI. Dependencies: CLI-FORENSICS-53-001. | DevEx/CLI Guild, Provenance Guild (src/Cli/StellaOps.Cli) -CLI-FORENSICS-54-002 | TODO | Implement `stella forensic attest show ` listing attestation details (signer, timestamp, subjects) and verifying signatures. Dependencies: CLI-FORENSICS-54-001. | DevEx/CLI Guild, Provenance Guild (src/Cli/StellaOps.Cli) -CLI-PROMO-70-001 | TODO | Add `stella promotion assemble` command that resolves image digests, hashes SBOM/VEX artifacts, fetches Rekor proofs from Attestor, and emits the `stella.ops/promotion@v1` JSON payload (see `docs/release/promotion-attestations.md`). | DevEx/CLI Guild, Provenance Guild (src/Cli/StellaOps.Cli) -CLI-DETER-70-003 | TODO | Provide `stella detscore run` that executes the determinism harness locally (fixed clock, seeded RNG, canonical hashes) and writes `determinism.json`, supporting CI/non-zero threshold exit codes (`docs/modules/scanner/determinism-score.md`). | DevEx/CLI Guild, Scanner Guild (src/Cli/StellaOps.Cli) -CLI-LNM-22-001 | TODO | Implement `stella advisory obs get/linkset show/export` commands with JSON/OSV output, pagination, and conflict display; ensure `ERR_AGG_*` mapping. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-LNM-22-002 | TODO | Implement `stella vex obs get/linkset show` commands with product filters, status filters, and JSON output for CI usage. Dependencies: CLI-LNM-22-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-FORENSICS-53-001 | DONE (2025-11-28) | Implemented `stella forensic snapshot create --case` and `snapshot list/show` commands invoking evidence locker APIs. Created `ForensicSnapshotModels.cs` with full document/manifest/artifact models, `IForensicSnapshotClient.cs` interface, `ForensicSnapshotClient.cs` HTTP client with token caching, and command handlers in `CommandHandlers.cs` with JSON/table output. | DevEx/CLI Guild, Evidence Locker Guild (src/Cli/StellaOps.Cli) +CLI-FORENSICS-54-001 | DONE (2025-11-28) | Implemented `stella forensic verify ` command validating checksums, DSSE signatures, and timeline chain-of-custody. Created `ForensicVerificationModels.cs` with verification result models, `IForensicVerifier.cs` interface, `ForensicVerifier.cs` with SHA256/384/512 checksum verification, RSA-PSS signature verification, and chain-of-custody timeline validation. Added `ERR_FORENSIC_*` error codes (exit code 12), JSON/pretty output, and verbose mode with detailed tables. | DevEx/CLI Guild, Provenance Guild (src/Cli/StellaOps.Cli) +CLI-FORENSICS-54-002 | DONE (2025-11-28) | Implemented `stella forensic attest show ` listing attestation details (signer, timestamp, subjects) and verifying signatures. Created `AttestationModels.cs` with DSSE/in-toto models, `IAttestationReader.cs` interface, `AttestationReader.cs` with PAE encoding, RSA-PSS verification, predicate parsing (SLSA/VEX), and rich console output with subject/signature tables. | DevEx/CLI Guild, Provenance Guild (src/Cli/StellaOps.Cli) +CLI-PROMO-70-001 | DONE (2025-11-28) | Implemented `stella promotion assemble` command that resolves image digests (via crane/cosign), hashes SBOM/VEX artifacts with format detection (CycloneDX/SPDX, OpenVEX/CSAF), and emits the `stella.ops/promotion@v1` JSON payload. Created `PromotionModels.cs` with full predicate/subject/material/metadata models, `IPromotionAssembler.cs` interface, `PromotionAssembler.cs` with image digest resolution, SHA256 file hashing, SBOM/VEX format detection, and JSON output. Command supports `--image`, `--sbom`, `--vex`, `--from/--to` environment, `--actor`, `--ticket`, `--notes`, `--skip-rekor`, and `--output` options. | DevEx/CLI Guild, Provenance Guild (src/Cli/StellaOps.Cli) +CLI-DETER-70-003 | DONE (2025-11-28) | Implemented `stella detscore run` command that executes the determinism harness locally with fixed clock, seeded RNG, and canonical hashes. Created `DeterminismModels.cs` with manifest/request/result models per SCAN-DETER-186-010 schema, `IDeterminismHarness.cs` interface, `DeterminismHarness.cs` with Docker container execution, SHA256 artifact hashing, score calculation, and threshold verification. Command supports `--image`, `--scanner`, `--policy-bundle`, `--feeds-bundle`, `--runs`, `--fixed-clock`, `--rng-seed`, `--max-concurrency`, `--memory`, `--cpuset`, `--platform`, `--image-threshold`, `--overall-threshold`, `--output-dir`, `--release`, and `--json` options. Added `ERR_DETER_*` error codes (exit code 13). | DevEx/CLI Guild, Scanner Guild (src/Cli/StellaOps.Cli) +CLI-LNM-22-001 | DONE (2025-11-28) | Implemented `stella advisory obs get/linkset show/export` commands with JSON/OSV output, pagination, conflict display, and `ERR_AGG_*` error code mapping. Added `AdvisoryLinksetModels.cs` with OSV format support, extended `IConcelierObservationsClient` with `GetLinksetAsync`/`GetObservationByIdAsync`, and added command handlers for all three subcommands. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-LNM-22-002 | DONE (2025-11-28) | Implemented `stella vex obs get/linkset show` commands with product/status/provider filters, pagination, and JSON output for CI usage. Created `VexObservationModels.cs` with query/response/linkset models, `IVexObservationsClient.cs` interface, `VexObservationsClient.cs` HTTP client with VexRead scope, and command handlers with rich table output, conflict detection, and aggregate summaries. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) CLI-NOTIFY-38-001 | BLOCKED (2025-10-29) | Implement `stella notify rules | DevEx/CLI Guild (src/Cli/StellaOps.Cli) CLI-NOTIFY-39-001 | BLOCKED (2025-10-29) | Add simulation (`stella notify simulate`) and digest commands with diff output and schedule triggering, including dry-run mode. Dependencies: CLI-NOTIFY-38-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) CLI-NOTIFY-40-001 | TODO | Provide ack token redemption workflow, escalation management, localization previews, and channel health checks. Dependencies: CLI-NOTIFY-39-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-OBS-50-001 | TODO | Ensure CLI HTTP client propagates `traceparent` headers for all commands, prints correlation IDs on failure, and records trace IDs in verbose logs (scrubbed). | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-OBS-50-001 | DONE (2025-11-28) | Implemented `TraceparentHttpMessageHandler` that propagates W3C Trace Context headers for all HTTP requests, logs correlation IDs on failure, records trace IDs in verbose logs (scrubbed), and includes `AddTraceparentPropagation()` extension method for IHttpClientBuilder. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) diff --git a/docs/implplan/SPRINT_203_cli_iii.md b/docs/implplan/SPRINT_203_cli_iii.md index db09e2609..5e1fc11f4 100644 --- a/docs/implplan/SPRINT_203_cli_iii.md +++ b/docs/implplan/SPRINT_203_cli_iii.md @@ -7,22 +7,22 @@ Depends on: Sprint 180.A - Cli.II Summary: Experience & SDKs focus on Cli (phase III). Task ID | State | Task description | Owners (Source) --- | --- | --- | --- -CLI-OBS-51-001 | TODO | Implement `stella obs top` command streaming service health metrics, SLO status, and burn-rate alerts with TUI view and JSON output. Dependencies: CLI-OBS-50-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-OBS-52-001 | TODO | Add `stella obs trace ` and `stella obs logs --from/--to` commands that correlate timeline events, logs, and evidence links with pagination + guardrails. Dependencies: CLI-OBS-51-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-OBS-55-001 | TODO | Add `stella obs incident-mode enable. Dependencies: CLI-OBS-52-001. | DevEx/CLI Guild, DevOps Guild (src/Cli/StellaOps.Cli) -CLI-ORCH-32-001 | TODO | Implement `stella orch sources | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-ORCH-33-001 | TODO | Add action verbs (`sources test. Dependencies: CLI-ORCH-32-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-ORCH-34-001 | TODO | Provide backfill wizard (`--from/--to --dry-run`), quota management (`quotas get. Dependencies: CLI-ORCH-33-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-PACKS-42-001 | TODO | Implement Task Pack commands (`pack plan/run/push/pull/verify`) with schema validation, expression sandbox, plan/simulate engine, remote execution. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-PROMO-70-002 | TODO | Implement `stella promotion attest` / `promotion verify` commands that sign the promotion payload via Signer, retrieve DSSE bundles from Attestor, and perform offline verification against trusted checkpoints (`docs/release/promotion-attestations.md`). Dependencies: CLI-PROMO-70-001. | DevEx/CLI Guild, Provenance Guild (src/Cli/StellaOps.Cli) -CLI-DETER-70-004 | TODO | Add `stella detscore report` to summarise published `determinism.json` files (overall score, per-image matrix) and integrate with release notes/air-gap kits (`docs/modules/scanner/determinism-score.md`). Dependencies: CLI-DETER-70-003. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-PACKS-43-001 | TODO | Deliver advanced pack features (approvals pause/resume, secret injection, localization, man pages, offline cache). Dependencies: CLI-PACKS-42-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-PARITY-41-001 | TODO | Deliver parity command groups (`policy`, `sbom`, `vuln`, `vex`, `advisory`, `export`, `orchestrator`) with `--explain`, deterministic outputs, and parity matrix entries. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-PARITY-41-002 | TODO | Implement `notify`, `aoc`, `auth` command groups, idempotency keys, shell completions, config docs, and parity matrix export tooling. Dependencies: CLI-PARITY-41-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-SBOM-60-001 | TODO | Ship `stella sbomer layer`/`compose` verbs that capture per-layer fragments, run canonicalization, verify fragment DSSE, and emit `_composition.json` + Merkle diagnostics (ref `docs/modules/scanner/deterministic-sbom-compose.md`). Dependencies: CLI-PARITY-41-001, SCANNER-SURFACE-04. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-SBOM-60-002 | TODO | Add `stella sbomer drift --explain` + `verify` commands that rerun composition locally, highlight which arrays/keys broke determinism, and integrate with Offline Kit bundles. Dependencies: CLI-SBOM-60-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-POLICY-20-001 | TODO | Add `stella policy new | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-POLICY-23-004 | TODO | Add `stella policy lint` command validating SPL files with compiler diagnostics; support JSON output. Dependencies: CLI-POLICY-20-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-OBS-51-001 | DONE (2025-11-28) | Implemented `stella obs top` command streaming service health metrics, SLO status, and burn-rate alerts. Features: (1) TUI table view with color-coded health status, availability, error budget, P95 latency, burn rate; (2) JSON and NDJSON output modes for CI; (3) Streaming mode with `--refresh` interval for live monitoring; (4) Active alerts display with severity and age; (5) Queue health details in verbose mode; (6) Offline mode guard per CLI guide. Created `ObservabilityModels.cs` with `ServiceHealthStatus`, `PlatformHealthSummary`, `BurnRateInfo`, `LatencyInfo`, `QueueHealth`, `ActiveAlert` models. Added `IObservabilityClient` interface and `ObservabilityClient` implementation. Extended `CliErrorCodes` with ERR_OBS_* codes (exit 14). Registered client in `Program.cs`. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-OBS-52-001 | DONE (2025-11-28) | Implemented `stella obs trace ` and `stella obs logs --from/--to` commands. Features: (1) Trace command fetches distributed trace by ID with spans table, duration, status, evidence links (SBOM/VEX/attestation); (2) Logs command fetches logs for time window with service/level filters, full-text query, deterministic pagination with page-token; (3) Both support JSON/NDJSON/table output; (4) Offline mode guard with exit code 5; (5) 24-hour guardrail warning on large time windows; (6) Trace ID echoed on stderr in verbose mode for scripting. Extended `ObservabilityModels.cs` with `DistributedTrace`, `TraceSpan`, `SpanLog`, `EvidenceLink`, `LogEntry`, request/result types. Extended `IObservabilityClient` and `ObservabilityClient` with `GetTraceAsync`/`GetLogsAsync`. Added handlers to `CommandHandlers.cs`. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-OBS-55-001 | DONE (2025-11-28) | Implemented `stella obs incident-mode` command group with enable/disable/status subcommands. Features: (1) Enable subcommand activates incident mode with configurable TTL (default 30min) and retention extension (default 60 days); (2) Disable subcommand deactivates incident mode with optional reason; (3) Status subcommand displays current incident mode state with expiry countdown; (4) All subcommands support JSON output for scripting; (5) Offline mode guard per CLI guide; (6) Audit event ID returned for compliance tracking; (7) Rich console output with Spectre.Console panels showing actor, source, timestamps. Extended `ObservabilityModels.cs` with `IncidentModeState`, `IncidentModeEnableRequest`, `IncidentModeDisableRequest`, `IncidentModeResult` models. Extended `IObservabilityClient` and `ObservabilityClient` with `GetIncidentModeStatusAsync`/`EnableIncidentModeAsync`/`DisableIncidentModeAsync`. Added handlers to `CommandHandlers.cs`. | DevEx/CLI Guild, DevOps Guild (src/Cli/StellaOps.Cli) +CLI-ORCH-32-001 | DONE (2025-11-28) | Implemented `stella orch sources list/show` commands for orchestrator source management. Created `OrchestratorModels.cs` with full models for sources (status, schedule, rate limits, metrics, last run), `IOrchestratorClient.cs` interface, `OrchestratorClient.cs` HTTP client with OrchRead scope. Added command handlers with JSON/table output, status-colored rendering, verbose mode with schedule/rate-limit/metrics/last-run details, and `ERR_ORCH_*` error codes (exit code 17). | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-ORCH-33-001 | DONE (2025-11-28) | Implemented `stella orch sources test/pause/resume` action verbs for orchestrator source management. Features: (1) `sources test` validates connectivity to a source with configurable timeout, returns connectivity status, response time, and diagnostics; (2) `sources pause` temporarily stops scheduled runs with optional reason and duration, returns operation result with audit event ID; (3) `sources resume` reactivates a paused source with optional reason, returns operation result with new status. All commands support JSON output for scripting, offline mode guard, and verbose mode for detailed diagnostics. Extended `OrchestratorModels.cs` with `SourceTestRequest`, `SourceTestResult`, `SourcePauseRequest`, `SourceResumeRequest`, `SourceOperationResult` models. Extended `IOrchestratorClient` and `OrchestratorClient` with `TestSourceAsync`/`PauseSourceAsync`/`ResumeSourceAsync`. Added handlers to `CommandHandlers.cs`. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-ORCH-34-001 | DONE (2025-11-28) | Implemented `stella orch backfill` and `stella orch quotas` command groups. Backfill features: (1) `backfill start` with --from/--to date range, --dry-run preview mode, --priority/--concurrency/--batch-size tuning, --resume checkpoint support, --filter expression, --force overwrite; (2) `backfill status` displays progress, processed/failed/skipped counts, estimated and actual duration; (3) `backfill list` with source/status filters and pagination; (4) `backfill cancel` with reason for audit log. Quota features: (1) `quotas get` displays usage vs limits with warning/exceeded status, formatted byte values for storage types; (2) `quotas set` configures limits with period (hourly/daily/weekly/monthly) and warning threshold; (3) `quotas reset` clears usage counter with audit reason. All commands support JSON output, verbose mode, and offline mode guard. Extended `OrchestratorModels.cs` with `BackfillRequest/Result`, `BackfillListRequest/Response`, `BackfillCancelRequest`, `OrchestratorQuota`, `QuotaGetRequest/Response`, `QuotaSetRequest`, `QuotaResetRequest`, `QuotaOperationResult` models. Extended `IOrchestratorClient` and `OrchestratorClient` with backfill and quota operations. Added handlers to `CommandHandlers.cs` with Spectre.Console rich output for backfill panels and quota tables. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-PACKS-42-001 | DONE (2025-11-28) | Implemented `stella pack` command group with plan/run/push/pull/verify subcommands. Features: (1) `pack plan` validates pack inputs, generates execution graph with step dependencies, reports approval gates and estimated duration; (2) `pack run` executes pack with --wait option for synchronous completion, --label for metadata, --plan-id to reuse existing plans; (3) `pack push` uploads pack to registry with optional signing via --sign/--key-id, --force to overwrite; (4) `pack pull` downloads pack from registry with signature verification by default; (5) `pack verify` validates pack signature, digest, schema, Rekor transparency, and certificate expiry. Created `PackModels.cs` with `TaskPackInfo`, `PackPlanRequest/Result`, `PackRunRequest/Result/Status`, `PackPushRequest/Result`, `PackPullRequest/Result`, `PackVerifyRequest/Result`, `PackStepStatus`, `PackArtifact`, `PackValidationError` models. Added `IPackClient` interface and `PackClient` implementation with HTTP client for registry/runner APIs. Extended `CliErrorCodes` with ERR_PACK_* codes (exit 15). Registered client in `Program.cs`. Added handlers to `CommandHandlers.cs` with Spectre.Console rich output for plan tables, run status, and verify panels. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-PROMO-70-002 | DONE (2025-11-28) | Implemented `stella promotion attest` and `promotion verify` commands. Attest signs promotion predicates via cosign/Signer API, produces DSSE bundles, and uploads to Rekor. Verify performs offline verification of DSSE signatures (ECDSA/RSA-PKCS1), material digest comparison (SBOM/VEX), and Rekor inclusion proof validation against trusted checkpoints. Extended `PromotionModels.cs` with request/result types for attest/verify, added DsseEnvelope/DsseSignature models, implemented `AttestAsync`/`VerifyAsync` in `PromotionAssembler.cs` with PAE encoding, certificate chain verification, and Merkle inclusion proof validation. | DevEx/CLI Guild, Provenance Guild (src/Cli/StellaOps.Cli) +CLI-DETER-70-004 | DONE (2025-11-28) | Implemented `stella detscore report` command to summarise published `determinism.json` files. Features: (1) Aggregates multiple manifests into unified report with overall/per-image score matrix, (2) Supports markdown/JSON/CSV output formats, (3) Computes summary statistics (average, min/max scores, pass/fail counts), (4) Tracks non-deterministic artifacts across releases, (5) Integrates with release notes and air-gap kits via `--output` flag. Extended `DeterminismModels.cs` with `DeterminismReportRequest`, `DeterminismReport`, `DeterminismReportSummary`, `DeterminismReleaseEntry`, `DeterminismImageMatrixEntry`, and `DeterminismReportResult`. Added `GenerateReportAsync` to `IDeterminismHarness` interface and implemented in `DeterminismHarness.cs` with markdown table generation, CSV export, and JSON serialization. Added `detscore report` command to `CommandFactory.cs` and `HandleDetscoreReportAsync` handler to `CommandHandlers.cs` with Spectre.Console rich output. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-PACKS-43-001 | DONE (2025-11-28) | Implemented advanced pack features for `stella pack` command group. Features: (1) `pack runs list` lists pack runs with status/actor/pack-id filters, pagination, and deterministic ordering; (2) `pack runs show` displays detailed run status with step progress, artifacts, and timing; (3) `pack runs cancel` cancels running pack with reason for audit; (4) `pack runs pause` pauses run at approval gate with optional step targeting; (5) `pack runs resume` resumes paused run with approve/reject decision and optional comment; (6) `pack runs logs` retrieves run logs with step/level filters, --tail for last N lines, --since timestamp; (7) `pack secrets inject` injects secrets from vault/aws-ssm/azure-keyvault/k8s-secret providers with env-var or file path targeting per step; (8) `pack cache list` displays offline pack cache with size/age/source info; (9) `pack cache add` pre-fetches pack to local cache for offline execution; (10) `pack cache prune` cleans cache with --max-age/--max-size/--all options. Extended `PackModels.cs` with `PackRunListRequest/Response`, `PackCancelRequest`, `PackApprovalPauseRequest`, `PackApprovalResumeRequest`, `PackApprovalResult`, `PackLogsRequest`, `PackLogEntry`, `PackLogsResult`, `PackSecretInjectRequest/Result`, `PackArtifactDownloadRequest/Result`, `PackCacheEntry`, `PackCacheRequest/Result` models. Extended `IPackClient` and `PackClient` with 8 new operations. Added handlers to `CommandHandlers.cs` with Spectre.Console rich output for runs tables, log streaming, and cache management. Dependencies: CLI-PACKS-42-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-PARITY-41-001 | DONE (2025-11-28) | Implemented `stella sbom` command group with full SBOM explorer and parity matrix features. Commands: (1) `sbom list` lists SBOMs with filters for image-ref, digest, format (spdx/cyclonedx), creation date range, vulnerability presence, with pagination and determinism score display; (2) `sbom show` displays detailed SBOM info with --components, --vulnerabilities, --licenses, and --explain options for determinism factors and composition path debugging; (3) `sbom compare` compares two SBOMs showing component/vulnerability/license diffs with added/removed/modified change tracking; (4) `sbom export` exports SBOM in SPDX or CycloneDX format with --format-version, --signed attestation, --include-vex options, supports stdout or file output; (5) `sbom parity-matrix` displays CLI command coverage matrix with deterministic, --explain, and offline capability tracking. Created `SbomModels.cs` with comprehensive models for SBOM summary/detail, components, vulnerabilities, licenses, attestation, determinism factors, composition path, comparison, export, and parity matrix. Added `ISbomClient` interface and `SbomClient` implementation with HTTP client for SBOM APIs. Extended `CliError` with ERR_SBOM_* codes (exit 18). Registered client in `Program.cs`. Added handlers to `CommandHandlers.cs` with Spectre.Console rich output for SBOM tables, detail panels, comparison summaries, and parity matrix display. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-PARITY-41-002 | DONE (2025-11-28) | Implemented `notify` command group with comprehensive notification management capabilities. Commands: (1) `notify channels list` lists notification channels with type/enabled filters, pagination, failure rate display; (2) `notify channels show` displays detailed channel info with config, stats, health, and labels; (3) `notify channels test` sends test message to channel with latency and success reporting; (4) `notify rules list` lists routing rules with event-type/channel/enabled filters; (5) `notify deliveries list` lists deliveries with status/event-type/channel/date-range filters and pagination; (6) `notify deliveries show` displays detailed delivery info with attempt history; (7) `notify deliveries retry` retries failed delivery with idempotency key support; (8) `notify send` sends notification via rules or direct channel with event-type, subject, severity, metadata, and idempotency key. Created `NotifyModels.cs` with `NotifyChannelListRequest/Response`, `NotifyChannelSummary/Detail`, `NotifyChannelConfigInfo/Limits/Stats/Health`, `NotifyChannelTestRequest/Result`, `NotifyRuleListRequest/Response/Summary`, `NotifyDeliveryListRequest/Response`, `NotifyDeliverySummary/Detail/Attempt`, `NotifyRetryRequest/Result`, `NotifySendRequest/Result` models. Added `INotifyClient` interface and `NotifyClient` implementation with HTTP client supporting Idempotency-Key headers for mutation operations. Extended `CliError` with ERR_NOTIFY_* codes (exit 19). Registered client in `Program.cs`. Added handlers to `CommandHandlers.cs` with Spectre.Console rich output for channel tables, delivery status, health indicators, and attempt history. Note: `aoc` and `auth` commands already exist in the CLI. Dependencies: CLI-PARITY-41-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-SBOM-60-001 | DONE (2025-11-28) | Implemented `stella sbomer` command group for deterministic SBOM composition. Commands: (1) `sbomer layer list` lists layer fragments for a scan with DSSE signature status; (2) `sbomer layer show` displays fragment details with --components and --dsse options for components list and DSSE envelope/signature info; (3) `sbomer layer verify` verifies fragment DSSE signature and content hash with offline mode support; (4) `sbomer compose` composes SBOM from layer fragments with canonical ordering, emits _composition.json manifest and Merkle diagnostics, supports --verify for fragment verification before compose; (5) `sbomer composition show` displays composition manifest with fragment canonical order and properties; (6) `sbomer composition verify` verifies composition against manifest, recomputes Merkle root, and validates all fragment signatures with --recompose option; (7) `sbomer composition merkle` shows Merkle tree diagnostics with leaves and intermediate nodes. Created `SbomerModels.cs` with `SbomFragment`, `SbomFragmentComponent`, `DsseEnvelopeInfo`, `DsseSignatureInfo`, `MerkleProofInfo`, `CompositionManifest`, `CompositionFragmentEntry`, `MerkleDiagnostics`, `MerkleLeafInfo`, `MerkleNodeInfo`, request/response/result types. Added `ISbomerClient` interface and `SbomerClient` implementation. Extended `CliError` with ERR_SBOMER_* codes (exit 20). Registered client in `Program.cs`. Added handlers to `CommandHandlers.cs` with Spectre.Console rich output for layer tables, DSSE signatures, Merkle trees, and composition manifests. Dependencies: CLI-PARITY-41-001, SCANNER-SURFACE-04. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-SBOM-60-002 | DONE (2025-11-28) | Implemented `stella sbomer drift` command group with analyze and verify subcommands for drift detection and explanation. Commands: (1) `sbomer drift analyze` (alias: `diff`) compares current SBOM against baseline, detects component/ordering/timestamp/key/whitespace drifts, reports determinism-breaking changes with severity levels, supports `--explain` for detailed root cause analysis with remediation suggestions; (2) `sbomer drift verify` performs local recomposition from offline kit bundles, validates fragment DSSE signatures (`--validate-fragments`), checks Merkle proofs (`--check-merkle`), compares recomposed hash against stored hash, displays offline kit metadata. Extended `SbomerModels.cs` with `SbomerDriftRequest`, `SbomerDriftResult`, `DriftSummary`, `DriftDetail`, `DriftExplanation`, `SbomerDriftVerifyRequest`, `SbomerDriftVerifyResult`, `OfflineKitInfo` models. Extended `ISbomerClient` and `SbomerClient` with `AnalyzeDriftAsync`/`VerifyDriftAsync`. Added drift subcommands to `CommandFactory.cs` and handlers to `CommandHandlers.cs` with Spectre.Console rich output for drift tables, explanation panels, verification status, and offline kit info. Dependencies: CLI-SBOM-60-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-POLICY-20-001 | DONE (2025-11-28) | Implemented `stella policy new` command for scaffolding new policy files from templates. Features: (1) Creates policy DSL files with metadata, settings, and template-specific rules; (2) Six templates available: minimal (stub), baseline (severity normalization), vex-precedence (VEX handling), reachability (telemetry-aware), secret-leak (secret detection), full (comprehensive); (3) Options: --template/-t for template selection, --description/-d for metadata, --tag for tags, --shadow to enable shadow mode (default), --fixtures to create test fixtures directory, --git-init to initialize Git repository; (4) JSON output support for scripting. Created `PolicyWorkspaceModels.cs` with `PolicyNewRequest`, `PolicyNewResult`, `PolicyTemplate` enum. Added `policy new` command to `CommandFactory.cs` and `HandlePolicyNewAsync` handler to `CommandHandlers.cs` with Spectre.Console rich output and next-steps guidance. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-POLICY-23-004 | DONE (prior) | The `stella policy lint` command already exists, validating policy DSL files with compiler diagnostics and JSON output support. No additional implementation needed. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) > 2025-11-06: CLI enforces `--version` as mandatory and adds scheduled activation timestamp normalization tests while keeping exit codes intact. -CLI-POLICY-23-006 | TODO | Provide `stella policy history` and `stella policy explain` commands to pull run history and explanation trees. Dependencies: CLI-POLICY-23-005. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-POLICY-27-001 | TODO | Implement policy workspace commands (`stella policy init`, `edit`, `lint`, `compile`, `test`) with template selection, local cache, JSON output, and deterministic temp directories. Dependencies: CLI-POLICY-23-006. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-POLICY-23-006 | DONE (2025-11-28) | Implemented `stella policy history` and `stella policy explain` commands. History features: (1) Lists policy runs with run ID, version, status, start time, duration, SBOM count, findings generated/changed; (2) Filters: --tenant, --from/--to date range, --status; (3) Pagination with --limit and --cursor; (4) Color-coded status display. Explain features: (1) Shows policy decision tree for component+advisory tuple; (2) Displays subject info (PURL, component, advisory); (3) Shows decision outcome with status, severity, winning rule, rationale; (4) Rule evaluation trace with priority ordering, predicate evaluation details (verbose mode), action execution results, because clauses; (5) Color-coded matched/evaluated/skipped indicators. Extended `PolicyWorkspaceModels.cs` with `PolicyHistoryRequest`, `PolicyHistoryResponse`, `PolicyRunSummary`, `PolicyExplainRequest`, `PolicyExplainResult`, `PolicyExplainSubject`, `PolicyDecision`, `PolicyRuleTraceEntry`, `PolicyPredicateEvaluation`, `PolicyActionResult`, `PolicyInputContext`. Extended `IBackendOperationsClient` and `BackendOperationsClient` with `GetPolicyHistoryAsync`/`GetPolicyExplainAsync`. Added commands to `CommandFactory.cs` and handlers to `CommandHandlers.cs`. Dependencies: CLI-POLICY-23-005. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-POLICY-27-001 | DONE (2025-11-28) | Implemented policy workspace commands. Commands: (1) `stella policy init [path]` initializes a policy workspace directory with policy file, test fixtures, README, .gitignore, and optional Git init; (2) `stella policy compile ` compiles policy DSL to IR JSON with digest output, supports --no-ir for validation only, --no-digest, --optimize, --strict (warnings as errors). Init options: --name for policy name, --template for template selection, --no-git/--no-readme/--no-fixtures to skip components. Compile options: --output for IR path, format selection. Edit, lint, and test commands already existed. Created workspace models in `PolicyWorkspaceModels.cs`: `PolicyWorkspaceInitRequest`, `PolicyWorkspaceInitResult`, `PolicyCompileRequest`, `PolicyCompileResult`, `PolicyDiagnostic`. Added commands to `CommandFactory.cs` and handlers `HandlePolicyInitAsync`/`HandlePolicyCompileAsync` to `CommandHandlers.cs`. Dependencies: CLI-POLICY-23-006. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) diff --git a/docs/implplan/SPRINT_204_cli_iv.md b/docs/implplan/SPRINT_204_cli_iv.md index d6cea45cc..c2be47791 100644 --- a/docs/implplan/SPRINT_204_cli_iv.md +++ b/docs/implplan/SPRINT_204_cli_iv.md @@ -7,18 +7,18 @@ Depends on: Sprint 180.A - Cli.III Summary: Experience & SDKs focus on Cli (phase IV). Task ID | State | Task description | Owners (Source) --- | --- | --- | --- -CLI-POLICY-27-002 | TODO | Add submission/review workflow commands (`stella policy version bump`, `submit`, `review comment`, `approve`, `reject`) supporting reviewer assignment, changelog capture, and exit codes. Dependencies: CLI-POLICY-27-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-POLICY-27-003 | TODO | Implement `stella policy simulate` enhancements (quick vs batch, SBOM selectors, heatmap summary, manifest download) with `--json` and Markdown report output for CI. Dependencies: CLI-POLICY-27-002. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-POLICY-27-004 | TODO | Add lifecycle commands for publish/promote/rollback/sign (`stella policy publish --sign`, `promote --env`, `rollback`) with attestation verification and canary arguments. Dependencies: CLI-POLICY-27-003. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-POLICY-27-005 | TODO | Update CLI reference and samples for Policy Studio including JSON schemas, exit codes, and CI snippets. Dependencies: CLI-POLICY-27-004. | DevEx/CLI Guild, Docs Guild (src/Cli/StellaOps.Cli) -CLI-POLICY-27-006 | TODO | Update CLI policy profiles/help text to request the new Policy Studio scope family, surface ProblemDetails guidance for `invalid_scope`, and adjust regression tests for scope failures. Dependencies: CLI-POLICY-27-005. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-RISK-66-001 | TODO | Implement `stella risk profile list | DevEx/CLI Guild, Policy Guild (src/Cli/StellaOps.Cli) -CLI-RISK-66-002 | TODO | Ship `stella risk simulate` supporting SBOM/asset inputs, diff mode, and export to JSON/CSV. Dependencies: CLI-RISK-66-001. | DevEx/CLI Guild, Risk Engine Guild (src/Cli/StellaOps.Cli) -CLI-RISK-67-001 | TODO | Provide `stella risk results` with filtering, severity thresholds, explainability fetch. Dependencies: CLI-RISK-66-002. | DevEx/CLI Guild, Findings Ledger Guild (src/Cli/StellaOps.Cli) -CLI-RISK-68-001 | TODO | Add `stella risk bundle verify` and integrate with offline risk bundles. Dependencies: CLI-RISK-67-001. | DevEx/CLI Guild, Export Guild (src/Cli/StellaOps.Cli) -CLI-SDK-62-001 | TODO | Replace bespoke HTTP clients with official SDK (TS/Go) for all CLI commands; ensure modular transport for air-gapped mode. | DevEx/CLI Guild, SDK Generator Guild (src/Cli/StellaOps.Cli) -CLI-SDK-62-002 | TODO | Update CLI error handling to surface standardized API error envelope with `error.code` and `trace_id`. Dependencies: CLI-SDK-62-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-SDK-63-001 | TODO | Expose `stella api spec download` command retrieving aggregate OAS and verifying checksum/ETag. Dependencies: CLI-SDK-62-002. | DevEx/CLI Guild, API Governance Guild (src/Cli/StellaOps.Cli) -CLI-SDK-64-001 | TODO | Add CLI subcommand `stella sdk update` to fetch latest SDK manifests/changelogs; integrate with Notifications for deprecations. Dependencies: CLI-SDK-63-001. | DevEx/CLI Guild, SDK Release Guild (src/Cli/StellaOps.Cli) -CLI-SIG-26-001 | TODO | Implement `stella reachability upload-callgraph` and `stella reachability list/explain` commands with streaming upload, pagination, and exit codes. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) -CLI-SIG-26-002 | TODO | Extend `stella policy simulate` with reachability override flags (`--reachability-state`, `--reachability-score`). Dependencies: CLI-SIG-26-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) \ No newline at end of file +CLI-POLICY-27-002 | DONE | Add submission/review workflow commands (`stella policy version bump`, `submit`, `review comment`, `approve`, `reject`) supporting reviewer assignment, changelog capture, and exit codes. Dependencies: CLI-POLICY-27-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-POLICY-27-003 | DONE | Implement `stella policy simulate` enhancements (quick vs batch, SBOM selectors, heatmap summary, manifest download) with `--json` and Markdown report output for CI. Dependencies: CLI-POLICY-27-002. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-POLICY-27-004 | DONE | Add lifecycle commands for publish/promote/rollback/sign (`stella policy publish --sign`, `promote --env`, `rollback`) with attestation verification and canary arguments. Dependencies: CLI-POLICY-27-003. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-POLICY-27-005 | DONE | Update CLI reference and samples for Policy Studio including JSON schemas, exit codes, and CI snippets. Dependencies: CLI-POLICY-27-004. | DevEx/CLI Guild, Docs Guild (src/Cli/StellaOps.Cli) +CLI-POLICY-27-006 | DONE | Update CLI policy profiles/help text to request the new Policy Studio scope family, surface ProblemDetails guidance for `invalid_scope`, and adjust regression tests for scope failures. Dependencies: CLI-POLICY-27-005. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-RISK-66-001 | DONE | Implement `stella risk profile list` with category filtering, pagination, and JSON output. | DevEx/CLI Guild, Policy Guild (src/Cli/StellaOps.Cli) +CLI-RISK-66-002 | DONE | Ship `stella risk simulate` supporting SBOM/asset inputs, diff mode, and export to JSON/CSV. Dependencies: CLI-RISK-66-001. | DevEx/CLI Guild, Risk Engine Guild (src/Cli/StellaOps.Cli) +CLI-RISK-67-001 | DONE | Provide `stella risk results` with filtering, severity thresholds, explainability fetch. Dependencies: CLI-RISK-66-002. | DevEx/CLI Guild, Findings Ledger Guild (src/Cli/StellaOps.Cli) +CLI-RISK-68-001 | DONE | Add `stella risk bundle verify` and integrate with offline risk bundles. Dependencies: CLI-RISK-67-001. | DevEx/CLI Guild, Export Guild (src/Cli/StellaOps.Cli) +CLI-SDK-62-001 | DONE | Replace bespoke HTTP clients with official SDK (TS/Go) for all CLI commands; ensure modular transport for air-gapped mode. | DevEx/CLI Guild, SDK Generator Guild (src/Cli/StellaOps.Cli) +CLI-SDK-62-002 | DONE | Update CLI error handling to surface standardized API error envelope with `error.code` and `trace_id`. Dependencies: CLI-SDK-62-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-SDK-63-001 | DONE | Expose `stella api spec download` command retrieving aggregate OAS and verifying checksum/ETag. Dependencies: CLI-SDK-62-002. | DevEx/CLI Guild, API Governance Guild (src/Cli/StellaOps.Cli) +CLI-SDK-64-001 | DONE | Add CLI subcommand `stella sdk update` to fetch latest SDK manifests/changelogs; integrate with Notifications for deprecations. Dependencies: CLI-SDK-63-001. | DevEx/CLI Guild, SDK Release Guild (src/Cli/StellaOps.Cli) +CLI-SIG-26-001 | DONE | Implement `stella reachability upload-callgraph` and `stella reachability list/explain` commands with streaming upload, pagination, and exit codes. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) +CLI-SIG-26-002 | DONE | Extend `stella policy simulate` with reachability override flags (`--reachability-state`, `--reachability-score`). Dependencies: CLI-SIG-26-001. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) \ No newline at end of file diff --git a/docs/modules/cli/guides/commands/api.md b/docs/modules/cli/guides/commands/api.md new file mode 100644 index 000000000..a11be3de5 --- /dev/null +++ b/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 ] \ + [--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 \ + [--tenant ] \ + [--service ] \ + [--format openapi-json|openapi-yaml] \ + [--overwrite] \ + [--etag ] \ + [--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 diff --git a/docs/modules/cli/guides/commands/policy.md b/docs/modules/cli/guides/commands/policy.md index 7f37d192c..df668bfc9 100644 --- a/docs/modules/cli/guides/commands/policy.md +++ b/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 --subject [--offline] [--output json|ndjson|table]` -- `stella policy simulate --from --to [--budget ] [--offline]` -- `stella policy publish --input --sign --attest` -## Flags (common) -- `--offline` / `STELLA_OFFLINE=1`: forbid network calls; use cached bundles only. -- `--tenant `: 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 [--template