Audit Trail

Requirement An audit adoption decision MUST record its owner, status, decider, decide-by, audited categories, threshold, access model, integrity method, and records entry.

Rationale The selection, its retention, and its protection are policy choices. A reviewer evaluates the declared policy before evaluating the implementation. No record is approved while this decision is draft. Each audited category carries its retention period and lawful basis. The decision records the bulk-read threshold, the read access model, the integrity method, and the processing-records entry.

Requirement Every Command MUST declare that it is audited, or declare that it is excluded together with the reason for exclusion.

Rationale An implicit selection cannot be reviewed. A total declaration makes an omission a visible statement rather than an absent call.

Example A storefront browse Command declares exclusion because a public catalog read is not a sensitive action.

Requirement An audit selection MUST include authentication, authorization denial, grant change, monetary action, tenant configuration, personal-data read, bulk export, and background-process change.

Rationale These categories carry the questions a security review, a customer, and a supervisory authority ask. A trail that omits one of them cannot answer its own purpose.

Requirement A project MUST NOT audit every Command without a recorded selection.

Rationale An undifferentiated trail buries the sensitive action inside routine traffic. Volume then defeats the review the trail exists to support.

Requirement An audit producer MUST run in the mediation pipeline stages that dispatch the Command.

Rationale Only the pipeline observes the whole attempt, including its outcome. A handler that throws never reaches an audit call placed inside it.

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

Requirement A handler MUST contribute only the audit values that the handler alone determines.

Rationale A generated target identity and a composed reason are unavailable before the handler runs. Every other field comes from the declaration, the actor, and the request context.

Example A create handler contributes the identity it generated. It contributes no actor, action code, or timestamp.

Requirement An audit trail MUST NOT be derived from domain events, database triggers, or change data capture.

Rationale These sources describe committed state change. They carry no refused attempt, no use-case identity, and no request origin.

Requirement An audit record MUST contain actor, action, target, outcome, business time, record time, and tenant, fixed where the tenancy extension is absent.

Rationale These fields carry the accountability question. Business time states when the action happened. Record time states when the evidence was written. Actor and target each carry kind and identity.

Requirement An audit action MUST use the identity of the use case that the actor invoked.

Rationale A reviewer resolves the record to the specification that defines the intended behavior. A separate vocabulary requires a mapping that drifts.

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

Requirement An audit record with a denied or failed outcome MUST carry the stable failure code that the attempt produced.

Rationale The code distinguishes a refused permission from an exhausted precondition, which are different review findings.

Requirement An audit record MUST carry an explicit schema version.

Rationale A retained record outlives several shapes of the application that wrote it. The version keeps an old record readable without rewriting it.

Requirement An audit actor MUST be one of person, company, provider, system, or guest.

Rationale An absent actor collapses three answers into one. A scheduled process acted, a device acted, or no one recorded the actor. Only the third is a defect. A device maps to the person whose account authorized it. The device appears as the client description. A named process maps to system.

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

Requirement An action that an actor takes under an administrative or support grant MUST record that the grant was used.

Rationale A supplier-side action and a customer-side action are indistinguishable without this field. The distinction is what makes a no-silent-access commitment demonstrable.

Requirement An audit record MUST carry an outcome of succeeded, denied, or failed.

Rationale A trail of successes is a change history. The refused attempt carries the security signal.

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

Requirement An authorization decision that refuses an audited action MUST produce an audit record.

Rationale Repeated refusal is the primary indicator of a compromised or probing account. No other record holds it.

Requirement An audited action that the actor was permitted to take and that did not complete MUST produce an audit record.

Rationale A permitted attempt that fails repeatedly separates an operating defect from an access problem.

Requirement An audit record produced from an inbound request MUST carry the request origin address, the client description, and the request identifier.

Rationale Two records naming one account state nothing about location. The same records from two countries within one minute state that the account is compromised.

Requirement An audit record MUST carry the trace identifier of the operation that produced it.

Rationale The identifier joins the evidence record to the diagnostic detail. An investigation without it stops at the audit record.

Requirement An audit record MUST NOT contain a credential, token, session identifier, encryption key, or payment instrument value.

Rationale A retained, widely readable, append-only store is the worst location for a secret. Retention then extends the exposure.

Requirement An audit record MUST NOT contain personal data other than the pseudonymous identifier of the actor and the target.

