79b8e53441
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.
56 lines
2.4 KiB
Markdown
56 lines
2.4 KiB
Markdown
# Policy Overlay Projection Contract (Draft) — PREP-POLICY-ENGINE-30-001
|
|
|
|
Status: Draft (2025-11-20)
|
|
Owners: Policy Guild · Cartographer Guild · Platform/Observability Guild
|
|
Scope: Define the overlay projection output that depends on metrics/logging outputs from POLICY-ENGINE-29-004. Intended to unblock POLICY-ENGINE-30-001 and downstream 30-00x tasks.
|
|
|
|
## 1) Inputs
|
|
- `policy_run_id` (required)
|
|
- `tenant_id` (required)
|
|
- Metrics/logging envelope from 29-004 (pending): expected fields include run duration, rule evaluation counts, fact ingest counts, cache hit/miss, scheduler job metadata.
|
|
- Optional: advisory/KB versions, SBOM/VEX digests, risk profile version.
|
|
|
|
## 2) Overlay projection shape (proposed)
|
|
```json
|
|
{
|
|
"overlay_id": "ulid",
|
|
"policy_run_id": "...",
|
|
"tenant_id": "...",
|
|
"generated_at": "2025-11-20T00:00:00Z",
|
|
"schema_version": "policy.overlay.v1",
|
|
"metrics": {
|
|
"duration_ms": 1234,
|
|
"rules_evaluated": 4200,
|
|
"facts_ingested": 98765,
|
|
"cache_hit_rate": 0.92,
|
|
"p95_rule_latency_ms": 8
|
|
},
|
|
"logs_pointer": "bundle://telemetry/logs.ndjson",
|
|
"inputs": {
|
|
"sbom_digest": "sha256:...",
|
|
"advisories_digest": "sha256:...",
|
|
"vex_digest": "sha256:..."
|
|
},
|
|
"provenance": {
|
|
"engine_version": "x.y.z",
|
|
"profile": "policy-default",
|
|
"scheduler_job_id": "..."
|
|
}
|
|
}
|
|
```
|
|
- Determinism: sorted keys; timestamps UTC; numeric metrics fixed to 3 decimal places where fractional.
|
|
- Overlay acts as the query surface for simulation/change events (30-002/30-003) and UI overlays.
|
|
|
|
## 3) Storage & API
|
|
- Stored as NDJSON under `overlays/{tenant_id}/{policy_run_id}.ndjson` in policy engine store; referenced by Export/Console bundle.
|
|
- API (proposed): `GET /policy-runs/{policy_run_id}/overlay` with ETag = sha256 of payload; `POST /policy-runs/{policy_run_id}/overlay/rebuild` for re-projection when metrics contract changes.
|
|
|
|
## 4) Open dependencies / decisions
|
|
- Need final metrics/logging schema from 29-004 to lock `metrics` section (owner: Platform/Observability).
|
|
- Confirm cache metrics naming and units.
|
|
- Confirm whether overlay should embed inline logs vs pointer.
|
|
- Clarify retention/GC policy for overlays (suggest 30d, aligned with export bundles).
|
|
|
|
## 5) Handoff
|
|
Use this document as the PREP artefact for POLICY-ENGINE-30-001. Update once 29-004 publishes metrics/logging outputs; then fix schema_version to `overlay.v1` and add JSON Schema under `docs/modules/policy/schemas/`.
|