Scanner witness records

stella reachability witness-ops lists, reads and requests verification of persisted Scanner witness records. The separate top-level stella witness group operates on binary micro-witness files.

Owner contract verified against 3ba34ad13b13c94351b5ff6a0cc6d0fc4ca40303 (2026-10-14). Original CLI implementation checkpoint verified against bd8c3f77b2799f2daafacf4df8ee683a6bb7b776. CLI source qualification and exact test identities are recorded in the CCP-089 source checkpoint. Re-verify with pwsh tools/scripts/test-targeted-xunit.ps1 -Project src/Cli/__Tests/StellaOps.Cli.Tests/StellaOps.Cli.Tests.csproj -Class '*WitnessOwnerContractTests' -BuildProjectReferences -MaxThreads 1. Source tests do not establish availability in a packaged CLI or a deployed installation. The frozen capture tooling is available and the scoped owner reference is generated from an actual Scanner owner-host capture. Source qualification and integration receipts are recorded in the owning sprint. The reference’s “Auth: Not declared” records missing metadata; owner authorization remains required. The initial accepted Scanner test-factory input and dated actual-host capture are retained in the CCP-089 forward qualification.

List and read

Choose exactly one CLI list selector: a scan ID, an exact CVE or an exact graph hash. The CLI refuses combined selectors. Scanner returns the matching retained records without paging; totalCount is the number returned. An empty list does not prove that a scan exists or that no witness exists elsewhere.

stella reachability witness-ops list --scan <scan-id> --format json
stella reachability witness-ops list --vuln CVE-2026-1234
stella reachability witness-ops list --graph-hash <graph-hash>
stella reachability witness-ops show <witness-record-guid> --format json
stella reachability witness-ops show <witness-record-guid> --path-only

A scan ID is trimmed nonblank opaque text, including Scanner’s generated 40-character IDs. The CVE and graph-hash selectors retain their exact values. The client encodes query values once. Read and verification take the persisted record GUID. The record’s witnessHash and nested payload.witness_id are separate identities; neither is substituted for the GUID.

The owner wrapper contains the recorded scan, nullable run, timestamps, signature metadata and the nested witness.v1 payload. JSON output retains those fields. List JSON adds the display verdict unknown: Scanner’s witness record supplies no public reachability verdict. Text output reads the payload’s artifact, vulnerability, entrypoint, path and sink; missing values say not recorded. Text escapes terminal control characters and Unicode through JSON string escaping. The yaml display format emits the same complete JSON representation, which is valid YAML 1.2.

Missing or foreign record GUIDs return a nonzero command result. Malformed responses, wrong subjects, inconsistent lists, transport errors and authorization failures produce no domain output. The CLI does not replace a refused request with an empty successful result or another route.

Verification

stella reachability witness-ops verify <witness-record-guid> --format json

This online action uses Scanner’s configured verifier and records verification history. It requires separately authorized live access; source qualification performs no live verification. Only a coherent owner valid result returns exit zero. invalid, unsigned, unverified, missing or future statuses remain non-successful. An inconsistent valid result also remains non-successful. Output retains the owner’s status, error, witness identities, timestamp, envelope-presence flag and verifier key ID. isSigned records envelope presence and does not establish successful verification. Automation must check the command exit status as well as the returned fields.

Offline verification and caller-supplied public keys are unsupported. --offline and --public-key refuse before a request or key access. There is no local verifier or trust-policy override in this command.

Authorization and limits

Each supported request asks for canonical scanner:read and uses the existing CLI tenant resolver. Configured Authority/default tenant settings precede the ambient global --tenant value; the resolved header is trimmed and lower-cased. The server takes ordinary tenancy from the validated token claim. Only its existing global-admin rule permits the canonical header to select another tenant. A tenant header supplies no grant by itself.

The source-default owner routes are GET /api/v1/witnesses, GET /api/v1/witnesses/{witnessId} and POST /api/v1/witnesses/{witnessId}/verify. Operator configuration and gateway publication must match the qualified installation. Scanner also owns a separate by-hash read; this CLI command does not infer that route from a content ID.

Verdict/tier, reachable-only, probe-type and paging modes are unsupported. Recognized unsupported options return exit 9 before authorization, requests or domain output. Unknown options are parser errors. The discoverable export command returns exit 9 before requests or file access. Scanner serves no witness export or replay operation, and the CLI produces no synthetic download.

Later packaged/live acceptance needs the qualified CLI, Scanner and gateway revisions, approved CCP-075/059/060 inputs, a real retained witness and restricted/second-tenant access. A finding’s scan relation and unknown reachability establish neither witness presence nor witness absence.