stella advisory — Command Guide

Audience: DevEx engineers, security analysts, and CI authors who read or export advisory evidence from Stella Ops. Scope: Listing, retrieving, and exporting raw advisory evidence, plus offline verification of product CSAF advisories.

The stella advisory commands surface raw advisory and VEX evidence projected by Concelier and Excititor. They are read-only and aggregation-only: the CLI returns upstream evidence with provenance attached and never merges sources or infers severity. For background on this contract, see the Aggregation-Only Contract reference.

Commands

• stella advisory list --source <provider> [--status <status>] [--output json|ndjson|table] [--offline]
• stella advisory get --id <advisoryId> [--output json|table] [--offline]
• stella advisory export --bundle <path> [--offline]
• stella verify product-csaf-advisory <csaf.json> --envelope <dsse.json> --trust-root <pem-or-dir> [--key-id <id>] [--json]

Flags (common)

• --offline: pull from cached advisory snapshots/mirror bundles only; exit code 5 if remote needed.
• --source: provider filter (msrc, nvd, osv, csaf, etc.).
• --status: affected, fixed, not_affected, withdrawn, disputed.
• --output: json (default), ndjson, table.

Inputs/outputs

• Inputs: Concelier/Excititor advisory projections; cached mirror bundles when offline.
• Outputs: raw evidence with provenance (observationId, linksetId, signatures); no merging/inference.
• Exit codes follow the output and exit-code reference; not found → 4, offline violation → 5.

Determinism rules

• Sorted by advisory key; withdrawn/duplicate handling matches upstream evidence; no severity inference.
• Timestamps UTC; hashes lowercase hex.

Offline/air-gap notes

• Mirror bundles must be preloaded for offline use; CLI verifies signatures against trust roots.
• Export uses local evidence only; produces deterministic bundle with manifest + checksums.

Product CSAF advisory verification

stella verify product-csaf-advisory verifies the concrete product-csaf-advisory-v1 artifact contract from docs/contracts/stella-product-csaf-advisory-v1.md. It reads a local CSAF JSON document and its local DSSE envelope, canonicalizes the CSAF JSON, computes the sha256: digest, and verifies the DSSE envelope through the product CSAF offline verifier with local manufacturer PEM trust roots.

Required inputs:

• <csaf.json>: local CSAF advisory JSON file.
• --envelope <dsse.json>: local DSSE envelope JSON file.
• --trust-root <pem-or-dir>: one or more PEM public-key files or directories.

Optional inputs:

• --key-id <id>: expected signer key ID. When omitted, key IDs are inferred from the DSSE envelope signatures.
• --trust-root-id <id>: display/reporting identifier for loaded PEM roots.
• --json or --output json: deterministic JSON output for CI.

The command does not fetch http or https inputs and fails closed when trust roots are missing, the DSSE signature cannot be verified, or the canonical CSAF hash does not match the signed artifact payload. Table output reports only successful verification; JSON output reports deterministic issue codes for failures.