Skip to Content
OperationsThe audit chain

The audit chain

Nebbos keeps hash-chained, tamper-evident records of the tool calls made through the Nebbos MCP and of the changes made through the platform API. Each record carries the SHA-256 hash of the record before it, so changing an earlier record breaks the link to every record that follows. This page describes what is recorded today, what each record holds, how your team checks a record, a range or the whole chain, and the limits that still apply.

This page describes the platform as built on 9 November 2026. Read-only platform API requests are not recorded yet, verification results are not signed, and there is no offline verifier yet. See Current limits.

What is recorded

SourceWhat is recordedHow it enters the chain
MCP tool callsEvery call made through the Nebbos MCP, by a Pearl or a person, reads included, with its outcome. Refused and denied calls are recorded too.The record is written to a durable queue before the tool response returns. A background chain builder hashes it into the chain, normally within about a minute.
Platform API changesEvery POST, PUT, PATCH and DELETE request to the platform API.Queued by the API after the request completes and written by a background job.

Each client has its own chain for each source. Writers take a per-client lock while they read the latest hash and append, so two writers cannot fork a chain.

Read-only (GET) requests to the platform API are not recorded yet. Changes made in the web app by signed-in people have been recorded since 4 November 2026; some made before that date have no record.

Record contents

MCP tool-call records

These fields are stored as columns:

FieldMeaning
idRecord identifier (UUID).
event_typeagent.tool_call for tool calls. Other platform events written to the same chain use their own types.
actor_typeThe kind of identity that made the call, for example agent.
actor_idThe identity that made the call.
delegated_byThe person on whose behalf an agent acted, when the call was delegated.
occurred_atWhen the record was written.
hashSHA-256 of this record. See Hashing.
previous_hashThe hash of your client’s previous record; 64 zeros for the first record in the chain.

Each record also has a payload, which the MCP audit tools do not return today. The values of the payload fields that identify a person (actor_id, delegated_by, subject_user_id, requested_by, user_id, ip and user_agent) are encrypted with your client’s key; the rest of the payload is stored as plain JSON. If your client has no key yet, the payload is stored unencrypted.

Payload fieldMeaning
toolThe MCP tool name.
parametersThe parameters of the call, with sensitive fields redacted before storage. Some arguments, such as uploaded file contents, are stored only as a SHA-256 digest and a length.
result_statussuccess, failed, denied, timeout, denied_not_configured or partial.
scopes_usedThe scopes on the calling token.
lane, intentHow the platform classified the call, from its scopes and the tool.
attestation_levelThe attestation level recorded for the caller’s session. The platform records it but does not yet require it.
session_id, session_id_sourceThe caller’s session and where that identifier came from.
client_id, client_name, mcp_session_id, ip, user_agentThe MCP client application, its MCP session, and the network address and user agent of the call.
via, surface, task_id, code_job_id, answered_from, duration_ms, error_classPresent when they apply: how the call was routed, the surface it came from, the task it served, the code job it ran, where an answer came from, how long it took and the class of any error.

The payload can also carry fields the platform records for its own access-policy checks. The tool’s response is not stored, and inputs and outputs are not hashed separately.

Platform API change records

Each record has your client identifier and fields for the event category and type, the actor, the subject (type and identifier), the action, severity, a description, metadata, before and after state, IP address, user agent, session and correlation identifiers, the time it occurred, hash and previous_hash.

Hashing

hash = sha256( canonical_json(payload) + previous_hash )

canonical_json is Python’s json.dumps(payload, sort_keys=True, default=str): keys sorted, default separators (", " and ": "), non-ASCII characters escaped. The concatenated string is UTF-8 encoded and the hash is lower-case hex. The first record of a chain uses 64 zeros as previous_hash.

  • MCP tool-call records hash the plaintext payload above, before any field is encrypted. The id, event_type, actor_type, actor_id, delegated_by and occurred_at columns are stored next to the payload and are not covered by the hash.
  • Platform API change records hash these fields: tenant_id, event_category, event_type, actor_type, actor_id, subject_type, subject_id, action, severity, description, metadata, before_state, after_state, ip_address, user_agent, session_id and correlation_id. The time and the hash fields themselves are not covered.

Checking a record

Three MCP tools read the MCP tool-call chain. Each needs the audit_events:read scope and is scoped automatically to your client.

