git.stella-ops.org/docs/features/unchecked/cli/vex-observation-and-webhooks-cli.md

VEX Observation and Webhooks CLI (stella vex evidence/webhooks/observation)

Module

Cli

Status

IMPLEMENTED

Description

Extended VEX CLI plugin providing evidence linking, webhook management for VEX events, and VEX observation commands with Rekor attestation support for transparency log integration. Consolidates vex, vexgen, vexlens, and advisory commands under a unified stella vex umbrella.

Implementation Details

• Unified VEX Command Group: src/Cli/StellaOps.Cli/Commands/VexCommandGroup.cs -- VexCommandGroup (static class)
  • Sprint: SPRINT_20260118_014_CLI_evidence_remaining_consolidation (CLI-E-008)
  • Consolidates: vex, vexgen, vexlens, advisory commands
• VEX Generation: src/Cli/StellaOps.Cli/Commands/VexGenCommandGroup.cs -- VexGenCommandGroup with evidence linking via IVexEvidenceLinker
• Runtime Observations: src/Cli/StellaOps.Cli/Commands/Observations/ObservationsCommandGroup.cs -- ObservationsCommandGroup (static class)
  • Sprint: SPRINT_20260122_039_Scanner_runtime_linkage_verification (RLV-008)
  • Uses IObservationStore and verification services from Scanner module
• Commands (VEX umbrella):
  • stella vex generate --scan <id> [--format openvex|csaf|cyclonedx] [--output <path>] [--product <name>] [--supplier <name>] [--sign] -- generate VEX documents
  • stella vex validate --input <file> [--strict] [--schema <file>] -- validate VEX document schema and consistency
  • stella vex query [--cve <id>] [--product <name>] [--status affected|not_affected|under_investigation] [--format table|json] [--limit <n>] -- query VEX statements
  • stella vex advisory list [--severity critical|high|medium|low] [--source nvd|osv|ghsa] [--after <date>] -- list advisories
  • stella vex advisory show <cve-id> [--format text|json] -- show advisory details
  • stella vex advisory sync [--source <name>] [--force] -- sync advisory feeds
  • stella vex lens analyze --scan <id> [--cve <id>] [--depth <n>] -- reachability analysis for VEX determination
  • stella vex lens explain --scan <id> --cve <id> -- explain VEX determination reasoning with evidence chain
  • stella vex apply --scan <id> --vex <file> [--dry-run] -- apply VEX statements to scan results
• Commands (observations):
  • stella observations query [--symbol <glob>] [--node-hash <sha256>] [--container <id>] [--pod <name>] [--namespace <ns>] -- query runtime observations

E2E Test Plan

• Run stella vex generate --scan <id> and verify VEX document with statement counts
• Run stella vex generate --scan <id> --format csaf --sign and verify signed CSAF output
• Run stella vex validate --input vex.json and verify schema/statement/product/CVE validation passes
• Run stella vex validate --input vex.json --strict and verify strict mode
• Run stella vex query --status not_affected and verify filtered query results
• Run stella vex advisory list --severity critical and verify critical-only listing
• Run stella vex advisory show CVE-2024-1234 and verify advisory details (severity, CWE, affected products)
• Run stella vex advisory sync and verify feed sync counts per source
• Run stella vex lens analyze --scan <id> and verify reachability analysis with REACHABLE/EXPLOITABLE columns
• Run stella vex lens explain --scan <id> --cve CVE-2024-1234 and verify determination explanation with evidence
• Run stella vex apply --scan <id> --vex vex.json --dry-run and verify preview of VEX suppressions
• Run stella observations query --symbol "SSL_*" and verify symbol-filtered observation results