Add new features and tests for AirGap and Time modules
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- Introduced `SbomService` tasks documentation. - Updated `StellaOps.sln` to include new projects: `StellaOps.AirGap.Time` and `StellaOps.AirGap.Importer`. - Added unit tests for `BundleImportPlanner`, `DsseVerifier`, `ImportValidator`, and other components in the `StellaOps.AirGap.Importer.Tests` namespace. - Implemented `InMemoryBundleRepositories` for testing bundle catalog and item repositories. - Created `MerkleRootCalculator`, `RootRotationPolicy`, and `TufMetadataValidator` tests. - Developed `StalenessCalculator` and `TimeAnchorLoader` tests in the `StellaOps.AirGap.Time.Tests` namespace. - Added `fetch-sbomservice-deps.sh` script for offline dependency fetching.
This commit is contained in:
55
docs/modules/policy/design/export-console-bundle-contract.md
Normal file
55
docs/modules/policy/design/export-console-bundle-contract.md
Normal file
@@ -0,0 +1,55 @@
|
||||
# Export Console Bundle Contract (Draft) — PREP-EXPORT-CONSOLE-23-001
|
||||
|
||||
Status: Draft (2025-11-20)
|
||||
Owners: Policy Guild · Scheduler Guild · Observability Guild
|
||||
Scope: Define the evidence bundle exported by Policy Engine for Console replay/verification and the scheduler job contract that produces it.
|
||||
|
||||
## 1) Manifest format
|
||||
- Container: tar.gz (deterministic ordering, UTC mtime `1970-01-01T00:00:00Z`), content-addressed by SHA-256 of archive bytes.
|
||||
- Root manifest: `bundle.manifest.json` (unsigned) and `bundle.manifest.dsse` (signed, optional until Rekor/Authority hookup).
|
||||
- `bundle.manifest.json` fields:
|
||||
- `bundle_id` (string, required): GUID/ULID assigned by Policy Engine.
|
||||
- `policy_run_id` (string, required): ID of originating policy run.
|
||||
- `tenant_id` (string, required): tenant scope.
|
||||
- `policy_version` (string, required): semantic version or commit hash of the policy set evaluated.
|
||||
- `inputs_hash` (hex): SHA-256 of normalized inputs (SBOM, advisories, VEX) used for the run.
|
||||
- `generated_at` (string, RFC3339 UTC): timestamp of bundle creation.
|
||||
- `schema_version` (string): `policy.export.console.v1`.
|
||||
- `artifacts`: array of artefact descriptors with `{path, media_type, sha256, purpose}`; expected purposes: `policy-run-summary`, `effective-findings`, `inputs`, `logs`, `metrics`.
|
||||
- `signatures`: optional array referencing DSSE statement(s) with signer identity and key hint.
|
||||
|
||||
## 2) Artefact layout
|
||||
- `summary/policy-run.json`: minimal run summary (status, duration, rule counts, decision stats).
|
||||
- `findings/effective.ndjson`: deterministic NDJSON list of effective findings emitted by the run (sorted by `finding_id`).
|
||||
- `inputs/sbom/*.json`: normalized SBOM slices (content-addressed references pointing back to source digests).
|
||||
- `inputs/advisories/*.json`: advisories snapshot used during evaluation.
|
||||
- `inputs/vex/*.json`: VEX statements snapshot.
|
||||
- `telemetry/logs.ndjson`: structured logs with correlation IDs and runner metadata (no secrets, scrub file paths).
|
||||
- `telemetry/metrics.json`: counters/histograms for run (p50/p95 latency, evaluated rules, facts ingested).
|
||||
|
||||
## 3) Scheduler job contract
|
||||
- Job type: `policy.export.console`.
|
||||
- Inputs:
|
||||
- `policy_run_id` (required)
|
||||
- `tenant_id` (required)
|
||||
- `priority` (enum: background|interactive; default background)
|
||||
- `include_logs` (bool, default true)
|
||||
- Outputs:
|
||||
- `bundle_pointer` (URI/path) to stored bundle in Evidence Locker/Export Center bucket.
|
||||
- `bundle_id`, `sha256`.
|
||||
- Events:
|
||||
- Progress events to Observability stream `{job_id, state, percent, bundle_id?, error?}`.
|
||||
- Completion emits `policy.export.console.completed` with bundle metadata for Console ingestion.
|
||||
|
||||
## 4) Determinism & security
|
||||
- All NDJSON/JSON sorted by stable keys; floats avoided; timestamps UTC RFC3339.
|
||||
- No inline PII; tenant-scoped file paths must be redacted or normalized.
|
||||
- Offline-friendly: no external references; all URIs either `bundle://` or content hashes.
|
||||
|
||||
## 5) Open items / decisions needed
|
||||
- Signer identity and DSSE profile (Rekor optional) — awaiting Authority/Attestor alignment.
|
||||
- Exact location for bundle storage (Evidence Locker vs Export Center) — propose Evidence Locker namespace `policy-console/` with retention 30d.
|
||||
- Metrics schema: align with Observability guild’s latest counters/histogram names.
|
||||
|
||||
## 6) Handoff
|
||||
Cite this file in sprint trackers for PREP-EXPORT-CONSOLE-23-001. When upstream decisions land, update schema_version and finalize DSSE profile.
|
||||
Reference in New Issue
Block a user