save progress
This commit is contained in:
StellaOps Bot
316
docs/modules/provenance/architecture.md
Normal file
316
docs/modules/provenance/architecture.md
Normal file
@@ -0,0 +1,316 @@
|
||||
# component_architecture_provenance.md - **Stella Ops Provenance** (2025Q4)
|
||||
|
||||
> Provenance attestation library for SLSA/DSSE compliance.
|
||||
|
||||
> **Scope.** Library architecture for **Provenance**: shared libraries and tooling for generating, signing, and verifying provenance attestations (DSSE/SLSA). Used by evidence bundles, exports, and timeline verification flows.
|
||||
|
||||
---
|
||||
|
||||
## 0) Mission & boundaries
|
||||
|
||||
**Mission.** Provide **deterministic, verifiable provenance attestations** for all StellaOps artifacts. Enable SLSA compliance through DSSE statement generation, Merkle tree construction, and cryptographic verification.
|
||||
|
||||
**Boundaries.**
|
||||
|
||||
* Provenance is a **library**, not a standalone service.
|
||||
* Provenance **does not** store attestations. Storage is handled by Attestor and EvidenceLocker.
|
||||
* Provenance **does not** hold signing keys. Key management is delegated to Signer/KMS.
|
||||
* All attestation outputs are **deterministic** with canonical JSON serialization.
|
||||
|
||||
---
|
||||
|
||||
## 1) Solution & project layout
|
||||
|
||||
```
|
||||
src/Provenance/
|
||||
├─ StellaOps.Provenance.Attestation/ # Core attestation library
|
||||
│ ├─ AGENTS.md # Guild charter
|
||||
│ ├─ PromotionAttestation.cs # Promotion statement builder
|
||||
│ ├─ BuildModels.cs # SLSA build predicate models
|
||||
│ ├─ Signers.cs # Signer abstractions
|
||||
│ ├─ Verification.cs # Verification harness
|
||||
│ └─ Hex.cs # Hex encoding utilities
|
||||
│
|
||||
├─ StellaOps.Provenance.Attestation.Tool/ # CLI tool for attestation
|
||||
│ ├─ Program.cs
|
||||
│ └─ README.md
|
||||
│
|
||||
└─ __Tests/
|
||||
└─ StellaOps.Provenance.Attestation.Tests/
|
||||
├─ PromotionAttestationBuilderTests.cs
|
||||
├─ VerificationTests.cs
|
||||
├─ SignersTests.cs
|
||||
├─ MerkleTreeTests.cs
|
||||
└─ RotatingSignerTests.cs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2) External dependencies
|
||||
|
||||
* **Signer** - Cryptographic signing operations
|
||||
* **Cryptography** - Hash computation, signature algorithms
|
||||
* **EvidenceLocker** - Consumes attestations for storage
|
||||
* **ExportCenter** - Attaches attestations to export bundles
|
||||
* **.NET 10** - Runtime target
|
||||
|
||||
---
|
||||
|
||||
## 3) Contracts & data model
|
||||
|
||||
### 3.1 DSSE Statement
|
||||
|
||||
Dead Simple Signing Envelope (DSSE) format:
|
||||
|
||||
```json
|
||||
{
|
||||
"payloadType": "application/vnd.in-toto+json",
|
||||
"payload": "<base64-encoded-statement>",
|
||||
"signatures": [
|
||||
{
|
||||
"keyid": "sha256:abc123...",
|
||||
"sig": "<base64-signature>"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 SLSA Provenance Predicate
|
||||
|
||||
```json
|
||||
{
|
||||
"_type": "https://in-toto.io/Statement/v1",
|
||||
"subject": [
|
||||
{
|
||||
"name": "pkg:oci/scanner@sha256:abc123",
|
||||
"digest": { "sha256": "abc123..." }
|
||||
}
|
||||
],
|
||||
"predicateType": "https://slsa.dev/provenance/v1",
|
||||
"predicate": {
|
||||
"buildDefinition": {
|
||||
"buildType": "https://stellaops.dev/build/v1",
|
||||
"externalParameters": {},
|
||||
"internalParameters": {},
|
||||
"resolvedDependencies": []
|
||||
},
|
||||
"runDetails": {
|
||||
"builder": {
|
||||
"id": "https://stellaops.dev/builders/scanner"
|
||||
},
|
||||
"metadata": {
|
||||
"invocationId": "build-2025-01-15-abc123",
|
||||
"startedOn": "2025-01-15T10:30:00Z",
|
||||
"finishedOn": "2025-01-15T10:35:00Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 Promotion Attestation
|
||||
|
||||
For artifact promotion across environments:
|
||||
|
||||
```csharp
|
||||
public sealed class PromotionAttestation
|
||||
{
|
||||
public required string ArtifactDigest { get; init; }
|
||||
public required string SourceEnvironment { get; init; }
|
||||
public required string TargetEnvironment { get; init; }
|
||||
public required DateTimeOffset PromotedAt { get; init; }
|
||||
public required string ApprovedBy { get; init; }
|
||||
public required IReadOnlyList<string> PolicyDigests { get; init; }
|
||||
public string? MerkleRoot { get; init; }
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4) Core Components
|
||||
|
||||
### 4.1 Signer Abstractions
|
||||
|
||||
```csharp
|
||||
public interface IAttestationSigner
|
||||
{
|
||||
string KeyId { get; }
|
||||
string Algorithm { get; }
|
||||
|
||||
Task<byte[]> SignAsync(
|
||||
ReadOnlyMemory<byte> payload,
|
||||
CancellationToken ct);
|
||||
}
|
||||
|
||||
public interface IRotatingSigner : IAttestationSigner
|
||||
{
|
||||
DateTimeOffset KeyNotBefore { get; }
|
||||
DateTimeOffset KeyNotAfter { get; }
|
||||
Task<IAttestationSigner> GetCurrentSignerAsync(CancellationToken ct);
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 Verification Harness
|
||||
|
||||
```csharp
|
||||
public interface IAttestationVerifier
|
||||
{
|
||||
Task<VerificationResult> VerifyAsync(
|
||||
DsseEnvelope envelope,
|
||||
VerificationOptions options,
|
||||
CancellationToken ct);
|
||||
}
|
||||
|
||||
public sealed record VerificationResult
|
||||
{
|
||||
public required bool IsValid { get; init; }
|
||||
public required string KeyId { get; init; }
|
||||
public DateTimeOffset? SignedAt { get; init; }
|
||||
public IReadOnlyList<string>? Warnings { get; init; }
|
||||
public string? ErrorMessage { get; init; }
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 Merkle Tree Utilities
|
||||
|
||||
For evidence chain verification:
|
||||
|
||||
```csharp
|
||||
public static class MerkleTree
|
||||
{
|
||||
public static string ComputeRoot(IEnumerable<string> leaves);
|
||||
public static IReadOnlyList<string> ComputePath(
|
||||
IReadOnlyList<string> leaves,
|
||||
int leafIndex);
|
||||
public static bool VerifyPath(
|
||||
string leaf,
|
||||
IReadOnlyList<string> path,
|
||||
string root);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5) CLI Tool
|
||||
|
||||
`StellaOps.Provenance.Attestation.Tool` provides CLI commands:
|
||||
|
||||
```bash
|
||||
# Generate provenance attestation
|
||||
provenance-tool generate \
|
||||
--subject "pkg:oci/scanner@sha256:abc123" \
|
||||
--builder "stellaops/ci" \
|
||||
--output attestation.json
|
||||
|
||||
# Sign attestation
|
||||
provenance-tool sign \
|
||||
--input attestation.json \
|
||||
--key-id "kms://keys/signing-key" \
|
||||
--output attestation.dsse.json
|
||||
|
||||
# Verify attestation
|
||||
provenance-tool verify \
|
||||
--input attestation.dsse.json \
|
||||
--trust-root trust-bundle.json
|
||||
|
||||
# Generate promotion attestation
|
||||
provenance-tool promote \
|
||||
--artifact "sha256:abc123" \
|
||||
--from staging \
|
||||
--to production \
|
||||
--approver "user@example.com"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6) Security & compliance
|
||||
|
||||
* **SLSA L3 compliance**: Build provenance with hermetic builds
|
||||
* **Key rotation**: RotatingSigner supports key rotation with overlap
|
||||
* **Determinism**: Canonical JSON ensures reproducible digests
|
||||
* **Offline verification**: Trust bundles for air-gapped verification
|
||||
* **Threat model**: Reviewed before each release
|
||||
|
||||
---
|
||||
|
||||
## 7) Performance targets
|
||||
|
||||
* **Statement generation**: < 10ms for typical attestation
|
||||
* **Signing**: Depends on KMS (target < 100ms for HSM)
|
||||
* **Verification**: < 50ms for single signature
|
||||
* **Merkle root**: < 100ms for 10,000 leaves
|
||||
|
||||
---
|
||||
|
||||
## 8) Testing matrix
|
||||
|
||||
* **Serialization tests**: Deterministic JSON output across runs
|
||||
* **Signing tests**: Round-trip sign/verify
|
||||
* **Merkle tests**: Path generation and verification
|
||||
* **Rotation tests**: Key rotation with overlap handling
|
||||
* **Integration tests**: Full attestation flow with mock KMS
|
||||
|
||||
---
|
||||
|
||||
## 9) Sample Artifacts
|
||||
|
||||
Samples committed under `samples/provenance/`:
|
||||
|
||||
```
|
||||
samples/provenance/
|
||||
├─ slsa-provenance-v1.json # Sample SLSA statement
|
||||
├─ promotion-attestation.json # Sample promotion
|
||||
├─ trust-bundle.json # Sample trust root
|
||||
└─ verify-example.sh # Verification script
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10) Integration Points
|
||||
|
||||
### 10.1 EvidenceLocker
|
||||
|
||||
Evidence bundles include attestations:
|
||||
|
||||
```json
|
||||
{
|
||||
"bundleId": "eb-2025-01-15-abc123",
|
||||
"attestations": [
|
||||
{
|
||||
"type": "slsa-provenance",
|
||||
"dsse": { /* DSSE envelope */ }
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 10.2 ExportCenter
|
||||
|
||||
Exports attach attestations to manifests:
|
||||
|
||||
```json
|
||||
{
|
||||
"exportId": "export-abc123",
|
||||
"manifest": { /* export manifest */ },
|
||||
"attestation": { /* DSSE envelope */ }
|
||||
}
|
||||
```
|
||||
|
||||
### 10.3 CLI
|
||||
|
||||
Scanner and other tools generate attestations:
|
||||
|
||||
```bash
|
||||
stella scan image:tag --attest --output sbom.cdx.json
|
||||
# Produces sbom.cdx.json + sbom.cdx.json.dsse
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
* Attestor architecture: `../attestor/architecture.md`
|
||||
* Signer architecture: `../signer/architecture.md`
|
||||
* EvidenceLocker: `../evidence-locker/architecture.md`
|
||||
* SLSA specification: https://slsa.dev/provenance/v1
|
||||
* DSSE specification: https://github.com/secure-systems-lab/dsse
|
||||
Reference in New Issue
Block a user