Minctrl Docs
Guides

Audit export, SIEM sinks and evidence

Stream the hash-linked audit chain to Splunk, Datadog or a signed webhook without ever skipping an entry, export any range with its hashes and a verification manifest, hand an auditor an evidence pack, and anchor the chain head with an RFC 3161 timestamp.

Every governance event in Minctrl — a run started, a gate signed, a process saved, a connector or role changed, a sign-in — is an entry in a hash-linked audit chain: each entry's hash covers its content and the previous hash, so an edited or deleted entry breaks every link after it. This page covers getting that chain out: to your SIEM as it is written, to a file, to an auditor, and to an independent timestamp authority.

Everything here is on Settings → Audit & SIEM (/settings/audit) and in the API below. Any member may read the configuration; an owner or admin changes it, and every change is itself an entry in the chain.

Export a range

curl -H "Authorization: Bearer $TOKEN" \
  "$API/audit-chain/export?format=jsonl&from_seq=1&to_seq=500" -o chain.jsonl
parametermeaning
formatjson (default, one document), jsonl or csv (streamed row by row)
from_seqfirst entry (default 1)
to_seqlast entry (default: the head when the export starts — an export taken while the chain grows is a consistent snapshot)

Each row is {company_id, seq, created_at, kind, run_id, payload, prev_hash, hash}. The rows are re-hashed while they stream, and each one's link to the row before it is checked — the first row against the stored entry at from_seq - 1.

The last JSONL line is the manifest:

{"manifest": {"from_seq": 1, "to_seq": 500, "count": 500, "first_prev_hash": "",
  "head_hash": "9f2c…", "chain_head": {"seq": 512, "hash": "…"},
  "valid": true, "first_broken_seq": null, "verified_at": "2026-10-31T18:02:11Z"}}

A JSONL file without a manifest line is incomplete (the stream was cut) — never treat it as the whole range. For CSV, the manifest of the same range is GET /audit-chain/export/manifest?from_seq=…&to_seq=….

Recompute a hash yourself

hash = sha256(canonical_json({"c": company_id, "s": seq, "t": created_at, "r": run_id or "", "k": kind, "p": payload, "v": prev_hash})), where canonical JSON has sorted keys and no spaces (separators=(",", ":")). Nothing else is needed: an export verifies offline.

Send the chain to a SIEM

Add a sink with a preset:

kindURLcredentialwhat is sent
splunk_hechttps://<splunk>:8088/services/collector/eventHEC token (Authorization: Splunk <token>)one HEC event per entry; options index, sourcetype, source, host
datadoghttps://http-intake.logs.datadoghq.com/api/v2/logs (or your site's intake)API key (DD-API-KEY)a JSON array; the entry is under minctrl; options service, tags, source, host
webhookyour endpointHMAC secret{"company_id", "entries": [...]}, signed (below)
curl -X POST "$API/audit/sinks" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "Splunk prod", "kind": "splunk_hec",
       "url": "https://splunk.acme.com:8088/services/collector/event",
       "secret": "<HEC token>", "options": {"index": "minctrl"}, "start_from": "beginning"}'

start_from: "now" skips the history and delivers only what is written from now on.

The credential is write-only. It is stored encrypted (AES-256-GCM under MINCTRL_SECRETS_KEY, or a key derived from JWT_SECRET when that is unset — the same key as connector and SSO secrets) and no endpoint returns it — secret_set says whether one is stored. A credential that can no longer be decrypted (the key was rotated) shows as an error on the sink: enter it again with PATCH /audit/sinks/{id}.

Delivery: in order, never skipped, at least once

Each sink has a cursor — the last entry it accepted. A background worker in the API sends the entries after the cursor in order, in batches (AUDIT_SINK_BATCH, default 100), and:

  • the cursor moves only after the sink answered 2xx for the batch that ends at the new position. A non-2xx, a timeout, an unreadable chain or a lost lease leaves it where it was, and the next attempt resends the same entries. An outage delays delivery; it never skips an entry.
  • retries back off exponentially with jitter (about 5 s, 10 s, 20 s … up to 5 min);
  • a sink that has not accepted anything for an hour is marked failing — red on the settings page, and an audit_sink_failing entry in the chain (which reaches your other sinks). When it accepts again, audit_sink_recovered is recorded;
  • delivery is at-least-once: if the sink accepted a batch but the cursor update was lost, the batch comes again. Deduplicate on (company_id, seq) — or on hash.

