107 lines
5.8 KiB
Markdown
107 lines
5.8 KiB
Markdown
# 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
|
|
|
|
1. Operator provides a bundle file path and optional trust profile (key whitelist) via CLI arguments.
|
|
2. Verifier extracts the bundle to a temporary directory.
|
|
3. The manifest is loaded and parsed.
|
|
4. The DSSE signature on the manifest is verified against the trust profile's allowed public keys.
|
|
5. Any RFC 3161 timestamps are validated for structural and cryptographic correctness.
|
|
6. SHA-256 digests are recomputed for every file referenced in the manifest and compared to the declared values.
|
|
7. Each SBOM/DSSE pair is validated for internal consistency.
|
|
8. 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.
|