Decide what your web app must record in its audit log

Start with the question a reviewer must answer

A small team discovers a disputed loan approval. The current record says “approved”, but that alone cannot show who made the decision, when it took effect or whether a later retry changed it. This is a useful audit question. “Save everything in case we need it” is not: it leaves the team with private data to protect and a search problem when something goes wrong.

List the decisions, access changes and data movements for which a named owner needs reconstructable history. For each, write the future question: “Who granted this role?”, “Was this export completed?”, “Was this request denied before anyone changed the record?” OWASP says application logging should be set during requirements and design, proportionate to risk, and warns that a blind checklist can create alarm fog. It distinguishes security events from process and transaction trails, which may need different records and access. This guide makes that selection; the permission-matrix guide defines who is allowed to perform an action in the first place.

Choose events by consequence, not by screen count

Make an inventory of meaningful actions: sign-in success and failure; denied access; account and role changes; use of exceptional administrator access; approval or status decisions; import, export and deletion; consent changes; and opening the audit history itself. OWASP identifies authentication outcomes, access-control failures, higher-risk administration, imports and exports, and relevant opt-ins among events to consider. An ordinary page view or keystroke does not become an audit event merely because it is easy to capture.

Separate attempted, denied, committed, failed and reversed outcomes. A click is only an attempt. Record “completed” after the authoritative change succeeds; record a safe failure if it does not. An asynchronous export can need a request event and a later completion or failure event joined by one job reference. A history that reports an approval or export as complete before the underlying operation is durable misleads the reader. Agree the point of success for each action before implementation.

A user-visible activity timeline may need friendly explanations, while restricted security history needs signals that can support investigation. Product analytics answers aggregate usage questions and may have a separate consent and retention basis. Do not send attributable audit events, raw record IDs or sensitive values into a general analytics stream to save implementation effort.

Copy the event-selection and retention worksheet

Create one row per event family and materially different retention rule. The downloadable CSV contains a blank template row and the completed fictional rows below, using the same fixed columns. Record “no audit event” explicitly when the team considered an action and found no audit purpose. That decision helps prevent later blanket logging.

• Event family | Trigger and outcome | Purpose and reviewer | Actor and target reference | Minimal recorded fields | Explicit exclusions | Retention start and period | Access and disposal owner | Failure or abuse test.
• Trigger and outcome: say whether the event is created on an attempt, denial, committed change, failed job or reversal. Name the authoritative point that proves the result.
• Purpose and reviewer: identify the question this event answers and the team allowed to investigate it. If nobody can name a purpose, reconsider collection.
• Actor and target reference: use stable internal IDs where attribution is necessary. Distinguish a human, service account and unknown unauthenticated attempt; never claim an unknown actor is a named person.
• Minimal recorded fields: normally consider UTC event time, event code, actor and target references where justified, outcome, bounded reason or state codes, and a correlation or job ID. Add a field only if a reviewer needs it.
• Explicit exclusions: prohibit credentials, tokens, session IDs, raw request or response bodies, full documents, free text and sensitive personal values unless a separate, justified evidence store is designed for them. Treat supplied labels and identifiers as untrusted input.
• Retention start and period: specify the clock trigger, duration, applicable obligations and review owner. State what happens to replicas, exports and backups at expiry; do not assume deleting a database row deletes every copy.
• Access and disposal owner: restrict who can search, read and export history; record access to that history; assign a person to verify expiry and exception handling.
• Failure or abuse test: prove the event appears once with the right outcome, remains readable only to approved reviewers, rejects injected or secret values, and behaves predictably if logging or storage fails.

Hypothetical example: a shared-equipment loan app

Imagine a small organisation that lends equipment to members. Staff approve requests, manage accounts and can export loan data. This is invented solely to show a completed worksheet; it describes no Kinetivy client, deployed system or recommended universal retention rule. Read each row in the column order above. All five non-empty periods are illustrative choices for discussion and need business, technical and applicable legal or contractual review before use.

