stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
c2b9cd8d1f1a81af32c757063a460815ff4949a4
git.stella-ops.org/docs/modules/provenance/architecture.md

7.9 KiB
Raw Blame History

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:

{
  "payloadType": "application/vnd.in-toto+json",
  "payload": "<base64-encoded-statement>",
  "signatures": [
    {
      "keyid": "sha256:abc123...",
      "sig": "<base64-signature>"
    }
  ]
}

3.2 SLSA Provenance Predicate

{
  "_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:

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

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

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:

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:

# 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:

{
  "bundleId": "eb-2025-01-15-abc123",
  "attestations": [
    {
      "type": "slsa-provenance",
      "dsse": { /* DSSE envelope */ }
    }
  ]
}

10.2 ExportCenter

Exports attach attestations to manifests:

{
  "exportId": "export-abc123",
  "manifest": { /* export manifest */ },
  "attestation": { /* DSSE envelope */ }
}

10.3 CLI

Scanner and other tools generate attestations:

stella scan image:tag --attest --output sbom.cdx.json
# Produces sbom.cdx.json + sbom.cdx.json.dsse

Related Documentation