Two API replicas share the work safely: a sink is leased (FOR UPDATE SKIP LOCKED) and the cursor is moved with a conditional update, so one batch is never sent by both at once.

POST /audit/sinks/{id}/test sends one synthetic event (kind: "minctrl_sink_test", seq: 0 — not a chain entry) with the stored credential and reports what the sink answered. It does not move the cursor.

Verify a webhook

Every webhook POST carries X-Minctrl-Timestamp (Unix seconds) and X-Minctrl-Signature: sha256=<hex>, where the hex is HMAC-SHA256(secret, timestamp + "." + body).

import hashlib, hmac, time

def verify(secret: bytes, body: bytes, ts: str, sig: str, tolerance: int = 300) -> bool:
    if abs(time.time() - int(ts)) > tolerance:
        return False  # a replay of an old delivery
    expected = hmac.new(secret, ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", sig)

Evidence pack

curl -X POST "$API/audit-chain/evidence-pack" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"from": "2026-07-01T00:00:00Z", "to": "2026-10-01T00:00:00Z"}' -o evidence.zip

A zip an auditor can check without access to Minctrl. Owners, admins, and an API key with the audit:read scope may generate one; each generation is recorded (evidence_pack_exported).

filecontents
manifest.jsonwho, when, the period, the chain range and head, and the SHA-256 of every other file
chain.jsonlthe entries of the period, ending with the range manifest
verification.jsonthe whole-chain walk, the period's range check, the timestamp tokens check
timestamps.json, timestamps/*.tsrevery TSA attempt, and each token as the TSA sent it
governance_policy.jsonseparation of duties, SLA timezone
members.jsonmembers and roles at generation time
processes.jsonevery process and version, and which versions runs of the period used
settings.jsonconnectors (live or shadowed — never their tokens), audit sinks and timestamping (never their secrets)
README.txthow to verify

Every section is read before the zip is written: if one cannot be read, the request fails rather than producing a pack that silently lacks it.

External timestamps (RFC 3161)

The chain is tamper-evident: an edit breaks the links. But someone with write access to the database could rewrite history and recompute every link after it. An external timestamp closes that: every interval, the hash of the chain head is sent to a Time-Stamp Authority, which signs "this hash existed at this time". Nobody can produce that signature over a rewritten head later.

curl -X PUT "$API/audit/timestamps/settings" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tsa_url": "https://freetsa.org/tsr", "interval_minutes": 60}'
  • The entry hash is already a SHA-256 over the entry's canonical content, so it is the message imprint as it stands — anyone can recompute it from an export.
  • A head that already has a token is not stamped again; a failed attempt is stored with its error and retried after 5 minutes. POST /audit/timestamps/stamp stamps now.
  • Each token is checked on receipt (granted, imprint, nonce, content digest, signature against the TSA's certificate) and stored as the DER TimeStampResp. Download one with GET /audit/timestamps/{id}/token.
  • GET /audit-chain/verify re-checks every token against the entry now stored at its seq. A mismatch makes the chain valid: false with first_broken_seq at that seq, and lists it under timestamps.mismatched_seqs.

Which TSA certificate to trust is your decision: the token's certificate fingerprint is stored (tsa_cert_sha256). Verify a token independently with OpenSSL:

openssl ts -reply -in minctrl-chain-7.tsr -text
openssl ts -verify -digest <entry hash> -in minctrl-chain-7.tsr -CAfile tsa-ca.pem

The job runs every AUDIT_TSA_TICK_SECONDS (default 60; it decides who is due — the interval is per company). With two replicas, a company is claimed with a conditional update, so it is stamped once.

Operating it

variabledefault
AUDIT_SINK_TICK_SECONDS10how often the delivery worker looks for due sinks; 0 turns it off
AUDIT_SINK_BATCH100entries per request (1–1000)
AUDIT_TSA_TICK_SECONDS60how often the timestamp job looks for due companies; 0 turns it off
MINCTRL_SECRETS_KEYderived from JWT_SECRETKey for every stored credential: sinks, connectors, SSO
CONNECTOR_ALLOW_PRIVATE_HOSTSoffallow sink and TSA URLs on private networks (on-prem); otherwise they are refused (SSRF guard)

A failing sink or TSA never takes the API down and never changes the chain: both background loops log a failed tick and go on.

On this page