stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
cf5b72974f923126944f4dcd47e85864ebb31a3b
git.stella-ops.org/docs/features/unchecked/policy/knowledge-snapshot-manifest.md

3.1 KiB
Raw Blame History

Knowledge Snapshot Manifest

Module

Policy

Status

IMPLEMENTED

Description

Knowledge Snapshot Manifest as a content-addressed sealed record containing source descriptors with hashes/digests, policy IDs, engine versions, plugin versions, and trust anchor set hashes.

Implementation Details

  • KnowledgeSnapshotManifest: src/Policy/__Libraries/StellaOps.Policy/Snapshots/KnowledgeSnapshotManifest.cs (sealed record)
    • SnapshotId: content-addressed ksm:sha256:{hash}
    • CreatedAt (UTC timestamp)
    • Engine: EngineInfo record (Name, Version, Commit)
    • Plugins: list of PluginInfo records (Name, Version, Type)
    • Policy: PolicyBundleRef record (PolicyId, Digest, Uri)
    • Scoring: ScoringRulesRef record (RulesId, Digest, Uri)
    • Trust: TrustBundleRef record (BundleId, Digest, Uri) -- optional
    • Sources: list of KnowledgeSourceDescriptor -- all knowledge inputs
    • Environment: DeterminismProfile record (TimezoneOffset, Locale, Platform, EnvironmentVars)
    • Signature: optional DSSE signature over the manifest
    • ManifestVersion: "1.0"
  • KnowledgeSourceDescriptor: src/Policy/__Libraries/StellaOps.Policy/Snapshots/KnowledgeSourceDescriptor.cs (sealed record)
    • Name, Type ("advisory-feed", "vex", "sbom", "reachability", "policy"), Epoch, Digest, Origin, LastUpdatedAt, RecordCount
    • InclusionMode: Referenced (digest only), Bundled (embedded), BundledCompressed
    • BundlePath for embedded sources
    • Well-known types in KnowledgeSourceTypes static class: AdvisoryFeed, Vex, Sbom, Reachability, Policy
  • SnapshotBuilder: src/Policy/__Libraries/StellaOps.Policy/Snapshots/SnapshotBuilder.cs -- fluent builder for constructing snapshots
  • SnapshotIdGenerator: src/Policy/__Libraries/StellaOps.Policy/Snapshots/SnapshotIdGenerator.cs -- content-addressed ID generation
  • SnapshotService: src/Policy/__Libraries/StellaOps.Policy/Snapshots/SnapshotService.cs -- snapshot lifecycle management
  • SnapshotAwarePolicyEvaluator: src/Policy/__Libraries/StellaOps.Policy/Snapshots/SnapshotAwarePolicyEvaluator.cs -- evaluates policy using pinned snapshot inputs

E2E Test Plan

  • Build snapshot with 3 knowledge sources (NVD advisory-feed, vendor VEX, SBOM); verify SnapshotId is content-addressed ksm:sha256:...
  • Build snapshot; change one source digest; rebuild; verify SnapshotId changes (content-addressed)
  • Build identical snapshot twice; verify SnapshotId is identical (deterministic)
  • Verify Engine field contains correct Name, Version, and Commit
  • Add 2 plugins to snapshot; verify Plugins list contains both with correct Name/Version/Type
  • Set Policy.Digest and Scoring.Digest; verify PolicyBundleRef and ScoringRulesRef are populated
  • Set Trust.BundleId and Trust.Digest; verify TrustBundleRef is populated
  • Add source with InclusionMode=Bundled; verify BundlePath is set
  • Add source with InclusionMode=Referenced; verify BundlePath is null
  • Set Environment DeterminismProfile; verify TimezoneOffset, Locale, Platform are captured
  • Use SnapshotAwarePolicyEvaluator with snapshot; verify evaluation uses pinned source data