Rationale A record holding a name, an address, or a message body turns retention into an erasure conflict. An identifier keeps the record meaningful and erasable.

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.

Example 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.

Requirement An audit record MUST NOT contain a copy of the state before or after the audited change.

Rationale The domain event stream already holds the change under its own retention. The trail adds the actor and the reason, which nothing else holds.

Requirement An audit record with a succeeded outcome MUST commit in the same database transaction as the change it describes.

Rationale One transaction makes the action and its evidence inseparable. Neither an unrecorded action nor a record of a rolled-back action can exist.

Requirement An audit record with a denied or failed outcome MUST be written on a connection that the failing transaction does not roll back.

Rationale The transaction that would carry the record is the one being abandoned. The evidence of a refusal outlives the refusal.

Requirement An audit producer that stages a success record MUST run before the pipeline stage that commits the business transaction.

Rationale A record staged after the commit reaches a closed transaction. Pipeline ordering therefore carries an explicit priority rather than a registration order.

Requirement An audit deployment MUST publish the write failure count of its unsuccessful-outcome path.

Rationale The separate connection accepts a rare lost record at process death. Continuous loss is a defect. Only a published indicator separates the two.

Requirement An audit record describing an action inside tenant-owned data MUST carry the identity of that tenant.

Rationale The tenant is the filter for every read of the trail. A trail without it serves an internal reviewer and no customer.

Requirement An audit store MUST refuse update and delete through the privileges granted to the writing account.

Rationale An absent code path is a convention. A reviewer can verify a revoked privilege.

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

Requirement An audit store MUST chain each record to its predecessor with a SHA-256 hash over a canonical serialization of both.

Rationale A chain detects an edit and a removal, because a changed or missing record breaks every following value. Detection is the obligation. 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.

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

Requirement An audit store SHOULD publish a periodic checkpoint of its chain head to a destination that the store's own operators cannot rewrite.

Deviation: A store whose recorded threat model excludes its own operators publishes no checkpoint.

Rationale A chain proves that records are consistent with each other. It does not prove that the whole chain was not recomputed, which anyone holding the store can do. A checkpoint someone else holds fixes the chain as it stood at that moment. A later recomputation disagrees with it.

Example 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.

Requirement An audit deployment MUST verify its integrity chain on a recurring schedule and raise an alert on a break.

Rationale Unverified tamper evidence proves nothing. The verification result is the evidence a reviewer receives.

Requirement A correction to the trail MUST be a new record that references the earlier one.

Rationale An edited history carries no evidential value. The correction and the original both stay visible.

Requirement An audit deployment MUST delete a record after the retention period declared for its category.

Rationale An indefinite period is the hardest retention to defend and the easiest to correct at design time.

Requirement An erasure request MUST remove the mapping from actor identifier to person and retain every audit record.

Rationale The record keeps its evidential value. The person stops being identifiable from it. This depends on the record holding no personal data.

Requirement An audited system MUST provide a trail read as a use case needing a Permission record, filtered by tenant, actor, action, target, and outcome.

Rationale A trail that no use case reads is storage rather than a control. The actor holds a Role at a scope. The Role allows the Permission. The guard permits the read.

Requirement A read of the audit trail MUST itself produce an audit record.

Rationale Access to the evidence is a sensitive action. An unrecorded read leaves the reviewer outside the trail.

Requirement A query returning personal data across a boundary MUST produce an audit record, defining the account boundary in the adoption decision where tenancy is absent.

Rationale A read leaves no state change and therefore no other trace. Disclosure without a record cannot be investigated.

Requirement A query returning personal data for more subjects than its declared threshold MUST produce an audit record, inside one tenant or account boundary as well.

Rationale The cross-boundary rule catches a disclosure to the wrong party. It does not catch an export of every record a party may read one at a time. That is the shape a copied dataset has. Article 30 of the GDPR asks what categories of data were processed and by whom. An unrecorded bulk read cannot answer either.

Example 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.

Requirement An export that returns a set of records to a caller MUST produce an audit record naming the requested scope.

Rationale Bulk extraction is the highest-consequence read in most products. The scope states what left the system.

Requirement An automated check MUST fail when a Command declares neither audited nor excluded status, with a composition refusal at startup satisfying this rule.

Rationale The next Command is written by someone who did not read this page. Only an automated gate catches it.