Verifier Architecture

Standalone, offline-first CLI tool for cryptographic verification of evidence bundles.

Overview

Verifier is a single-project, self-contained .NET CLI application published as a trimmed, single-file binary for multiple platforms. It takes an evidence bundle (a gzipped tar archive) as input, extracts it, and runs a six-stage verification pipeline that validates the manifest, signatures, timestamps, digests, and SBOM/DSSE pair integrity. The tool requires no network access, no database, and no running Stella Ops services.

Components

src/Verifier/
  Verifier/                          # Single project (self-contained CLI)
    Program.cs                       # Entry point and CLI argument parsing
    BundleExtractor.cs               # gzip+tar extraction
    ManifestLoader.cs                # manifest.json parsing and validation
    SignatureVerifier.cs             # DSSE signature verification
    TimestampVerifier.cs             # RFC 3161 timestamp verification
    DigestVerifier.cs                # SHA-256 digest checking
    PairVerifier.cs                  # SBOM + DSSE pair matching
    TrustProfile.cs                  # Trusted key whitelisting
    OutputFormatter.cs               # Text / JSON / Markdown output

Bundle Format

The input evidence bundle is a gzipped tar archive with the following structure:

bundle.tar.gz
  manifest.json                      # Bundle manifest (pairs, metadata, digests)
  manifest.json.sig                  # DSSE signature over the manifest
  pairs/
    {pairId}/
      sbom.spdx.json                 # SPDX SBOM document
      delta-sig.dsse.json            # DSSE envelope for the delta signature
    {pairId}/
      ...
  timestamps/                        # Optional RFC 3161 timestamps
    *.tsr                            # Timestamp request files
    *.tst                            # Timestamp token files

Verification Pipeline

The verification pipeline executes six stages sequentially. Each stage must pass before the next begins:

Stage	Name	Description
1	Extract bundle	Decompress gzip, unpack tar to temporary directory
2	Load manifest	Parse `manifest.json`, validate required fields and structure
3	Signature verification	Verify `manifest.json.sig` DSSE signature against trusted key list
4	Timestamp verification	Validate RFC 3161 timestamp tokens (`.tsr`/`.tst`) if present
5	Digest verification	Recompute SHA-256 digests for all referenced files, compare to manifest
6	Pair verification	Verify each SBOM + DSSE pair matches and is internally consistent

Data Flow

Operator provides a bundle file path and optional trust profile (key whitelist) via CLI arguments.
Verifier extracts the bundle to a temporary directory.
The manifest is loaded and parsed.
The DSSE signature on the manifest is verified against the trust profile's allowed public keys.
Any RFC 3161 timestamps are validated for structural and cryptographic correctness.
SHA-256 digests are recomputed for every file referenced in the manifest and compared to the declared values.
Each SBOM/DSSE pair is validated for internal consistency.
A verification report is written to stdout in the requested format (text, JSON, or markdown).

Database Schema

Not applicable. Verifier is a standalone CLI tool with no persistent storage.

Endpoints

Not applicable. Verifier is a CLI tool with no HTTP endpoints.

Cross-Platform Targets

Runtime Identifier	Platform
`win-x64`	Windows x64
`linux-x64`	Linux x64 (glibc)
`linux-musl-x64`	Linux x64 (musl/Alpine)
`osx-x64`	macOS x64 (Intel)
`osx-arm64`	macOS ARM64 (Apple Silicon)

All targets produce a single-file, self-contained, trimmed binary with no external runtime dependencies.

Dependencies

Library	Purpose
System.CommandLine	CLI argument parsing and help generation
System.Security.Cryptography	SHA-256, RSA/ECDSA signature verification
System.Formats.Tar	Tar archive extraction
System.IO.Compression	Gzip decompression
System.Text.Json	JSON parsing for manifests and DSSE envelopes
BouncyCastle (optional)	Extended algorithm support (SM2, EdDSA)

Security Considerations

Air-gap first: Verifier requires no network access. All verification is performed locally using only the bundle contents and the trust profile.
No key export or generation: Verifier only reads public keys from the trust profile; it never generates or exports key material.
Trust profiles: Operators define which public keys are trusted for signature verification via a key whitelist file. Bundles signed by unknown keys are rejected.
Deterministic output: Given the same bundle and trust profile, Verifier produces identical verification results, supporting audit reproducibility.
Temporary file cleanup: Extracted bundle contents are written to a temporary directory and cleaned up after verification completes, minimizing residual data on disk.
No code execution: Verifier does not execute any code or scripts from within the bundle. It only reads and verifies data.

5.8 KiB Raw Permalink Blame History