Events and the audit record
List every audit event Straza emits and the fields of the audit record.
On this page
An event is one CloudEvents 1.0 JSON object that Straza publishes when something it governs happens: a tool decision, an admin mutation, a login, a revocation, a policy activation or an MCP server lifecycle change. The type is also the subject. A consumer therefore filters by type alone. Every type under straza.audit. is appended to the hash chain after publication, and every type except the recorded prompts and replies reaches a sink that sets no filter. Evidence explains why the pipeline has this shape.
The envelope
Every event carries the six CloudEvents fields specversion (always 1.0), id, type, source, time and data, all required. The producer mints a unique id, delivery is at least once, and a consumer dedupes by that id. The source says which producer wrote the record and nothing more: strazad on a server-side decision, strazad/ followed by the instance id on a control or admin event, strazad-sentinel on a sentinel verdict, and straza on every event a client uploaded, stamped by the server at ingest whatever the client sent. Consumers route on type, never on source, and they ignore fields they do not know, because payloads only ever grow. time is RFC 3339 in UTC.
Since revision 53 a record is at most 256 KiB of JSON once strazad writes it to its database, a quarter of the event bus’s default message size of 1 MiB. A record within that is stored exactly as its producer made it. In a longer record strazad cuts the longest strings inside data to one common length at which the record fits, and each cut string ends with ... (<n> bytes, sha256 <hex>), its whole length in bytes and the SHA-256 of the whole string. A hook command of 900 KiB of <, which the record writes as 5.4 MB because it escapes each < into six bytes, keeps about its first 43,500 characters that way, and you can hash the client’s copy of the command to compare. Numbers and booleans are never cut. When cutting cannot make a record fit, it keeps the five envelope fields and only these fields of data: action, actor, actorId, actorVia, agentId, agentType, app, approvalId, arguments, command, decidedBy, device, effect, event, harness, outcome, phase, reason, ruleId, session, setName, snapshot, state, target, tool, toolName, user, userId, via and workspace. Each string among them over 256 bytes is cut the same way, an upload’s own id included, and dataOmitted gives the length and the SHA-256 of the whole record. Such a record is the one exception to the table below, because fields such as paths are gone from it. Since revision 58 two more records take this form. A record over 256 KiB that holds more than 65,536 JSON values takes it at once, without the cut, because decoding that many values costs seconds. On an upload from a straza client, the records are decoded in order while their values add up to at most 65,536, and a record past that budget takes the form whatever its length, so a client record under 256 KiB can carry dataOmitted. strazad logs one Warn line per upload that names the count, and an upload of more than 1000 records is refused whole with 413. A row that the event bus still refuses is set aside. Every later record is still published. Only an external NATS server whose max_payload is below 256 KiB, or a row written to the database past strazad, makes one. straza_outbox_set_aside_total counts it, as Metrics and alerts explains.
Three streams and one channel that is not a stream
The events ride JetStream streams inside the server’s event bus. In either profile the bus runs in-process with no socket until it is pointed at an external NATS server, which several replicas share. STRAZA_AUDIT carries every straza.audit. type and is the stream the chain writer drains, bounded by age and size so a full disk can never stall a publish, with the chain and the outbox holding the durable copies. STRAZA_EVENTS carries the straza.policy., straza.revocation., straza.apps. and straza.identity. types, the control events that converge every server instance and feed the identity change feed, and none of them enters the chain. A third stream, STRAZA_DEADLETTER, holds the deliveries a sink refused, on straza.deadletter. followed by the sink name. It is not a spine subject, so a sink that filters straza.> cannot consume its own parked events, and it refuses new parks when full rather than shedding old ones. The client push channel is none of these. The straza.push. subjects and the approval resolution broadcast straza.approval.resolved. are core NATS messages rather than CloudEvents, delivered at most once, and a straza service that misses one learns of it at the session’s next renewal.
Event types
Every type below has at least one emit site in the server or the client. The stream column says where the type rides, and only the audit stream is chained.
| Type | Fires when | Actor in the payload | Stream |
|---|---|---|---|
straza.audit.tool |
a hook decides a local tool call, or /v1/decide does |
user, the session’s subject, with session and harness |
audit |
straza.audit.mcp |
the gateway decides a tools/call, serves a tools/list, or lists or reads the views of one MCP server, withholds a reply that held the credential it injected, or refuses a request for a revocation or a low attestation, or strazad decides a git grant |
user and session of the calling agent |
audit |
straza.audit.admin |
an admin object changes over the admin API or over SCIM, a role assignment that starts or ends included, a user is created or changed, an approver enroll token is minted, an approver device enrolls or goes with its deleted user, an admin revokes a user’s machine or deletes a user, an agent’s key is set or removed, or a config draft is created, checked, published, discarded or expires, or a server it proposes is contacted, or strazad lists the objects of an MCP server, or Straza refuses an identity manager’s SCIM write | actor, actorId and actorVia (login, session, api-token, or enroll-token on an approver enrolment, whose actor is the person whose enroll token was consumed), absent when no principal acted, as on a draft.check, which strazad writes for its own check |
audit |
straza.audit.authn |
a login succeeds or fails, a session ends, a Slack tap by a disabled or locked person is refused, the phone lane refuses a person who is disabled, locked or no longer a person, or a session token bound to a machine’s key arrives without a valid proof from that key | user and userId when known, never fabricated |
audit |
straza.audit.identity |
the kill switch fires, is lifted, or an identity manager lift is refused by a lock, a machine’s key is used from a copy of the machine and strazad revokes the device, or a person enrolls a machine’s key | origin, one of scim, admin or external, plus the affected user. A device.key.reused or device.enrolled record names the user and the device and carries no origin |
audit |
straza.audit.prompt |
a recorded session submits a prompt | user and session, with agentType when a delegate wrote it |
audit |
straza.audit.reply |
a recorded session’s model finishes a reply | the same as the prompt | audit |
straza.audit.sentinel |
the audit sentinel judges a session, or the gateway withholds a reply that held the credential it injected | none: the server’s sentinel is the author, or the gateway for a credentialEcho verdict |
audit |
straza.audit.approval |
an approval is requested or resolved, or a call uses its approval, a ticket’s grant or a hold’s one run | user at request, decidedBy and channel at resolution |
audit |
straza.policy.updated |
a snapshot activates | none, the activating admin is on the matching admin event | events |
straza.revocation.user |
a user is disabled, deactivated or locked | origin names the authority |
events |
straza.revocation.session |
one session is revoked | none | events |
straza.revocation.sessions |
a bulk stand-down revokes a set, at most 1000 ids per event | none | events |
straza.revocation.device |
a device enrollment is revoked | none | events |
straza.revocation.lift |
a user is fully reactivated and no revocation lane remains | origin |
events |
straza.apps.deployed |
an MCP server is installed or updated and serving | none, the server manager | events |
straza.apps.removed |
an MCP server is removed or stopped | none | events |
straza.apps.drift |
an MCP server’s upstream tool inventory changed against the cache | none | events |
straza.apps.updated |
an access row, an MCP server secret or a per-user grant changed, or a draft was published | none | events |
straza.identity.created |
a user is created over SCIM or through the admin API | none | events |
straza.identity.updated |
an identity fact changes: enroll, session start, role edits, device, key or approver changes | action names the change where the emitter sets one, such as enroll, session.start, renew, oauth.connect, nhi-key.set or approver-enroll. approver-device-revoked carries device, user, via admin or self, and reason when a user delete revoked the device. Role edits, user creates and the SCIM lifecycle carry only the user’s id |
events |
straza.identity.deactivated |
a user is deactivated over SCIM or deleted by an admin | none | events |
A sink with no subjects filter receives straza.audit.tool, straza.audit.mcp, straza.audit.admin, straza.audit.authn, straza.audit.identity, straza.audit.approval and straza.audit.sentinel, plus every type under straza.policy., straza.revocation., straza.apps. and straza.identity., and the boot log names the two it leaves out. Recorded conversation content leaves the box only when a sink names straza.audit.prompt and straza.audit.reply, or straza.>, in its own filter.
Payload fields
The first column of fields is present on every record of the type from the current revision on, and the second appears when the event carried it. Field names are the JSON keys inside data.
| Type | Always present | Present when it applies |
|---|---|---|
straza.audit.tool |
session, user, harness, event, tool, command, effect, ruleId, setName, reason, snapshot, except on a client’s loss record, below | toolName (the harness’s own name of a tool Straza does not classify, whose tool is other, since revision 50), and since revision 64 arguments (the JSON text of the tool’s input, cut at 8 KiB, absent when an older client sent none, and since revision 65 on every tool’s record) with argumentsTruncated and argumentsHash (sha256: and the hex SHA-256 of the whole text) when it was cut, and nativeTool (the harness’s own name of a tool Straza classifies, such as Skill behind a file.read), paths, workspace, agentType, agentId, and since revision 59 commandTruncated and commandHash, pathsTruncated and pathsHash on a client record that cut its command or paths at 64 KiB |
straza.audit.mcp |
session, user, harness, event, tool, app, toolName, effect, ruleId, setName, reason, snapshot, granted, default, where since revision 52 a server or tool name the caller’s catalog did not resolve, or that an approval_request describes, is cut at 256 bytes in app, toolName and reason and followed by ... (<n> bytes), its length as sent, and the schema check’s detail in the reason of a gated call is cut at 512 bytes the same way |
bindingId and role (the access row that admitted the call), credentialId (the credential row the upstream call used), credentialSource (own, sponsor, shared or client_credentials), credentialOwner (the user id of the person whose connection an agent used), arguments (the verbatim call arguments as JSON text, cut at 8 KiB), argumentsTruncated, argumentsDigest and argumentsSize (the hex sha256 and the length in bytes of the arguments, written in place of arguments on a call of straza__draft_submit), count (the tools or views served, on a tools.list or resources.list record), uri (the view’s address, on a resources.read record), object (on a server that pins an object type: the type and the tool’s reach, and the value the call names with its id in the object list, the value cut at 512 bytes with valueTruncated and valueSha256 when longer), rolesChecked (the held roles that bind the tool, on a call the object check refused, which then carries no role or bindingId), grant (on an issued git grant: its jti, op, aud, exp and approval, as Git grants says) |
straza.audit.admin |
action, target | actor, actorId, actorVia, draft (the draft a publish came from, on every record that publish writes), for roles.assign and roles.unassign the user, role, roleId, origin and reason, for apps.grant.remove and nhi-key.removed the user and reason, and the user, username and other fields of the identity setup records below, and for apps.objects.list, which names no actor, the app with its id as target, the tool, type, outcome, count and version, with joined and left on a success and reason on a failure. apps.secret.set and apps.secret.remove carry scope listing for a server’s listing credential. apps.binding.create and apps.binding.delete carry covers when the binding has a covers line, always as an object: {"every": true}, or objects with each object’s id and its value at publish |
straza.audit.authn |
action (login, session.end, or proof, whose outcome is always failure), outcome | via (device-key on a refusal by the key lanes, whose successful check-in writes no authn record, and client-assertion on an AI agent’s sign-in with its own key), user, userId, session, harness, reason, sourceIp, userAgent, approvalId (a refused Slack tap or phone decision) |
straza.audit.identity |
action (user.killed, user.reactivated, user.lift.blocked, device.key.reused or device.enrolled), user | origin (on every action except device.key.reused and device.enrolled), reason, sessionsRevoked, heldBy, on device.key.reused the device, counter (the counter the check-in sent) and storedCounter (the last one accepted), and on device.enrolled the device, signIn (browser or code, the lane strazad judged), custody (account or user) and authTime (the identity provider’s auth_time in RFC 3339, when the ID token carried one) |
straza.audit.prompt and straza.audit.reply |
session, user, harness, content, mode, truncated, contentHash | agentType, agentId |
straza.audit.sentinel |
session, detector, severity, reason, evidence | user, window |
straza.audit.approval |
phase, approvalId, session, user, rule, set, lane, summary, state, where since revision 52 summary holds at most 4 KiB, cut like a long name above | justification (at most 4 KiB since revision 52), decidedBy, channel (console, slack, phone or browser), decidedReason, decidedDeviceId, consumedBy, consumedAt |
straza.policy.updated |
snapshot, sets | draft, when a publish wrote the event |
straza.revocation.user |
user, reason, origin | none |
straza.revocation.session |
session | none |
straza.revocation.sessions |
sessions | reason |
straza.revocation.device |
device | none |
straza.revocation.lift |
user, origin | none |
straza.apps.deployed |
app, name, version, runtime, source | none |
straza.apps.removed |
app, name | draft, when a publish wrote the event |
straza.apps.drift |
app, name, added, removed | none |
straza.apps.updated |
change (binding, secret, grant or publish) | app, draft on every event a publish writes, and on the publish event itself snapshot and apps, the servers the publish created, changed or removed |
straza.identity.created, straza.identity.updated and straza.identity.deactivated |
the user id, as id or user depending on the emitter |
action where the emitter sets one, the session, device, harness or attestation it touched, and draft on a straza.identity.updated that a publish wrote |
A straza.audit.tool record keeps the input of every tool as it was sent, as it keeps a shell command. That is the file text of a write or an edit, the prompt an agent writes for a subagent, the skill a Skill call names, and the arguments of a call to an MCP server that the harness runs itself, such as the text a browser tool types into a form. An input over 8 KiB keeps every field with its longest strings shortened, and the record adds the hash of the whole text. The input is not scanned or masked. It can therefore hold a secret that the agent wrote or typed, and it reaches every sink that receives the tool record. To keep it out of a sink, give that sink a subjects list without straza.audit.tool. A call that goes through the Straza gateway keeps its arguments on the gateway record, so its tool record carries none. The same holds for the gateway’s draft_submit and approval_request when a harness reaches them under another server name.
Two reason values of a straza.audit.authn login failure come from the key lane. the client's bearer device credential is retired marks a request from a straza client older than the key lane, and key custody is below governance.minCustody marks a person’s machine key whose custody, as the client reported it at enrollment, ranks below governance.minCustody. An AI agent’s key carries no custody, so no agent record carries the second.
Revision 47 judges the sign-in behind a person’s machine key. Each person’s key enrollment that succeeds writes one device.enrolled record, also when it replaces an earlier key, and an enrollment of strazactl or the console writes none. Eight new reason values of a straza.audit.authn login failure come with it, and an enrollment can now also carry the deadline reason of revision 45. Each refused request writes one record:
| Reason | via |
When |
|---|---|---|
the sign-in was made for another Straza program |
device-key | an ID token of the built-in issuer that strazactl or the console asked for, whose audience is not straza |
the sign-in was made for another key |
device-key | the ID token’s nonce is neither empty nor names the key that signs the enrollment |
the sign-in carries no auth_time |
device-key | a browser sign-in whose ID token has no auth_time |
the sign-in is older than 10 minutes |
device-key | a browser sign-in whose auth_time is more than 10 minutes old |
the sign-in time is ahead of the server clock |
device-key | a browser sign-in whose auth_time is more than 1 minute ahead of strazad’s clock |
the sign-in lane is below governance.minSignIn |
device-key, or session-token on a refresh | a code sign-in at enrollment, or a key check-in or refresh of a machine enrolled with one, while governance.minSignIn is browser. A machine enrolled before revision 47 counts as code |
the last sign-in on this machine is older than governance.signInMaxAge |
device-key | an enrollment whose auth_time is already past the sign-in deadline, on either lane. Since revision 45 it also marks a check-in or refresh past the deadline |
a person's ID token alone does not start a session on enterprise |
id-token | under the enterprise profile, a person’s check-in with an ID token under a harness name other than console and self-service. A check-in under strazactl gets the reason of revision 55 instead |
an agent check-in without a key proof is refused on enterprise |
id-token | under the enterprise profile, an AI agent’s or a service account’s check-in with an ID token and no DPoP proof |
Revision 62 names the person in the refusal of a sign-in whose username belongs to an account linked to another identity at the identity provider. Each refused request writes exactly one straza.audit.authn login failure with via id-token, the account’s user and userId, and the reason the account is linked to another identity at the identity provider, on the session exchange, enroll, the admin API and the approvals routes. Before, only the session exchange wrote a record of it, with the reason login not accepted and no user. The change is additive.
Revision 59 brings the audit a straza client lost to the chain. When its spool discarded records, after failed uploads past the spool cap or for a record larger than one upload, or when its background service refused a decide or capture call before it could record it, the client’s next upload sends one straza.audit.tool record with the event audit.dropped, on its own and ahead of its other records. It carries droppedRecords, the sum of oversizeRecords, evictedRecords and refusedCalls, with evictedFiles, dropEvents, firstDrop and lastDrop when the client knew the times, and a reason that says the same in sentences. strazad files it under the uploading session and user. It carries none of the other fields a tool record always has, so a consumer that counts decisions skips it. The client keeps sending it, under the same id, until strazad takes it, and only then clears its count. The same revision bounds a client’s tool record: it keeps at most 64 KiB of command and of paths, and a record that cut either adds commandTruncated and commandHash, the SHA-256 of the whole command, or pathsTruncated and pathsHash, the SHA-256 of the whole list with each path preceded by its length in bytes as an unsigned 64-bit big-endian number. You can check a cut record against the machine’s own copy with them. The change is additive.
Revision 58 adds a record where a refusal left none, and one new verdict. When the reply to a tools/call holds the credential Straza injected for the call, whole or encoded in base64, hex, percent escapes, form encoding or JSON escapes, the gateway withholds the reply and the agent reads a refusal instead. The call’s allow record stays, and a second straza.audit.mcp record follows with the event tool.post, effect deny, the allowing rule and set, and the refusal as reason. Then a straza.audit.sentinel verdict follows, with the detector credentialEcho, severity critical, source strazad and the id of that deny record in evidence. The gateway raises this verdict itself, so it arrives whether the audit sentinel runs or not.
A gateway request that strazad refuses because its session, device or user is revoked, or because its attestation is below governance.minAttestation, now writes one straza.audit.mcp deny with the event request and ruleId revoked or attestation, as /v1/decide already did. Its app is the server of a /mcp/{server} request and empty elsewhere, and tool and toolName are empty. On /mcp, the record of an unknown tool whose name holds __ now names the server in app and the tool in toolName, as the record of a call that resolved does.
A device revoke now ends the device’s sessions, and each session it ends writes one session.end record. A user delete writes user.delete, and an audit upload refused for a revocation writes a login failure. The new reason values, and the records that carry them:
| Reason | Record | When |
|---|---|---|
device revoked by admin |
session.end, outcome revoked-admin |
one per session that an admin device revoke ends, before its device.revoke |
device key reused |
session.end, the new outcome revoked-key-reuse |
one per session that strazad ends when a copy of the device’s key checks in, before its device.key.reused, with the sourceIp and userAgent of that check-in |
an AI agent or a service account cannot sign in with a password |
login failure, via password |
an AI agent or a service account typed its right password on a built-in sign-in page. A wrong password keeps invalid username or password for every account |
session is no longer active, device or user revoked |
login failure, via session-token |
also an audit upload whose session, device or user is revoked |
only a person who is the user's sponsor or an administrator can change another user's connection |
connection.refused |
a write on another user’s connection by an AI agent or a service account, whatever roles it holds, or by a person who is neither the user’s sponsor nor an administrator |
an agent or a service account cannot allow agents |
connection.refused |
an AI agent or a service account turns the agents opt-in on for its own connection |
an admin API token cannot start a sign-in |
connection.refused, with actorVia api-token |
an admin API token starts a provider sign-in for the user it names |
an agent or a service account cannot start a sign-in |
connection.refused |
an AI agent or a service account starts its own provider sign-in |
No approval opens for a call whose hold a person denied while the hold’s decision window is still open, and none opens past the approval rate of a session or a person. Each such call writes its own deny record and no straza.audit.approval record. Every change of revision 58 is additive.
Revision 57 puts an admin device revoke on the audit chain. A revoke that deletes the device writes exactly one straza.audit.admin record with the action device.revoke, the actor fields of the credential that asked, the device id as target and device, the device’s user and the reason device revoked by admin. When the revoke answers 404 or the database refused its write, no record is written, and a device that strazad revokes because its key was reused keeps its device.key.reused record instead. Built-in straza tools now record a refusal that comes before their record as a deny. The record of a refused straza__draft_submit names finding codes and document numbers and never the documents, and the record of an unknown ref or draft id from approval_status, approval_await or draft_status leaves the value to the arguments field. The change is additive.
Revision 56 ends enrolling an approver device for someone else on an admin route. An enrolled phone or browser is how a person decides, so strazad mints its one-time enroll token only on the self route, for the account signed in there. The admin route POST /v1/admin/approvers/enroll-token answers 403 to every caller that reaches it, whoever the request names, and mints nothing. Each such request writes exactly one straza.audit.admin record with the action enroll-token.refused, the actor fields of the credential that asked and the reason only the person enrolls their own approver phone or browser. A request the admin plane refuses first, such as a token whose scope lacks the approvals area, writes no record, as on every other admin route. The change is additive.
Revision 55 ends strazactl’s sign-in. strazad refuses strazactl’s enrollment and its device credential, and it refuses every check-in or session labelled strazactl. Each refusal writes exactly one straza.audit.authn login failure whose reason is strazactl no longer signs in. The same revision lets an admin API token change a user’s connection on /v1/connect. The straza.identity.updated connection record of such a write carries the token’s id as setBy and the actorVia value api-token, which the admin records already use. A connection record that a person’s write leaves is unchanged and carries no actorVia. Both changes are additive, so a consumer that ignores unknown fields and values reads them as before.
Revision 49 ties an AI agent’s ID token to its key. The built-in issuer names the agent’s registered key in the token, and an admin’s key change ends the agent’s sessions. Two new reason values of a straza.audit.authn login failure come with it, and each refused request writes exactly one such record with the agent’s user and userId.
| Reason | via |
When |
|---|---|---|
the ID token was issued for a key that is no longer registered |
id-token | an AI agent’s ID token names a key that an admin replaced or removed, at a check-in, at GET /v1/self or on any other route that takes an ID token |
the DPoP proof key is not the key the ID token was issued for |
id-token | an AI agent’s check-in whose DPoP proof comes from another key than the one its ID token names |
When an admin replaces an AI agent’s key with a different one or removes it, each active session of the agent ends with one session.end record whose outcome is revoked-admin and whose reason is the agent's key was replaced or the agent's key was removed. The straza.revocation.sessions event of those sessions carries the same reason. Registering the agent’s first key, or the same key again, ends nothing.
An admin write under /v1/admin/, other than the drafts routes and the approve and deny routes, runs to its end once strazad has authorized it, also when the client disconnects, so a disconnect no longer separates the change from its straza.audit.admin record. A write that runs past five minutes answers 503 with a sentence that says the change may or may not have been applied, and until the row and the record commit in one transaction it can keep the change without its record. A SCIM write runs the same way: it runs to its end when the identity manager disconnects, and a write that runs past five minutes answers 503 in the SCIM error shape. The straza.audit.authn and straza.audit.identity records and the straza.identity.* events are written also when the client disconnects, and each write gives up after five seconds on a store that does not answer. A failed write is tried once more under the same id, so a write whose answer was lost leaves no second copy, and a record still not written is logged at Error and counted in straza_outbox_records_lost_total. The approval records follow the same rule. The refusal record of an approver phone is not counted, because the phone’s next refused request writes it again. Each identity setup write that succeeds chains one straza.audit.admin record, also when the client disconnects after the write. A refused write, an enrolment refused before its device is stored and a PATCH, PUT or SCIM DELETE that changes nothing chain none. On every one of these records user is the user’s id, as on every earlier admin record that carries it. No record carries a password, a password hash, an enroll token or a key.
| Action | When | Fields beside target |
|---|---|---|
user.create |
a user is created through the admin API, or over SCIM, where a create that revives a deactivated row counts as a create | user, the new user’s id, username, kind (human or nhi), userType when set, and origin, admin or scim, the lane that created it |
user.update |
an admin API PATCH, or a SCIM PUT, PATCH or DELETE, changes at least one field of a user. A status change sits beside its user.killed, user.reactivated or user.lift.blocked record, before it on the admin API and after it over SCIM, so pair the two by user |
user, username, and changed, the names of the fields that write changed, never their values; username and external_id occur only on SCIM writes |
enroll-token.create |
a person mints an approver enroll token for their own phone or browser on the self route | user, username, channel and self: true |
enroll-token.refused |
the retired admin enroll route refuses a request, whoever it names, because a device enrolls only on the self route, for the account signed in there | reason, and user and username when the request named a user that exists |
approver.enroll |
an approver phone or browser enrolls with its enroll token; the actor is that person, with actorVia enroll-token | user, username, device, platform and name |
nhi-key.set |
an AI agent’s assertion key is registered or replaced | user, username, and fingerprint, sha256 and the hex digest of the public key |
nhi-key.removed |
an AI agent’s key is removed by hand or with its user | user, and reason on a user delete |
approver.revoke |
an admin deletes a person who holds approver phones or browsers, one record per device | user, username, device, and reason, user deleted by admin |
device.revoke |
an admin revokes a user’s machine, one record per device it deletes | user, device, and reason, device revoked by admin |
user.delete |
an admin deletes a user, before the records of the assignments, grants, key and approver devices that end with the user. A 404 or a refused delete writes none | user, username, and reason, user deleted by admin |
Config drafts write straza.audit.admin records whose action starts with draft., and each names its draft in draft. A note, a typed text and a document’s text never enter a record.
| Action | When | Fields beside draft |
|---|---|---|
draft.create, draft.update |
a revision is stored | revision, door (the way the draft came in: console, strazactl, apps-directory, straza-app or api), items as kind, name and op, and digest, the hex SHA-256 of the revision’s items. When they apply: source and sourceHash, the apps directory file and the SHA-256 of its bytes, reverts on a draft that undoes another, rebase: true on a revision made by Check again, and client, sponsor and sponsorId on a draft from an agent’s drafting tools |
draft.check |
strazad stamps a check on a revision, with no actor | revision, snapshot, and the finding codes in refused and risks |
draft.contact |
a person asks Straza to contact a server that a draft proposes, to read its tools | app, host, outcome (answered, refused or failed) and tools, the number of tools the server listed |
draft.publish |
a person publishes, as the actor | revision, items, the resulting snapshot, riskDigest and reviewedDigest, the keys of the risks confirmed in acknowledged and typed, the proposer with proposerId and proposerVia, the client the publisher used, reverts on an undo, and since revision 51 agentLoosened, the sorted names of the policy sets an AI agent’s draft loosened while they bind that agent, which the actor accepted |
draft.discard |
a draft is discarded | revision, reason when one was given, closedBy when another draft’s publish closed a set’s saved edit, and unlinked, the server a discarded removal from the apps directory left in place |
draft.expire |
an open draft passes its expiry, with no actor | revision |
Each composition edge a change adds or removes is one roles.implication.create or roles.implication.delete with target, role, implies and impliesId. Every record a publish writes carries draft, and so do the records of a direct admin write, which publishes a one-item draft in the same request and writes no draft.* record for it.
The policy routes differ. A PUT of a live set’s text records draft.create or draft.update for the set’s saved edit, and no policy.update. A PUT of the published text records draft.discard of the saved edit with the reason the saved text equals the published text. An activate that publishes a saved edit records draft.publish beside policy.update and policy.activate, so a rule keyed on policy.update does not fire on a saved edit.
ruleId and setName name the rule and the policy set that decided, exactly as the engine reported them, and both are the empty string when no rule matched and a profile default decided. The gateway’s own refusals before any decision, an unknown tool or a throttled call, carry no rule either. When a rule allowed a call and a person then denied it, the hold ran out of time, or no credential could be resolved for it, the record is a deny with the allowing rule, its set and the refusal sentence as the reason, on the gateway record and on the hook lane’s tool record alike. A record written under an older revision may lack a field that is always present today, and a consumer never reconstructs a missing name from the policies of the day it reads the record. sourceIp on an authentication event is the transport peer and never a forwarded-for header, and it is absent when no client connection produced the event.
Git grants
Revision 48 records git grants. strazad decides a git grant on POST /v1/grants as a call of the tool that the server’s straza.git.ops maps the operation to, so the record is a straza.audit.mcp record with the event grant and the fields of a tools/call of that tool: tool is mcp.call, app is the server and toolName the mapped tool, such as git_push. arguments holds the repository under the argument the server’s objects block pins, and a push that names updates adds refs, each with ref, old and new, and branch when exactly one of them is under refs/heads/. A grant resolves no credential, so its record carries no credential fields. Git through Straza sets the route up.
strazad writes exactly one record for each grant it issues and for each refusal of the decision: a tool the session cannot see, a tool the session’s policy hides, the rate limit, the object check, a policy rule, and an approval that a person denied or that expired. An issued grant is an allow and adds grant, an object with jti, the grant’s id, op, which is fetch or push, aud, the server’s git address, exp, the grant’s expiry in RFC 3339, and approval, the approval request’s id when one ran. The record’s CloudEvents id is the grant’s dec claim, so a resource server’s log line names the record. The record enters the audit queue before the answer leaves strazad, and under governance.auditBackpressure: block a grant whose record cannot be queued is refused with 503 and never issued.
Some answers write no straza.audit.mcp record. A 202, which says an approval is still open, writes none, because the approval’s own straza.audit.approval record covers the request, and the later request that the person’s decision answers writes the one record. Neither does an answer that comes before the decision or after it failed to produce a grant: a malformed request or a push that names more updates than one grant can carry (400), a session whose token is bound to no machine key or an operation the git block maps to no tool (403), a repository no server lists (404, code not_listed) or two servers list (409, code ambiguous), and a grant strazad could not sign (500). A 401 writes what every session route writes, and POST /v1/grants/resolve decides nothing and writes no record of its own. On both routes, since revision 58, a 403 for a revoked session, device or user, or for an attestation below governance.minAttestation, writes one straza.audit.mcp record with the event request, as /mcp does.
The chain record
A chain record has four fields. seq is the monotonic sequence number, ce is the exact event JSON as published, prevHash is the previous record’s hash, and hash is the hex SHA-256 over prevHash, a newline and ce. The first record’s prevHash is the empty string. The prompt and reply events are the one exception to “as published”: before chaining, the writer removes data.content and adds data.contentBytes beside the client’s contentHash, so the chain witnesses a conversation by hash and size while the text lives only in the retention-bounded transcripts store. Batches of 64 are the writer’s unit: it appends each batch in one transaction with duplicate ids filtered inside it, and leaves linearity to a store-level lock, so several server instances may append at once. When the admin API serves a record it adds username, resolved from data.user at read time, and that field sits outside the hashed bytes so enrichment can never break a record.
Verification
A verifier walks the records in seq order and reports the first record whose prevHash differs from its predecessor’s hash, or whose hash does not recompute from its own prevHash and ce, and a chain with no such record is intact. strazactl audit verify runs that walk over the whole chain and prints audit chain intact: 1234 records verified, or fails with audit chain BROKEN at seq 812 (1234 records checked), where the numbers are the counts of your chain. The console’s Audit screen runs the same walk in the browser over the records it has loaded, and names the sequence number of the first record that fails. The chain proves that no stored record was edited or removed in place. It proves nothing against an attacker who rewrites every later record too, which is why the copy a sink forwards off the box is part of the evidence, as Evidence explains.