45 lines
2.6 KiB
Markdown
45 lines
2.6 KiB
Markdown
# Policy Engine · Path/Scope Schema Prep (POLICY-ENGINE-29-002)
|
|
|
|
- **Date:** 2025-11-20
|
|
- **Working directory:** `src/Policy/StellaOps.Policy.Engine`
|
|
- **Purpose:** Unblock path-aware evaluation chain (tasks 29-003/004 and overlays 30-001..30-003) by freezing the canonical path/scope schema and examples.
|
|
|
|
## Schema (authoritative fields)
|
|
`PathScope` object used across evaluator inputs, telemetry, and snapshots:
|
|
- `tenant` (string, required) — tenant isolation key.
|
|
- `subject` (object) — affected asset:
|
|
- `purl` (string) or `cpe` (string) — at least one required.
|
|
- `packagePath` (string, optional) — normalized module path within package (e.g., `lib/utils/a.js`).
|
|
- `osImage` (string, optional) — container image ref if OS-level advisory.
|
|
- `locator` (object) — where evidence was found:
|
|
- `filePath` (string, required) — repo or image path using POSIX separators.
|
|
- `digest` (string, optional) — SHA-256 of file content; hex, lowercase.
|
|
- `treeDigest` (string, optional) — Merkle root for build tree snapshot.
|
|
- `vulnerability` (object) — identifiers present in evidence (facts only): `cve`, `ghsa`, `osv`, `advisoryId`, `source`.
|
|
- `provenance` (object) — `ingestedAt` (ISO-8601 UTC), `evidenceHash` (hex), `connectorId` (string), `dsseEnvelopeHash` (optional hex) for replay.
|
|
- `scope` (object) — evaluation bounding box:
|
|
- `pathMatch` (enum) `exact|prefix|glob` with `pattern` (string) using POSIX separators.
|
|
- `confidence` (float 0..1) — how confident the analyzer is about the path binding.
|
|
- `depthLimit` (int, optional) — maximum traversal depth for prefix/glob bindings.
|
|
|
|
## Determinism
|
|
- Canonical ordering: subject fields ordered as listed; pathMatch evaluation uses lexical order, then `confidence` desc, then `filePath` asc for tie-breaking.
|
|
- Hashing: `evidenceHash` = SHA-256 over normalized JSON of the observation with sorted properties and UTF-8 encoding.
|
|
|
|
## Sample payload
|
|
```json
|
|
{
|
|
"tenant": "acme",
|
|
"subject": {"purl": "pkg:npm/lodash@4.17.21", "packagePath": "lib/isEqual.js"},
|
|
"locator": {"filePath": "src/lib/isEqual.js", "digest": "c1ab..."},
|
|
"vulnerability": {"ghsa": "GHSA-35jh-r3h4-6jhm", "source": "ghsa"},
|
|
"provenance": {"ingestedAt": "2025-11-20T00:00:00Z", "evidenceHash": "4f9b...", "connectorId": "excititor-ghsa"},
|
|
"scope": {"pathMatch": "prefix", "pattern": "src/lib/", "confidence": 0.92, "depthLimit": 3}
|
|
}
|
|
```
|
|
|
|
## Acceptance for prep completion
|
|
- Path/Scope schema above is frozen for sprint 0125; downstream tasks must align or update this doc and sprint risks if changes occur.
|
|
- Sample payload provided for fixtures/tests; hashing and ordering rules documented for determinism.
|
|
|