git.stella-ops.org/docs/features/unchecked/cli/witness-cli-commands.md

Witness CLI Commands

Module

Cli

Status

IMPLEMENTED

Description

CLI command group for managing witnesses with core witness operations and handler implementations. Provides two witness subsystems: reachability witness operations (show, verify, list, export) and binary micro-witness operations (generate, verify, bundle) for patch verification.

Implementation Details

• Reachability Witness Command Group: src/Cli/StellaOps.Cli/Commands/WitnessCommandGroup.cs -- WitnessCommandGroup (internal static class)
  • Sprint: SPRINT_3700_0005_0001_witness_ui_cli (CLI-001 through CLI-004)
  • Delegates to CommandHandlers.HandleWitnessShowAsync, HandleWitnessVerifyAsync, HandleWitnessListAsync, HandleWitnessExportAsync
• Binary Micro-Witness Command Group: src/Cli/StellaOps.Cli/Commands/Witness/WitnessCoreCommandGroup.cs -- WitnessCoreCommandGroup (internal static class)
  • Sprint: SPRINT_0128_001_BinaryIndex_binary_micro_witness (TASK-003)
  • Handlers in src/Cli/StellaOps.Cli/Commands/Witness/WitnessCoreCommandHandlers.cs
• Commands (reachability witnesses):
  • stella witness show <witness-id> [--format text|json|yaml] [--no-color] [--path-only] -- display witness with call path visualization
  • stella witness verify <witness-id> [--public-key <path>] [--offline] -- verify witness signature (local key or server-fetched)
  • stella witness list --scan <id> [--vuln <cve>] [--tier confirmed|likely|present|unreachable] [--reachable-only] [--probe-type kprobe|uprobe|tracepoint|usdt|fentry|fexit] [--format table|json] [--limit <n>] -- list witnesses for a scan with filtering
  • stella witness export <witness-id> [--format json|sarif] [--output <path>] [--include-dsse] -- export witness to file with optional DSSE envelope
• Commands (binary micro-witnesses):
  • stella witness generate <binary> --cve <id> [--sbom <path>] [--output <path>] [--sign] [--rekor] [--format json|envelope] -- generate micro-witness for binary patch verification
  • stella witness verify <witness> [--offline] [--sbom <path>] [--format text|json] -- verify micro-witness signature and Rekor proof
  • stella witness bundle <witness> --output <dir> [--include-binary] [--include-sbom] -- export self-contained verification bundle for air-gapped audits

E2E Test Plan

• Run stella witness show wit:sha256:abc123 and verify call path visualization output
• Run stella witness show wit:sha256:abc123 --format json and verify JSON witness details
• Run stella witness show wit:sha256:abc123 --path-only and verify only call path shown
• Run stella witness verify wit:sha256:abc123 and verify signature verification result
• Run stella witness verify wit:sha256:abc123 --offline and verify offline-only verification
• Run stella witness list --scan <id> and verify witness table with ID, CVE, tier columns
• Run stella witness list --scan <id> --tier confirmed --reachable-only and verify filtered results
• Run stella witness list --scan <id> --probe-type uprobe and verify eBPF probe type filtering
• Run stella witness export wit:sha256:abc123 --format sarif --output witness.sarif and verify SARIF file
• Run stella witness export wit:sha256:abc123 --include-dsse and verify DSSE envelope included
• Run stella witness generate ./binary.elf --cve CVE-2024-0567 --sign --rekor and verify signed micro-witness with Rekor log
• Run stella witness bundle ./witness.json --output ./bundle --include-binary --include-sbom and verify self-contained bundle