Security and privacy
The audit log as a security control
What the audit log lets you detect, which actions by Nullgap staff appear in it, and how to verify it yourself.
The audit log is the record of who did what in your organisation. As a security control it does three things: it shows you sign-ins and security changes, it shows you what Nullgap's own staff and automation did in your workspace, and it is built so that altering it afterwards is detectable.
This page is about those properties. For day-to-day use (the list of actions, filters, export) see the audit log.
#What it is good for
| Question | Where to look |
|---|---|
| Did anyone sign in whom I do not expect? Were there failed attempts? | Actions starting auth. and mfa. |
| Who was given access, or more access? | member., invitation., apikey., scim. |
| Did how people sign in change? | sso., and settings.updated naming requireMfa |
| Where are my findings being sent? | webhook., integration., slack_assistant., report.shared |
| Was data taken out or removed? | data.exported, data.erased, data.retention, findings.exported, audit.exported |
| Did someone try to take over one of my e-mail domains? | sso.domain_claim_attempt |
| Was a run stopped for a privacy reason? | security.zero_retention_unconfirmed |
Entries never contain secrets, tokens or codes. A change to settings lists which settings changed, not their values.
#Staff actions in your log
Whatever a person at Nullgap does to your workspace is written to your log, not only to Nullgap's own. You do not have to ask whether it happened.
| Actor | Action | What it means |
|---|---|---|
Nullgap researcher | finding.viewed_for_validation | A researcher opened one of your findings, with its evidence and code excerpt. Written on every read, where human validation is on for your workspace |
Nullgap researcher | finding.validation_confirmed, finding.validation_adjusted, finding.false_positive | The researcher's decision on a finding |
Nullgap support | platform.validation_enabled, platform.validation_disabled | Human validation was switched on or off for your workspace |
Nullgap support | platform.plan_changed, platform.limits_changed, platform.credits_adjusted | Your plan, your monthly usage ceiling or a credit balance was changed |
Nullgap support | platform.suspended, platform.resumed | Your workspace was suspended or resumed |
operator | secrets.erased | Your organisation's stored secrets were removed in a maintenance action on the service |
Each Nullgap support entry carries the reason the member of staff gave. The actor is the role, not the individual's name.
Nullgap's automation appears too, as nullgap (retention, automatic seats, stopped runs) and system (the daily domain re-check).
What reaches staff in the first place is described under who at Nullgap can see what.
#Tamper evidence
Each entry has a position, seq, and a hash. The hash is a SHA-256 over the entry's own fields and the hash of the entry before it. The hash of the newest entry is stored separately as the head of the chain.
| If someone | Then |
|---|---|
| Changes an entry | Its hash no longer matches its contents |
| Removes an entry from the middle | The next entry's link points at a hash that is no longer there, and the positions skip |
| Inserts an entry | The same: the links and positions around it no longer line up |
| Removes the newest entries | The chain that remains is consistent, but it no longer ends at the stored head |
Verify integrity in the console, or GET /api/orgs/:org/audit/verify, walks the whole chain from the oldest entry and reports the first place it does not hold. What a pass and a failure look like is shown under verify.
The audit log is not deleted by the retention period or by erasing data. It goes only when the workspace itself is deleted; Nullgap's own operations log then records that it was removed, how many entries it held and the hash it ended on.
#The limit
A chain kept in the same database as the entries protects against changes to individual entries. It does not protect against someone with full write access to the database rewriting the whole log and the head together. Verification inside the service cannot detect that.
What closes the gap is a copy that Nullgap cannot touch. That is the next section.
#Verifying it yourself
Export the log on a schedule and keep the exports in your own storage. An export carries seq and hash for every entry, so you can check two things without trusting the service:
- The export is internally consistent: every entry's hash matches its contents and the entry before it.
- History has not been rewritten: an entry in last month's export has the same
seqandhashin this month's.
#Take an export
Use the JSON format, with an API key that has the admin scope:
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/audit/export?format=json" -o audit.json
You also need your organisation's id, which is the id in:
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG"
#Check the chain
An entry's hash is the SHA-256, in hexadecimal, of the JSON text of this array:
[ previous entry's hash, seq, id, organisation id, at, actor, action, target, detail ]
The first entry of a chain (seq 1) uses an empty string as the previous hash. target and detail are null when absent. The JSON is compact, with no spaces, as JSON.stringify writes it.
A script that checks an export:
// node verify-audit.mjs audit.json org_7d3k
import { createHash } from 'node:crypto';
import { readFileSync } from 'node:fs';
const [file, orgId] = process.argv.slice(2);
const entries = JSON.parse(readFileSync(file, 'utf8'))
.filter((e) => e.hash !== undefined) // entries from before chaining carry no hash
.sort((a, b) => a.seq - b.seq);
let previous = null;
let checked = 0;
for (const e of entries) {
// The entry before the first one in a partial export is not in the file, so its link cannot be checked.
const prevHash = e.seq === 1 ? '' : previous && previous.seq === e.seq - 1 ? previous.hash : null;
if (prevHash === null) {
if (previous) throw new Error(`Entry ${e.seq} does not follow entry ${previous.seq}: something is missing`);
} else {
const expected = createHash('sha256')
.update(JSON.stringify([prevHash, e.seq, e.id, orgId, e.at, e.actor, e.action, e.target, e.detail]))
.digest('hex');
if (expected !== e.hash) throw new Error(`Entry ${e.seq} does not verify`);
checked += 1;
}
previous = e;
}
console.log(`${checked} entries verified, up to seq ${previous?.seq ?? 0} (${previous?.hash ?? 'none'})`);
Run it on an unfiltered export. A filtered export has gaps by design, and the script reports the first one.
#Compare with earlier exports
Keep the last line the script prints: the highest seq and its hash. Next time, check that the new export contains an entry with that seq and that its hash is the same. If it is, nothing at or before that point has been rewritten since your last export.
Things to know:
- An export holds at most 100,000 entries. For a longer log, export by date range with
fromandto, then merge the parts into one array before running the script, so that the link between one part and the next is checked too. - Taking an export adds an
audit.exportedentry, so the log is always one entry longer afterwards. - The CSV export has
seqandhashbut not the entry'sid, so it can be compared with earlier exports but not recomputed. Use JSON for verification.
#If something does not verify
Keep the export, note the first entry that fails, and contact Nullgap through the contact in your agreement. See getting help.
Nullgap documentation