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| parameter | meaning |
|---|---|
format | json (default, one document), jsonl or csv (streamed row by row) |
from_seq | first entry (default 1) |
to_seq | last 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:
| kind | URL | credential | what is sent |
|---|---|---|---|
splunk_hec | https://<splunk>:8088/services/collector/event | HEC token (Authorization: Splunk <token>) | one HEC event per entry; options index, sourcetype, source, host |
datadog | https://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 |
webhook | your endpoint | HMAC 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_failingentry in the chain (which reaches your other sinks). When it accepts again,audit_sink_recoveredis 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 onhash.
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.zipA 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).
| file | contents |
|---|---|
manifest.json | who, when, the period, the chain range and head, and the SHA-256 of every other file |
chain.jsonl | the entries of the period, ending with the range manifest |
verification.json | the whole-chain walk, the period's range check, the timestamp tokens check |
timestamps.json, timestamps/*.tsr | every TSA attempt, and each token as the TSA sent it |
governance_policy.json | separation of duties, SLA timezone |
members.json | members and roles at generation time |
processes.json | every process and version, and which versions runs of the period used |
settings.json | connectors (live or shadowed — never their tokens), audit sinks and timestamping (never their secrets) |
README.txt | how 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/stampstamps 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 withGET /audit/timestamps/{id}/token. GET /audit-chain/verifyre-checks every token against the entry now stored at its seq. A mismatch makes the chainvalid: falsewithfirst_broken_seqat that seq, and lists it undertimestamps.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.pemThe 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
| variable | default | |
|---|---|---|
AUDIT_SINK_TICK_SECONDS | 10 | how often the delivery worker looks for due sinks; 0 turns it off |
AUDIT_SINK_BATCH | 100 | entries per request (1–1000) |
AUDIT_TSA_TICK_SECONDS | 60 | how often the timestamp job looks for due companies; 0 turns it off |
MINCTRL_SECRETS_KEY | derived from JWT_SECRET | Key for every stored credential: sinks, connectors, SSO |
CONNECTOR_ALLOW_PRIVATE_HOSTS | off | allow 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.
Embedding and white-label
Put the sign-off queue or one run inside your own product with short-lived embed tokens, brand the widgets, emails and sign-in page as your company, and hear what happens to runs through signed webhooks.
Single sign-on and SCIM
Sign in with your company's identity provider (SAML 2.0 or OpenID Connect — Okta, Microsoft Entra ID, Google Workspace, Auth0), require it for your domains, map IdP groups to roles, and provision members with SCIM 2.0.