Audit Trail

Which actions to audit, how long to keep them, and how to protect them are policy choices, so the project declares them once in the adoption decision. A reviewer reads the declared policy before reading the implementation instead of reconstructing it from the code, which would give two reviewers two different policies.

Reviewed forWhich adoption decisions lack categories, threshold, access model, integrity method, or records entry? Look at the adoption decision behind the audited Commands.

Marked guidance: a reviewer answers this question.

An audit selection that lives only in code is invisible: a reader cannot tell an unaudited command from an audited one whose call is missing. The audit field states the reason of required, optional, or none with its target, or the exemption with its justification, so each omission becomes a visible statement. Commands are audited by default with reason none. litespec/core/use-cases#state-the-audit-position-of-every-command states the field, and review reads the selection instead of hunting for missing calls.

A storefront browse command declares an exemption because a public catalog read is not a sensitive action.

Reviewed forWhich command use cases lack an audit position or an exemption with its justification in their audit field? Look at the use case pages.

Marked guidance: a reviewer answers this question.

The actor, the origin, and the grant exist when the request arrives; the later run carries worker identity under system auth, which says nothing about who asked. Writing the record at request time ties the attempt to the caller who made it. A record written when the background run starts would attribute every scheduled and deferred act to the worker instead of the requester.

Reviewed forWhich deferred runs write their audit record at run time instead of request time? Look at the audit rows beside the requesting calls.

Marked guidance: a reviewer answers this question.

Each listed category answers a question a security review, a customer, or a supervisory authority asks after an incident: who signed in, who was refused, who changed a grant, who moved money, and the rest. A trail that omits a category has no answer when that question arrives. The list fixes the floor so no project discovers the gap during its first review.

Reviewed forWhich required categories have no selection entry? Look at the declared selection beside the eight listed categories.

Marked guidance: a reviewer answers this question.

A trail that records every Command buries the sensitive action inside routine traffic, and the reviewer who has to read it stops reading. Volume then defeats the review the trail exists to support. A recorded selection keeps the trail small enough to read.

Reviewed forWhich audited categories lack a recorded selection reason? Look at the declared selection.

Marked guidance: a reviewer answers this question.

Only the pipeline stages that dispatch the Command observe the whole attempt, including attempts the handler never reaches. An audit call inside the handler misses every attempt that throws before it and every refusal the pipeline makes. The pipeline is therefore the one place that records all three outcomes.

A pre-handler opens the audit scope, a post-handler closes it as succeeded, and an error handler closes it as denied or failed.

Reviewed forWhich audit writes run inside handlers instead of the mediation pipeline? Look at the producer stages and the handler code.

Marked guidance: a reviewer answers this question.

The declaration beside the message already fixes the audit target and the reason value the message carries, as litespec/backend/application#declare-audit-values-beside-the-message requires, so the pipeline records both on every outcome, including a denial. Only the handler knows the values it learns while running, such as a generated target identity or a reason value composed from loaded state. Letting the handler write the rest invites a second copy of each field that drifts from the first.

A create handler contributes the identity it generated. It contributes no actor, action code, timestamp, or value the message already carries.

Reviewed forWhich handler contributions repeat the declared target or reason value, the actor, action code, or timestamp? Look at the handler audit calls.

Marked guidance: a reviewer answers this question.

Domain events, triggers, and change data capture describe committed state change. They carry no refused attempt, no use-case identity, and no request origin, which are the fields a reviewer reads. A trail derived from them answers what changed and never who attempted it.

Reviewed forWhich trail writes derive from events, triggers, or capture? Look at the producer source.

Marked guidance: a reviewer answers this question.

Actor, action, target, outcome, the two times, and the tenant together answer who attempted what, against whose data, with what result, and when. Business time states when the action happened and record time states when the evidence was written, so a delayed write stays visible as a delay. A record missing any of them leaves the accountability question half answered.

Reviewed forWhich records lack actor, action, target, outcome, business time, record time, or tenant? Look at the stored audit rows.

Marked guidance: a reviewer answers this question.

