Investigation and archive workflow, end to end

Relata DB 3.0
This page describes Relata DB 3.0, the current release. Paths use the new /v1 prefix; see the route restructure.

One path from raw events to an archived, later retrievable investigation record, composed only from existing routes. The repository exercises it with a test against the real binary over real HTTP, including a SIGKILL and an offline backup and restore. Single node, local disk.

URL=http://127.0.0.1:9090; H="Authorization: Bearer $TOKEN"; J='Content-Type: application/json'
  1. Ingest events.

    curl -X POST "$URL/v1/ingest?purpose=investigation&object_type=SecEvent" -H "$H" -H "$J" \
      -d '[{"id":"ev-1","host":"web-1","note":"psexec service installed"},{"id":"ev-2","host":"web-1","note":"psexec remote execution"}]'
  2. Search and record what the answer rested on. The header makes the server store a version-pinned citation record (retrieval evidence). The response returns hits and evidence.id. Indexing is asynchronous: retry until both hits appear.

    curl -X POST "$URL/v1/search" -H "$H" -H "$J" -H 'X-Relata-Record-Evidence: true' \
      -d '{"query":"psexec","type":"SecEvent"}'
  3. Record the findings as assertions that cite that evidence. POST /v1/assertions with "evidence":["<evidence.id>"]; a second, contradicting claim from another source; POST /v1/assertions/{id}/decision; POST /v1/assertions/relations (contradicts or supports); and POST /v1/assertions/{id}/assessment. GET /v1/assertions/{id}/evidence-graph returns the claims, their relations and the independent-origin summary.

  4. Archive the record. Assemble one JSON document (the evidence envelope from GET /v1/evidence/{id}, the graph, the assertion ids), record its SHA-256 and store it with PUT /v1/files/content?key=cases/INC-1/record.json. Place a hold on the underlying events with POST /v1/retention/holds and a body such as {"case_id":"INC-1","object_type":"SecEvent","field":"host","value":"web-1"}.

  5. Correct a source event by ingesting the row again. The previous version is kept: a query with AS OF SYSTEM TIME '<ns>' returns the original, and POST /v1/evidence/{id}/replay still reports the cited version as verified with superseded set.

  6. Archive the whole node with relata backup, and bring it back with relata restore <artefact> into a fresh data directory. See Backup and restore.

  7. Retrieve later, under policy. After the restore the file bytes hash to the recorded SHA-256 and the assertion graph, hold and as-of answers are unchanged. Evidence envelopes are private to the principal that recorded them and tokens are not part of a data-directory restore, so a new analyst gets 404 for the old envelope id. The archived record still carries it, and re-running its query with the evidence header produces a fresh envelope that replays as verified. With read withdrawn for the event and file types, replay reports denied, file download is refused and search returns no hits: archived data is never served around the caller's policy.

What this does not cover

  • Cold retrieval from object storage: a single local node writes no segments.
  • Vector and hybrid retrieval, which needs an embedder.
  • Clustered behaviour and tamper-evident audit archives (Enterprise).
  • Extracting claims from documents or media (OpenETL work). Assertions here are written by the caller.