ToolWhat it does
audit_event_listLists records: id, event_type, actor_type, actor_id, delegated_by and occurred_at, with no hashes and no payload. Optional filters: event_type, since, until (ISO-8601), actor_id; limit defaults to 25, at most 200.
audit_event_getReturns one record’s columns, including hash and previous_hash. The payload is omitted.
audit_event_hash_chain_verifyVerifies one record, given its event_id.

Every record names the person who acted, so audit_event_list returns records only while your organization has per-person records switched on; otherwise the call is held. Filtering by another person’s actor_id needs an administrator.

audit_event_hash_chain_verify runs two checks:

  1. Structural. The record’s previous_hash matches the hash of an existing record of your client. Skipped for the first record.
  2. Cryptographic. The platform decrypts the stored payload fields with your client’s key, recomputes the hash and compares it with the stored hash.
Result fieldMeaning
validtrue when the structural check passes and the recomputed hash matches (or the record has no payload).
kindcryptographic_rehash when the hash was recomputed, otherwise structural_link.
is_genesisWhether this is the first record of the chain.
structural_validResult of the structural check.
rehash_verifiedResult of the cryptographic check; null when it could not run.
computed_hash, stored_hash, previous_hashThe hashes compared.
crypto_notecrypto_shredded when your client’s key has been destroyed, no_payload when there was nothing to hash. Present only in those cases.
legacy_wrapper_formtrue when the record verified under the one legacy hash form described in Current limits. Present only in that case.

The result is not signed. If your client’s key has been destroyed after an erasure request, the hash can no longer be recomputed and the result is valid: false with crypto_note: "crypto_shredded".

Checking a range or the whole chain

MCP tool-call chain, daily. Every day at 02:40 UTC the platform walks your client’s whole MCP tool-call chain. It checks every link and recomputes each record’s hash where your client’s key allows; records it cannot recompute keep their link checked and are counted as unverifiable. Read the newest result with the get_audit_chain_status MCP tool (scope security:read) or GET /api/v1/security/audit-chain: whether the chain is intact, the time it is verified through, the rows checked and, if there is one, the first broken link with its reason.

Platform API change chain, over a time range. GET /api/v1/audit/events/verify?since=<ISO-8601>&until=<ISO-8601> checks every record in the range on the server. It checks links only and does not recompute hashes. It covers at most 50,000 records per request and answers 422 above that. The response gives status (ok or broken), rows_checked, the record and time it is verified through and, for a break, first_break_id and first_break_reason (hash_mismatch, fork or missing_predecessor).

Reading and exporting platform API change records

Platform API change records are read through GET /api/v1/audit/events (at most 100 per page) and checked through GET /api/v1/audit/events/verify. Both need the settings:admin scope, or a member with an unexpired Record read grant, which an administrator creates through POST /api/v1/audit/record-read-grants. The export, GET /api/v1/audit/events/export (CSV or JSON), needs settings:admin and is an Enterprise-tier capability. Neither the list nor the export returns hash or previous_hash today.

Append-only, and its one exception

Database triggers reject updates and deletes on the chained records. There is one sanctioned exception: an erasure request (for example under GDPR) briefly disables the trigger to clear the person’s identifier from delegated_by and actor_id on MCP records. Neither column is covered by the hash, so the chain still verifies afterwards.

Current limits

  • Read-only platform API requests are not recorded.
  • Recording an MCP call does not block most calls: if the write fails, the tool still returns and the failure is logged on the server, so a missing record is possible. A few write tools, such as saving a memory note or sending a message, refuse to complete when their record cannot be written.
  • Platform API change records written before that chain was introduced have no hash and sit outside the chain.
  • If a writer cannot read the previous hash, it starts again from 64 zeros. That shows up as a break when you verify, and in the daily check.
  • Records of one historical event type were hashed in a different form (a wrapper around the payload) by a one-time backfill on 2 September 2026. The verifier accepts that form for that event type only and reports legacy_wrapper_form: true.
  • Verification results are not signed, there is no offline verifier, and neither the list nor the export of platform API change records returns the hashes, so you cannot recompute those hashes yourself.
  • The record format has no version marker yet. Changes to it will be noted on this page.

See the MCP reference for how to connect and discover tools.