47 lines
3.1 KiB
Markdown
47 lines
3.1 KiB
Markdown
# 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
|