A reviewer who reads an action value opens the specification of that use case to learn the intended behavior. A separate action vocabulary needs a mapping to those specifications, and the mapping drifts as both sides change. Reusing the use-case identity keeps record and specification joined with no mapping to maintain.

catalog.add-product names both the use case and the audited action.

Reviewed forWhich action values name something other than the invoked use case? Look at the action column beside the use case pages.

Marked guidance: a reviewer answers this question.

A refused permission and an exhausted precondition need different responses, but both look like failure without a code. The refusal code tells the reviewer which one the attempt produced. It also lets trend queries count one kind of refusal across the whole trail.

Reviewed forWhich denied or failed records lack the refusal code? Look at the unsuccessful audit rows.

Marked guidance: a reviewer answers this question.

A retained record outlives several shapes of the application that wrote it. An explicit version lets a later reader parse each record in the shape it was written in. Without it, every shape change forces a rewrite of retained evidence.

Reviewed forWhich records lack an explicit schema version? Look at the stored audit rows.

Marked guidance: a reviewer answers this question.

An absent actor collapses three answers into one: a scheduled process acted, a device acted, or no one recorded the actor, and only the third is a defect. The five kinds separate them: a device maps to the person whose account authorized it, with the device as the client description, and a named process maps to system. A free-text actor would let each writer spell the same actor differently and break every actor filter.

A warehouse handheld records the person actor whose account authorized it. The origin record names the device.

Reviewed forWhich actor values fall outside the five actor kinds? Look at the actor column, with devices and processes mapped.

Marked guidance: a reviewer answers this question.

Support staff act inside customer data under a grant, and without a marker their actions read exactly like customer actions. The marker makes a no-silent-access commitment demonstrable: every supplier-side action says so on its own record. A reviewer who cannot separate the two cannot verify the commitment.

Reviewed forWhich support-grant actions lack the grant marker? Look at the records of actions under administrative grants.

Marked guidance: a reviewer answers this question.

A trail of successes is a change history, not evidence. The refused attempt carries the security signal, and the failed attempt carries the operating signal. Three outcomes keep both signals in the same trail as the successes they qualify.

succeeded names a committed change, denied names a refused authorization, and failed names a permitted attempt that did not complete.

Reviewed forWhich records lack a succeeded, denied, or failed outcome? Look at the outcome column.

Marked guidance: a reviewer answers this question.

Repeated refusal is the first indicator of a compromised or probing account, and no other record holds it: nothing changed, so nothing else was written. Each refusal therefore writes its own record. A trail without refusals shows an attacker who never failed.

Reviewed forWhich refused authorizations produced no denied record? Look at the refusal paths beside the trail.

Marked guidance: a reviewer answers this question.

A permitted attempt that throws is neither a success nor a refusal, and without a record it vanishes entirely. Writing it separates an operating defect from an access problem: failures cluster around broken behavior, denials cluster around missing permission. Support reads that split before it reads the logs.

Reviewed forWhich permitted attempts that threw produced no failed record? Look at the error paths beside the trail.

Marked guidance: a reviewer answers this question.

Two records naming one account state nothing about location. The same account acting from two countries within one minute states that the account is compromised, but only when each record carries origin, client, and request identifier. The request identifier further joins the record to the exact request in the diagnostic log.

Reviewed forWhich request-produced records lack origin, client, or request identifier? Look at the inbound-request audit rows.

Marked guidance: a reviewer answers this question.

The audit record states what was attempted, and the diagnostic log states what the software did while attempting it. The trace identifier joins the two, so an investigation moves from evidence to detail in one step. Without it, the investigation stops at the audit record and reconstructs the rest by time.

Reviewed forWhich records lack the trace identifier of their operation? Look at the stored audit rows.

Marked guidance: a reviewer answers this question.

The trail is retained, widely readable, and append-only, which is the worst combination for a secret: retention extends the exposure and append-only removes the repair. A credential or payment value written once stays readable for the whole retention period. Secrets and payment values therefore travel in the systems built to hold them, never in the trail.

Reviewed forWhich records contain a credential, token, session identifier, key, or payment value? Look at the stored audit rows.

