stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
600f3a7a3cc47441484b201e372aed1bc5528d6e
git.stella-ops.org/docs/modules/graph/contracts/graph.inspect.v1.md
StellaOps Bot 600f3a7a3c
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details
Console CI / console-ci (push) Has been cancelled
Details
Export Center CI / export-ci (push) Has been cancelled
Details
feat(graph): introduce graph.inspect.v1 contract and schema for SBOM relationships 
- 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.
2025-12-04 09:36:59 +02:00

3.2 KiB
Raw Blame History

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

# 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).