Audit trail and how to verify it
On this page
Maplith keeps one record of every privileged change in your account: who changed what, when, and from where. You can read it in the app, export it as a file, and check that file on your own computer, without asking Maplith.
What is recorded
Every entry says four things:
- Who. A signed-in person, an agent key, Maplith's own service, or a Maplith operator working directly in the database.
- When. The time the change was made, to the microsecond, in UTC.
- What. The action (for example
agent_key.revoked), the thing it was done to, and the details of the change. - From where. The app, an agent over MCP, Maplith's worker, Maplith's service, or the database itself.
The areas it covers:
- Agent keys, their policies and the operations they may use.
- Members and their access, in a workspace and in the organisation.
- The organisation's profile, and a workspace's creation, deletion and settings.
- Connections, the GitHub connection, wake-ups and live checks.
- Masking terms and masking suggestions.
- Rules, playbooks, glossary decisions and assistant proposals.
- Legal acceptance and OAuth consent.
- The first use of a signing key in a workspace.
- Deletions made by the retention control.
- Maplith staff access to a workspace: the grant, the notice to you, each use, its expiry and its end.
What is never stored. Secrets, key values and tokens are never written here: an entry says that one changed, not what it was. Names, email addresses and other personal data are not copied either; an entry holds ids, and the app turns an id into a name only when you read the page, so someone who has left reads as a former member. No IP address is recorded.
How long. Five years from the change, also after a workspace is deleted. The entries go when the organisation itself is deleted.
Two chains
Entries are linked so that a rewrite shows. Each entry carries a hash, a fingerprint of everything the entry says, and the hash of the entry before it. Change one entry afterwards and its fingerprint no longer fits; remove one from the middle and the next entry no longer points at what is there. A hash here is SHA-256, written as 64 characters of hexadecimal.
There are two chains:
- The workspace chain: the changes made inside one workspace.
- The organisation chain: the organisation's own changes, such as its profile, its seats, legal acceptance, and a workspace being created or deleted.
A file for one workspace can also hold the organisation's entries about that workspace, such as its creation. They belong to the other chain, so the check follows each chain on its own.
The table is append-only: no role can change or delete an entry, and a guard in the database refuses it even from the table's owner. The chain is what detects a rewrite if someone with enough access got round that guard, and a file with a few lines of code lets you see it without taking our word for it.
What the Settings › Workspace › Audit log page shows
Admins whose view of the workspace is not limited open it under Settings › Workspace › Audit log. Owners and admins of the organisation open the organisation's Audit log from the workspace picker, which shows the organisation's chain and every workspace's.
- The newest entries first, each said in words, with who, when and from where.
- Under Proof, the result of the chain check Maplith's database ran when you opened the page: "Chain intact", with the number of entries, or "CHAIN BROKEN" and the first entry that does not fit.
- Filters for area, actor, origin and dates (Copenhagen calendar days).
Export a range
- Open the Audit log and set the filters you want: dates, area, actor.
- Choose Export CSV or Export JSON. The file has every entry the filters match, in chain order, with both hashes.
- Which one to use: JSON also carries what Maplith's database said about the chain when the file was made (the check result and the chain head, the number and hash of the last entry), so use it for a check against the head. CSV opens in a spreadsheet; the script reads it too.
A range too large for one file is refused with a request to narrow the dates, so a file is never a silent sample.
A filtered file leaves entries out on purpose. The check below tells you where, and does not call that tampering.
Check a file on your own computer
You need Node 18 or newer. The script reads nothing but the file you give it, writes nothing, and uses no packages.
- Download the export (CSV or JSON).
- Save the script below as
verify-audit.mjs. - Run
node verify-audit.mjs maplith-audit-….csvin the folder that holds both. - Read the result. For each chain it lists what it checked and anything that does not fit. The last line says whether every chain checks. The exit code is 0 when it does, 1 when something does not match, and 2 when the file could not be read. Add
--strictto also fail on a gap or an unanchored start, which you want for an export with no filters;--strictcannot catch an end cut in a CSV. It holds the chain the file is about to that; see the note on workspace files below.
import { createHash } from 'node:crypto';
import { readFileSync } from 'node:fs';
// Usage: node verify-audit.mjs maplith-audit-....csv (or .json)
// add --strict to fail on a gap or an unanchored start as well, in the
// chain the file is about (organisation entries that only name a
// workspace are never the whole chain, so they are not held to it).
// Exit code: 0 every chain checks, 1 something does not match, 2 unreadable.
const GENESIS = '0'.repeat(64);
const NULLABLE = ['org_id', 'workspace_id', 'actor_id', 'actor_key_id', 'target_id', 'ref_table', 'ref_id'];
const NOT_AN_EXPORT = 'This does not look like a Maplith audit export.';
const args = process.argv.slice(2);
const strict = args.includes('--strict');
const file = args.find((a) => !a.startsWith('--'));
// ---- reading the file --------------------------------------------------
function parseCsv(text) { // RFC 4180: CRLF, quoted cells, "" for a quote
const table = [];
let row = [], cell = '', quoted = false;
for (let i = 0; i < text.length; i++) {
const c = text[i];
if (quoted) {
if (c === '"' && text[i + 1] === '"') { cell += '"'; i++; }
else if (c === '"') quoted = false;
else cell += c;
} else if (c === '"') quoted = true;
else if (c === ',') { row.push(cell); cell = ''; }
else if (c === '\n' || c === '\r') {
if (c === '\r' && text[i + 1] === '\n') i++;
row.push(cell); table.push(row); row = []; cell = '';
} else cell += c;
}
if (cell || row.length) { row.push(cell); table.push(row); }
return table.filter((r) => r.length > 1 || r[0] !== '');
}
function readExport(text) {
if (/^\s*[{[]/.test(text)) {
const data = JSON.parse(text);
return { kind: 'JSON', meta: Array.isArray(data) ? {} : data, rows: Array.isArray(data) ? data : data.rows };
}
const [head, ...body] = parseCsv(text.replace(/^\uFEFF/, ''));
if (!head || !head.includes('seq') || !head.includes('hash')) throw new Error(NOT_AN_EXPORT);
const rows = body.map((cells) => {
const row = {};
head.forEach((name, i) => {
const v = cells[i] ?? '';
row[name] = v.startsWith("'") ? v.slice(1) : v; // undo the formula guard
});
for (const k of NULLABLE) if (row[k] === '') row[k] = null;
row.seq = Number(row.seq);
row.detail = row.detail ? JSON.parse(row.detail) : {};
return row;
});
return { kind: 'CSV', meta: {}, rows };
}
// ---- the hash, as db/0148 audit_row_hash builds it ---------------------
const byteLength = (s) => Buffer.byteLength(s, 'utf8');
const byteOrder = (a, b) => byteLength(a) - byteLength(b) || Buffer.compare(Buffer.from(a), Buffer.from(b));
const ESCAPES = { '"': '\\"', '\\': '\\\\', '\b': '\\b', '\f': '\\f', '\n': '\\n', '\r': '\\r', '\t': '\\t' };
function quote(s) { // as Postgres escapes a json string
let out = '"';
for (const ch of s) {
const code = ch.codePointAt(0);
out += ESCAPES[ch] ?? (code < 32 ? '\\u' + code.toString(16).padStart(4, '0') : ch);
}
return out + '"';
}
function jsonb(v) { // the jsonb text: shortest key first, ", " and ": "
if (v === null || v === undefined) return 'null';
if (typeof v === 'string') return quote(v);
if (typeof v !== 'object') return String(v);
if (Array.isArray(v)) return '[' + v.map(jsonb).join(', ') + ']';
return '{' + Object.keys(v).sort(byteOrder).map((k) => quote(k) + ': ' + jsonb(v[k])).join(', ') + '}';
}
function utc(at) { // 2026-11-16T10:00:00.1+00:00 -> 2026-11-16T10:00:00.100000Z
const m = /^(\d{4})-(\d\d)-(\d\d)[T ](\d\d):(\d\d):(\d\d)(?:\.(\d{1,6}))?(Z|[+-]\d\d(?::?\d\d)?)$/.exec(String(at));
if (!m) return null;
const sign = m[8].startsWith('-') ? -1 : 1;
const digits = m[8] === 'Z' ? '0000' : m[8].slice(1).replace(':', '').padEnd(4, '0');
const minutes = sign * (Number(digits.slice(0, 2)) * 60 + Number(digits.slice(2)));
const whole = new Date(Date.UTC(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], +m[6]) - minutes * 60000);
return whole.toISOString().slice(0, 19) + '.' + (m[7] ?? '').padEnd(6, '0') + 'Z';
}
const FIELDS = ['org_id', 'workspace_id', 'scope_kind', 'scope_id', 'actor_kind', 'actor_id', 'actor_key_id', 'origin', 'action', 'target_kind', 'target_id', 'ref_table', 'ref_id'];
function rowHash(r) {
const o = { prev_hash: r.prev_hash, seq: r.seq, at: utc(r.at), detail: r.detail ?? {} };
for (const k of FIELDS) o[k] = r[k] ?? null;
return createHash('sha256').update(jsonb(o), 'utf8').digest('hex');
}
const holdsNumber = (v) => typeof v === 'number' || (v !== null && typeof v === 'object' && Object.values(v).some(holdsNumber));
// ---- the chains ---------------------------------------------------------
function checkChain(rows, head, filtered) {
rows = [...rows].sort((a, b) => a.seq - b.seq);
const problems = []; // a mismatch: the file cannot be right
const gaps = []; // what this file does not cover: not tampering by itself
const info = [];
const bad = (seq, check, text) => problems.push({ seq, check, text });
rows.forEach((r, i) => {
const before = rows[i - 1];
if (!before) {
if (r.seq === 1 && r.prev_hash !== GENESIS) bad(r.seq, 'genesis', 'the first row does not start from 64 zeros');
if (r.seq > 1) gaps.push('starts at seq ' + r.seq + ': the first link is not anchored in this file');
} else if (r.seq === before.seq) bad(r.seq, 'seq', 'seq appears twice');
else if (r.seq > before.seq + 1) {
const many = r.seq - before.seq > 2;
const what = many ? 'rows ' + (before.seq + 1) + '..' + (r.seq - 1) : 'row ' + (before.seq + 1);
// With the chain head and no filters the file is the whole chain, so a
// missing row cannot be a filtered-out one. Without them it can.
if (head && !filtered) bad(r.seq, 'gap', what + (many ? ' are' : ' is') + ' missing from an unfiltered file');
else gaps.push(what + (many ? ' are' : ' is') + ' not in this file');
}
else if (r.prev_hash !== before.hash) bad(r.seq, 'link', 'prev_hash is not the hash of the row before it');
if (rowHash(r) !== r.hash) {
bad(r.seq, 'hash', holdsNumber(r.detail)
? 'the hash does not match. Its detail holds a number, and a file may not carry a number exactly as the database wrote it (1.50 reads back as 1.5): compare this row with the chain check on the Audit page'
: 'the hash does not match what the row says: it was changed after it was hashed');
}
});
if (head && rows.length) {
const last = rows[rows.length - 1];
const at = rows.find((r) => r.seq === head.seq);
if (at) {
if (at.hash === head.hash) info.push('seq ' + head.seq + ' matches the chain head recorded in the file');
else bad(at.seq, 'head', 'the hash differs from the chain head recorded at export');
} else if (last.seq < head.seq) {
const text = 'the file ends at seq ' + last.seq + ' but the chain head is at ' + head.seq;
if (filtered) gaps.push(text + ' (the export was filtered)');
else bad(head.seq, 'head', text + ': rows were cut from the end');
}
if (typeof head.first_seq === 'number' && rows[0].seq > head.first_seq && !filtered) bad(rows[0].seq, 'first_seq', 'rows ' + head.first_seq + '..' + (rows[0].seq - 1) + ' are missing from the start');
}
return { problems, gaps, info };
}
try {
if (!file) throw new Error('Usage: node verify-audit.mjs <maplith-audit file.csv|.json> [--strict]');
const { kind, meta, rows } = readExport(readFileSync(file, 'utf8'));
if (!Array.isArray(rows) || rows.some((r) => !Number.isFinite(r.seq) || !r.scope_kind || !r.scope_id || !r.hash)) throw new Error(NOT_AN_EXPORT);
if (!rows.length) throw new Error('This file holds no entries, so there is nothing to check.');
const chains = new Map();
for (const r of rows) chains.set(r.scope_kind + ' ' + r.scope_id, [...(chains.get(r.scope_kind + ' ' + r.scope_id) ?? []), r]);
const filtered = Object.keys(meta.filters ?? {}).length > 0;
let failed = false;
console.log(file + ': ' + rows.length + ' rows, ' + chains.size + ' chain(s), read as ' + kind + '.');
for (const [key, list] of chains) {
const own = key === meta.scope_kind + ' ' + meta.scope_id;
const head = own ? meta.chain_head : null;
// A file made for one scope holds the whole chain of that scope and, for a
// workspace, the entries of other chains that name it: sparse by design.
// A CSV names no scope: an organisation chain whose every entry names a
// workspace is that slice (an export of the organisation itself holds the
// chain's entries that name no workspace as well).
const partial = meta.scope_kind ? !own : list[0].scope_kind === 'org' && list.every((r) => r.workspace_id);
const { problems, gaps, info } = checkChain(list, head, filtered);
console.log('\nChain ' + key + ': ' + list.length + ' rows');
for (const p of problems) console.log(' MISMATCH at seq ' + p.seq + ' (' + p.check + '): ' + p.text);
if (partial) {
console.log(' note: this file holds only the entries of this chain that name the workspace it was made for; the rest of the chain is not part of it, so gaps here are expected and --strict does not count them');
for (const n of info) console.log(' note: ' + n);
} else for (const n of [...gaps, ...info]) console.log(' note: ' + n);
if (!problems.length) console.log(' every hash recomputed, every link present checked');
if (problems.length || (strict && !partial && gaps.length)) failed = true;
}
// The loop above visits only chains that have a row in the file. With the
// chain head and no filters the file is the whole chain it is about, so a
// file that holds none of its rows is a chain removed whole.
const ownKey = meta.scope_kind + ' ' + meta.scope_id;
if (meta.chain_head && !filtered && !chains.has(ownKey)) {
const h = meta.chain_head;
const count = Number.isFinite(h.seq) ? h.seq - (typeof h.first_seq === 'number' ? h.first_seq : 1) + 1 : '?';
console.log('\nChain ' + ownKey + ': 0 rows');
console.log(' MISMATCH (head): the chain head says ' + count + ' entries but the file holds none of that chain');
failed = true;
}
if (!meta.chain_head) console.log('\nNo chain head in this file: rows cut from the end cannot be detected from a file alone.');
if (kind === 'JSON') console.log('Maplith said at export time: ' + JSON.stringify(meta.verified ?? null) + ' (not checked here).');
console.log('\nResult for this file: ' + (failed ? 'FAILED' : 'every chain checks') + '.');
console.log('A pass proves the rows in this file are consistent with each other, unaltered since they were hashed, and in an unbroken order within what the file covers.');
console.log("It does not prove that nothing is missing from the ends of a filtered file, or from the end of a file without the chain head (any CSV); only the JSON's head catches rows cut from the end.");
console.log('It does not prove that the recorded facts were true.');
console.log('From a CSV, or any file without a chain head or with filters, a removed middle row and a filtered-out row look the same, so --strict fails it.');
console.log('The chain head and the Audit page check come from Maplith\'s database; keep an exported head to compare against later.');
process.exit(failed ? 1 : 0);
} catch (e) {
console.error(e.message);
process.exit(2);
}
What it checks, for every row and every chain:
- hash: the row's hash is recomputed from what the row says and equals the hash in the file.
- link: the row's previous hash equals the hash of the row before it.
- order: the numbers (
seq) run 1, 2, 3… with none repeated; the first row of a chain has 64 zeros as its previous hash. - head (JSON only): the entry the chain head names has the head's hash, and an unfiltered file reaches it. An unfiltered JSON file that has the head is the whole chain, so a row missing from the middle of it fails the check on its own, without
--strict.
A file that starts after entry 1, or skips entries, is reported as "starts at seq N: the first link is not anchored in this file" or "rows N..M are not in this file". Each row that is there is still checked. From a CSV, or any file without the head or with filters, a row removed from the middle and a row a filter left out look the same, so the check cannot call it tampering; --strict fails it, and you use that on an export made without filters.
A workspace file also holds the organisation's entries that name the workspace (when it was created, when a version of the terms was accepted, a deletion request). That is only part of the organisation's chain, so the check lists those entries as a slice and --strict does not count the gaps around them as failures. Their hashes and links are still checked, and a mismatch there fails the file. In a JSON file the chain the file is about is the one it names; a CSV does not name it, so there the check treats an organisation chain whose every entry names a workspace as that slice.
The JSON file's own verified field is shown as "Maplith said at export time" and kept apart from the script's result: it is what Maplith's database reported, not something the script checked.
One known limit. The database keeps a number exactly as it was written, and a file read by a program may show it differently: 12.50 in the database reads as 12.5 in a file. Recorded details hold whole numbers almost everywhere (counts, versions); a decimal can appear in an action policy's upper limit. If a row whose detail holds a number does not match, the script says so, rather than calling it a rewrite, and you compare that row with the check on the Audit log page.
Recompute a hash in any language
This is what the script does, so you can write it in the language you prefer.
- Take the row's 17 fields:
prev_hash,seq,at,org_id,workspace_id,scope_kind,scope_id,actor_kind,actor_id,actor_key_id,origin,action,target_kind,target_id,detail,ref_table,ref_id. - An empty field is
null(an empty CSV cell, or anullin JSON).detailis a JSON object,{}when there is none.seqis a number. - Write
atin UTC with six digits after the seconds and aZ:2026-11-16T10:00:00.1+00:00becomes2026-11-16T10:00:00.100000Z. Apply any offset first, and pad the fraction with zeros; never round it. - Write the 17 fields as one JSON object, the way PostgreSQL writes a
jsonbvalue: - Keys are ordered by their length in bytes (UTF-8) first, and keys of the same length bytewise. At the top level that gives:at,seq,action,detail,org_id,origin,ref_id,actor_id,scope_id,prev_hash,ref_table,target_id,actor_kind,scope_kind,target_kind,actor_key_id,workspace_id. Apply the same rule to every object insidedetail, at any depth. Arrays keep their order. - A comma and a space between members, a colon and a space after a key:{"a": 1, "b": [2, 1]}. Empty objects and arrays are{}and[]. - Strings are escaped as\",\\,\b,\f,\n,\r,\t; any other character below U+0020 as\u00and two lowercase hex digits; everything else, including non-ASCII characters and U+007F, is written as it is. - The hash is the SHA-256 of those characters as UTF-8, in lowercase hexadecimal.
A worked row. The file holds:
{
"seq": 1,
"at": "2026-09-28T10:00:00.123456+00:00",
"scope_kind": "org",
"scope_id": "00000103-0148-4000-8000-000000000001",
"workspace_id": null,
"org_id": "00000103-0148-4000-8000-000000000001",
"action": "org.profile_changed",
"actor_kind": "operator",
"actor_id": null,
"actor_key_id": null,
"origin": "db",
"target_kind": "org",
"target_id": null,
"detail": { "b": 1, "a": [2, 1] },
"ref_table": null,
"ref_id": null,
"prev_hash": "0000000000000000000000000000000000000000000000000000000000000000",
"hash": "9adeba44c86fd8e11b8515b68ba66f2b5ee4d599de48dcc52dc4d4b25ea06e09"
}The text to hash is (one line):
{"at": "2026-09-28T10:00:00.123456Z", "seq": 1, "action": "org.profile_changed", "detail": {"a": [2, 1], "b": 1}, "org_id": "00000103-0148-4000-8000-000000000001", "origin": "db", "ref_id": null, "actor_id": null, "scope_id": "00000103-0148-4000-8000-000000000001", "prev_hash": "0000000000000000000000000000000000000000000000000000000000000000", "ref_table": null, "target_id": null, "actor_kind": "operator", "scope_kind": "org", "target_kind": "org", "actor_key_id": null, "workspace_id": null}Its SHA-256 is the hash above. The second row's prev_hash is that value and its seq is 2.
In a CSV, two more things: a cell that starts with =, +, -, @, a tab, a carriage return or an apostrophe has one apostrophe put in front of it, so a spreadsheet does not run it as a formula, and you take that one apostrophe off before you hash; and detail is JSON text in one cell.
What a pass proves and what it does not
A pass proves that the rows in the file are internally consistent, unaltered since they were hashed, and in an unbroken order within what the file covers.
It does not prove that nothing is missing from the ends of a filtered file, or from the end of a file without the chain head (any CSV); only the JSON's head catches rows cut from the end. It does not prove that the recorded facts were true. From a CSV, or any file without the chain head or with filters, it does not prove that no row is missing from the middle either, because a removed row and a filtered-out row look the same there: run it with --strict on an export made without filters. And the chain head and the Audit log page's check are produced by Maplith's database: a customer who wants independence from that keeps an exported head and compares it later.
To do that, keep the chain_head of a JSON export (the number and hash of the last entry). When you check a newer file, the entry with that number must still carry that hash, and every entry from there to the end must link back to it.
A file that will not check, or a question about this page: support@maplith.com.
Related: Security and access for how the rest of the account is protected, and Agent keys & policies for the keys the trail records.