• Sign-in failure | Authentication rejected | Detect repeated account abuse; security owner | Attempted account ID if valid, otherwise anonymous; no item | UTC time, event code, result, bounded reason, correlation ID | Password, token, raw form body, full URL | Attempt time; illustrative 30 days | Security owner; restricted log, expiry deletion | Bursts and unknown-account attempts retain safe events without passwords.
• Loan decision | Approval or denial committed, or decision attempt failed | Explain who decided a loan; operations owner | Authenticated staff ID and loan ID | UTC time, action, result, prior and new status when committed, policy version, correlation ID | Free-text request, borrower contact, document contents | Each decision event time; illustrative 12 months | Operations owner; approved reviewers, expiry deletion | Double submit yields one committed decision event; a failed commit records failure, never success.
• Role change | Permission grant or revoke committed, or attempted change denied | Investigate access changes; security owner | Acting staff ID and affected account ID | UTC time, action, role code, result, correlation ID | Password, email, whole account profile | Each change or denial time; illustrative 12 months | Security owner; restricted review, expiry deletion | Self-grant is denied and safely logged; revocation is captured.
• Bulk export | Export requested, completed, failed or denied | Trace sensitive data movement; data owner | Actor ID and request/correlation ID; export job ID only if created | UTC time, action, scope code, count when known, result, correlation ID | Export rows, download URL or token, raw filter | Each request or outcome time; illustrative 12 months, including requests left pending | Data owner; restricted review, expiry deletion | Unauthorized export is denied and logged; retry does not duplicate a completed result.
• Audit-history read | History opened, exported or access denied | Detect misuse of audit access; security owner | Reviewer ID and query or job ID | UTC time, purpose code, scope code, result | Search text and copied log bodies | Each access attempt time; illustrative 90 days | Security owner; separate restricted log, expiry deletion | Unprivileged reader is denied and safely logged.
• Routine item-page view | Ordinary view | No audit purpose; product owner | None | No audit event; consider only separately approved aggregate analytics | Item titles, borrower identity, page query | None | Product owner; no audit record | Repeated browsing produces no audit event.

Make the history trustworthy and appropriately private

OWASP frames useful log attributes as when, where, who and what, but also says the detail should match the purpose. A stable account ID can support attribution without copying a name, email or complete profile into each event. Record a service-account ID for background jobs and connect it to the initiating person or approved schedule where that relationship exists. A correlation ID helps join a request, job and outcome; it must not be a secret token or a full URL containing private parameters.

Define an allowlist of fields for each event. Remove or mask secrets and sensitive data before storage, sanitize untrusted text against line breaks and delimiter injection, and test the displayed history as well as the stored record. OWASP lists passwords, access tokens, session identifiers, sensitive personal data, bank or card details and higher-classification information among data that should usually be excluded or protected. The UK Information Commissioner’s Office describes personal-data minimisation as keeping information adequate, relevant and limited to the purpose; the precise law applying to a real app depends on its context.

Use restricted write and read paths, protect transfer and storage, and detect unauthorized edits or deletion. OWASP recommends limiting log-read privileges, monitoring access and using tamper detection. A log is evidence with limits: a shared account, compromised administrator or missing event can weaken attribution, so do not promise that every entry proves which human acted. Keep an operational alert for logging that stops, and decide in advance which high-risk actions must pause if their required audit record cannot be written. Test that decision; do not silently report a completed action with no required history.

Set retention per purpose, then test expiry and failure

Do not copy an arbitrary number of days across authentication, business decisions and exports. Start with the investigation or accountability window each purpose needs, then check legal, contractual and operational duties with the responsible owner. Record when the clock begins, how authorized exceptions are approved, and when stored copies and backups age out. NIST SP 800-92 is a log-management guide covering infrastructure and operational processes; OWASP says logs and temporary copies should be kept for the required period and no longer. The ICO’s storage-limitation guidance asks organisations to justify periods, review them, and erase or anonymise personal data once it is no longer needed. None prescribes the fictional periods above.

Run a small release test set: a successful and a denied high-risk action; a request that fails before commit; a delayed job that later completes; duplicate submission; a role revoked while a page remains open; a value containing a newline or delimiter; an attempted secret in a field; a reviewer without audit access; and loss of the log store. Confirm the record, event outcome, reviewer view, alert and business action all agree. Also test expiry in the primary store and copies. OWASP explicitly calls for logging verification, injection resistance, access checks and simulated logging failures.

Review the worksheet when a new role, export, integration, record type or retention obligation changes the app. The approval-workflow guide covers who decides and how a decision is routed; the login guide covers account recovery; the analytics guide covers aggregate measurement. This worksheet remains the source for which actions leave an attributable, protected history and for how long.