stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

consolidation of some of the modules, localization fixes, product advisories work, qa work

Browse Source
This commit is contained in:
master
2026-03-05 03:54:22 +02:00
parent 7bafcc3eef
commit 8e1cb9448d
3878 changed files with 72600 additions and 46861 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
docs-archived/modules/verifier/README.md Normal file
View File

@@ -0,0 +1,40 @@
# Verifier
> Standalone CLI tool for offline verification of evidence bundles in air-gapped environments.
## Purpose
Verifier is a self-contained, cross-platform CLI binary that validates evidence bundles without requiring network access or external dependencies. It checks DSSE signatures, RFC 3161 timestamps, SHA-256 digests, and SBOM integrity, enabling compliance verification in air-gapped environments where no Stella Ops services are reachable.
## Quick Links
- [Architecture](./architecture.md)
## Status
| Attribute | Value |
|-------------|---------------------|
| **Maturity** | Production |
| **Source** | `src/Verifier/` |
## Key Features
- Self-contained single-file binary (cross-platform: win-x64, linux-x64, linux-musl-x64, osx-x64, osx-arm64)
- Bundle extraction (gzip+tar)
- Manifest validation
- DSSE signature verification
- RFC 3161 timestamp verification
- SHA-256 digest checking
- Trust profile support (key whitelisting)
- Output formats (text/JSON/markdown)
## Dependencies
### Upstream
- None (standalone, offline-first design with zero runtime dependencies on Stella Ops services)
### Downstream
- AirGap - offline bundle verification workflows
- CLI - integrated verification commands for operator use

106
docs-archived/modules/verifier/architecture.md Normal file
View File

@@ -0,0 +1,106 @@
# 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.