Marked guidance: a reviewer answers this question.

A record holding a name, an address, or a message body turns retention into an erasure conflict: the law asks for deletion and the trail asks for keeping. Pseudonymous identifiers keep the record meaningful while the mapping lives, and erasable once the mapping goes. The record then survives erasure instead of fighting it.

A pseudonymous identifier is still personal data where the party holding it can reverse it. That is the position the EDPB states. The identifier is therefore safe inside the tenant that owns the mapping. It is a disclosure when it leaves that tenant.

An audit export crossing a tenant boundary replaces each identifier with one derived for that export. The receiving party then cannot join the records back to a subject.

Reviewed forWhich records contain personal data beyond pseudonymous actor and target identifiers? Look at the stored audit rows.

Marked guidance: a reviewer answers this question.

The domain event stream already holds each change under its own retention. Copying before and after state into the trail duplicates that storage and widens every record with data the reviewer did not ask for. The trail adds the actor and the reason value, which nothing else holds, and leaves the change itself to the stream.

Reviewed forWhich records contain before or after state copies? Look at the stored audit rows.

Marked guidance: a reviewer answers this question.

One transaction makes the action and its evidence inseparable: the change commits with its record or neither commits. Separate writes admit both an unrecorded action and a record of a rolled-back action. Either one leaves the trail disagreeing with the data it describes.

Reviewed forWhich succeeded records commit outside their business transaction? Look at the success write path.

Marked guidance: a reviewer answers this question.

A denied or failed attempt ends with its transaction rolling back, which would take a record written inside it. The record therefore travels on a connection the rollback does not touch. The evidence of a refusal outlives the refusal itself.

Reviewed forWhich denied or failed records roll back with their transaction? Look at the unsuccessful write path.

Marked guidance: a reviewer answers this question.

A success record staged after the commit reaches a transaction that is already closed, so the write has nowhere to land. The producer therefore runs before the pipeline stage that commits. Pipeline priority states that order explicitly instead of leaving it to registration order.

Reviewed forWhich audit stages run after the business commit stage? Look at the pipeline stage order.

Marked guidance: a reviewer answers this question.

The separate connection for unsuccessful records accepts a rare lost record when the process dies between the refusal and the write. Continuous loss is a defect, not bad luck, and only a published count separates the two. The deployment publishes that count so monitoring tells rarity from breakage.

Reviewed forWhich deployments publish no write failure count for the unsuccessful path? Look at the published metrics.

Marked guidance: a reviewer answers this question.

The tenant is the filter for every read of the trail: each customer reads its own records and no one else's. A record without a tenant identity serves an internal reviewer and no customer. Scoping every record at write time keeps that filter exact.

Reviewed forWhich records on tenant-owned data lack the tenant identity? Look at the tenant column.

Marked guidance: a reviewer answers this question.

An audit store that relies on absent code paths stays append-only until someone writes the missing path. Revoked privileges refuse update and delete no matter what the code attempts. A reviewer verifies a privilege in the database instead of auditing every line for a missing write.

The application account holds INSERT and SELECT on the audit table. It holds neither UPDATE nor DELETE.

Reviewed forWhich writing accounts hold update or delete on the audit store? Look at the granted store privileges.

Marked guidance: a reviewer answers this question.

The hash chain detects an edit and a removal, because a changed or missing record breaks every value after it. Detection is the obligation: it lets a reviewer prove the trail is intact. Prevention at a higher cost is not required.

The algorithm is named because two implementations that each choose their own cannot verify each other. A verifier written later cannot recompute a chain whose algorithm no one recorded. Canonical serialization is named for the same reason. A hash over a serialization that reorders fields verifies nothing.

The chain value is SHA-256(previousHash || canonical(record)), where canonical sorts object members and uses one fixed encoding for every timestamp and number.

Reviewed forWhich records lack the chained SHA-256 hash over the canonical serialization? Look at the stored chain values.

Marked guidance: a reviewer answers this question.

A chain proves that records agree with each other, but anyone holding the store can recompute the whole chain and keep it agreeing. A checkpoint held somewhere the operators cannot rewrite fixes the chain as it stood at that moment. A later recomputation disagrees with the checkpoint, which exposes it.

