stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
b83aa1aa0b040cb378c02c24a4082c1aa34a68ac
git.stella-ops.org/docs/modules/excititor/observability/timeline-events.md
StellaOps Bot 150b3730ef
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details
Mirror Thin Bundle Sign & Verify / mirror-sign (push) Has been cancelled
Details
api-governance / spectral-lint (push) Has been cancelled
Details
up
2025-11-24 07:52:25 +02:00

1.7 KiB
Raw Blame History

Excititor Timeline Events (OBS-52-001)

Defines the event envelope for evidence timelines emitted by Excititor. All fields are aggregation-only; no consensus/merge logic.

Envelope

{
  "type": "excititor.timeline.v1",
  "tenant": "default",
  "eventId": "urn:uuid:...",
  "timestamp": "2025-11-23T23:10:00Z",
  "traceId": "beefcafe...",
  "spanId": "deadb33f...",
  "source": "excititor.web",
  "kind": "observation|linkset",
  "action": "ingest|update|backfill|replay",
  "observationId": "vex:obs:sha256:...",
  "linksetId": "CVE-2024-0001:pkg:maven/org.demo/app@1.2.3",
  "justifications": ["component_not_present"],
  "conflicts": [
    {"providerId": "suse-csaf", "status": "fixed", "justification": null}
  ],
  "evidenceHash": "sha256:...",        // content-addressed payload hash
  "dsseEnvelopeHash": "sha256:...",    // if attested (see OBS-54-001)
  "metadata": {"connector": "ubuntu-csaf", "mirrorGeneration": 12}
}

Semantics

  • eventId is stable per write; retries reuse the same ID.
  • timestamp must be UTC; derive from TimeProvider.
  • traceId/spanId propagate ingestion traces; if tracing is disabled, set both to null.
  • kind + action drive downstream storage and alerting.
  • evidenceHash is the raw document hash; dsseEnvelopeHash appears only when OBS-54-001 is enabled.

Determinism

  • Sort justifications and conflicts ascending by providerId/status before emit.
  • Emit at-most-once per storage write; idempotent consumers rely on (eventId, tenant).

Transport

  • Default topic: excititor.timeline.v1 (NATS/Redis). Subject includes tenant: excititor.timeline.v1.<tenant>.
  • Payload size should stay <32 KiB; truncate conflict arrays with truncated=true flag if needed (keep hash counts deterministic).