600f3a7a3c
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
Console CI / console-ci (push) Has been cancelled
Export Center CI / export-ci (push) Has been cancelled
- Added graph.inspect.v1 documentation outlining payload structure and determinism rules. - Created JSON schema for graph.inspect.v1 to enforce payload validation. - Defined mapping rules for graph relationships, advisories, and VEX statements. feat(notifications): establish remediation blueprint for gaps NR1-NR10 - Documented requirements, evidence, and tests for Notifier runtime. - Specified deliverables and next steps for addressing identified gaps. docs(notifications): organize operations and schemas documentation - Created README files for operations, schemas, and security notes to clarify deliverables and policies. feat(advisory): implement PostgreSQL caching for Link-Not-Merge linksets - Created database schema for advisory linkset cache. - Developed repository for managing advisory linkset cache operations. - Added tests to ensure correct functionality of the AdvisoryLinksetCacheRepository.
49 lines
3.2 KiB
Markdown
49 lines
3.2 KiB
Markdown
# graph.inspect.v1 · Inspector Contract (2025-12-04)
|
|
|
|
Replaces the archived Cartographer handshake note and grounds the Concelier/Excititor → Graph Indexer/API interface. Use this shape for any inspector payloads that carry SBOM relationships plus advisory/VEX linkouts destined for graph ingestion or replay.
|
|
|
|
## Purpose
|
|
- Give Concelier (Link-Not-Merge v1) and Excititor a frozen, deterministic payload so graph nodes/edges can be regenerated or replayed offline.
|
|
- Encode the evidence hashes and provenance needed for append-only rebuilds and audit trails.
|
|
- Keep ordering stable to avoid hash churn between runs.
|
|
|
|
## Payload shape (summary)
|
|
- `schemaVersion` — must be `graph.inspect.v1`.
|
|
- `tenant`, `artifactDigest`, `sbomDigest`, `collectedAt`.
|
|
- `components[]` (ordered):
|
|
- `purl`, optional `version`, optional sorted `scopes[]`.
|
|
- `relationships[]` → `contains|depends_on|provides|runtime_observed` with `targetPurl`, `scope?`, `source`, `evidenceHash`.
|
|
- `advisories[]` → `advisoryId`, `source`, `status`, `severity?`, `cvss?`, `justification?`, `linksetDigest?`, `evidenceHash`, `modifiedAt`.
|
|
- `vexStatements[]` → `statementId`, `source`, `status`, `justification`, `impactStatement?`, `knownExploited?`, `issuedAt`, `expiresAt?`, `evidenceHash`.
|
|
- `provenance` → `source`, `collectedAt`, `eventOffset?`, `linksetDigest?`, `evidenceHash?`.
|
|
- Optional `links.sbomObservationEventId` and `links.linksetDigest` for traceability.
|
|
|
|
Full machine-readable schema: `docs/modules/graph/contracts/graph.inspect.v1.schema.json`.
|
|
|
|
## Determinism rules
|
|
- Preserve input order for `components[]` and `relationships[]`; sort `scopes`, `advisories`, and `vexStatements` by (`source`, `advisoryId`/`statementId`) before emitting.
|
|
- All timestamps UTC ISO-8601; hashes are SHA-256 hex.
|
|
- Keep arrays unique where noted (`scopes`), and avoid null/empty strings.
|
|
|
|
## Graph mapping
|
|
- `relationships` → graph edges: `contains/depends_on/provides/runtime_observed` align with `CONTAINS`, `DEPENDS_ON`, `PROVIDES`, `OBSERVED_RUNTIME`.
|
|
- `advisories` → `advisory` nodes + `AFFECTED_BY` edges (use `linksetDigest` and `evidenceHash` for provenance).
|
|
- `vexStatements` → `vex_statement` nodes + `VEX_EXEMPTS` edges (propagate `justification`, `knownExploited`, `impactStatement`).
|
|
- `provenance` fields flow into graph `provenance` objects and `eventOffset` becomes the replay cursor.
|
|
|
|
## Validation
|
|
```sh
|
|
# Example (offline-friendly if ajv is already installed locally)
|
|
ajv validate -s docs/modules/graph/contracts/graph.inspect.v1.schema.json \
|
|
-d docs/modules/graph/contracts/examples/graph.inspect.v1.sample.json
|
|
```
|
|
Use any JSON Schema Draft 2020-12 validator if `ajv` is unavailable.
|
|
|
|
## Sample
|
|
See `docs/modules/graph/contracts/examples/graph.inspect.v1.sample.json` for a one-component payload that exercises relationships, advisory observations, VEX statements, and provenance fields.
|
|
|
|
## Upstream alignment
|
|
- Link-Not-Merge fixtures: `docs/modules/concelier/link-not-merge-schema.md`.
|
|
- Excititor overlay prep: `docs/modules/excititor/prep/2025-11-20-graph-21-001-prep.md` and `...graph-21-002-prep.md`.
|
|
- Graph canonical model: `docs/modules/graph/schema.md` (node/edge taxonomy the inspector feeds).
|