The checkpoint is the chain head and its record count, published at a stated interval. A separate append-only destination, a timestamping authority, and a transparency log each qualify.

Reviewed forWhich stores publish no checkpoint outside operator reach? Look at the checkpoint destination and the threat model.

Marked guidance: a reviewer answers this question.

Tamper evidence nobody checks proves nothing: a break sits in the store until someone looks. Scheduled verification turns the chain into a standing claim the deployment re-proves on each run. The alert carries the break to an operator instead of waiting for the next review.

Reviewed forWhich deployments run no scheduled chain verification with an alert? Look at the integrity job and its alerts.

Marked guidance: a reviewer answers this question.

An edited history carries no evidential value, because the reviewer cannot tell a correction from a cover-up. A new record that references the earlier one keeps both visible: the mistake and its fix. The trail then shows its own repairs instead of hiding them.

Reviewed forWhich corrections edit history instead of adding a referencing record? Look at the correction records.

Marked guidance: a reviewer answers this question.

Each category declares its retention in the adoption decision, and the deployment deletes records when that period ends. Deletion on schedule keeps retention defensible: kept data has a declared reason and nothing kept lacks one. An indefinite period is the hardest retention to defend and the easiest to correct at design time.

Reviewed forWhich records outlive the declared retention of their category? Look at the stored rows beside the adoption decision.

Marked guidance: a reviewer answers this question.

Erasure asks that the person stop being identifiable, while accountability asks that the record stay. Removing the mapping from identifier to person satisfies both: the record keeps its evidential value and no longer points at anyone. This works only because the record holds no other personal data.

Reviewed forWhich erasures leave the actor mapping or delete audit records? Look at the erasure handling and the retained rows.

Marked guidance: a reviewer answers this question.

A trail no use case reads is storage, not a control. The read path is a use case with its own access grant: the actor holds a role at a role scope, the role allows the permission, and the grant permits the read. Tenant, actor, action, target, and outcome filters keep each reader inside the records they may see.

Reviewed forWhich trail reads lack an access grant or a declared filter? Look at the trail read use case.

Marked guidance: a reviewer answers this question.

Reading the evidence is itself a sensitive action: the trail shows who did what across the whole product. A read that writes no record leaves the reviewer outside the trail. Recording each read puts the reviewer inside the same accountability as everyone else.

Reviewed forWhich completed trail reads produced no audit record? Look at the trail read path.

Marked guidance: a reviewer answers this question.

A read changes no state and therefore leaves no other trace, so a disclosure without a record cannot be investigated. The audit record on a cross-boundary personal-data query states who read whose data and when. Where tenancy is absent, the adoption decision defines the account boundary the rule watches.

Reviewed forWhich cross-boundary personal-data queries produced no record? Look at the query paths beside the trail.

Marked guidance: a reviewer answers this question.

The cross-boundary rule catches a disclosure to the wrong party, but it misses an export of every record a party may read one at a time, which is the shape a copied dataset has. A query above the declared threshold therefore writes a record even inside one boundary. Article 30 of the GDPR asks what categories of data were processed and by whom, and an unrecorded bulk read answers neither.

A project records the threshold in the adoption decision. A list endpoint whose page size can exceed it audits the read with the subject count rather than the subjects.

Reviewed forWhich above-threshold queries produced no record with the subject count? Look at the bulk query paths.

Marked guidance: a reviewer answers this question.

Bulk extraction is the highest-consequence read in most products: one call moves a dataset across the boundary. Naming the requested scope states what left the system. Without it, the project learns the shape of a leak from the party that received it.

Reviewed forWhich exports produced no record naming the requested scope? Look at the export paths.

Marked guidance: a reviewer answers this question.

The next Command is written by someone who did not read this page. Only an automated gate catches it: the build or startup fails while the declaration is missing. A selection that depends on every author remembering is a selection with holes.

Reviewed forWhich Commands build or start with no audit position or exemption? Look at the build or startup gate.

Marked guidance: a reviewer answers this question.