Build log/SaaS

Audit logs for SaaS: what to record, how long to keep it and who sees it

An audit log records who did what, to which record, when and from where, and can’t be changed afterwards. Security reviews ask for one, and it helps you show UK GDPR accountability.

The short answer

  • An audit log is an append-only record of important actions in your product, showing who did it, what they did, to which record, when, from where and what changed.
  • Protect it from editing, keep it apart from day-to-day application data, and set a retention period you can justify, because audit logs contain personal data under UK GDPR.
  • Letting each customer’s admins search and export their own audit log answers common security questionnaire questions and supports UK GDPR’s accountability principle, which requires organisations to be able to demonstrate compliance.

An audit log is a permanent, append-only record of the important actions taken in a software product, showing who acted, what they did, to which record, when, from where and what changed. In a B2B SaaS it lets a customer investigate a problem, lets you answer security reviews, and helps both of you show that personal data is handled properly under UK GDPR. It has to be designed in early, because actions that were never recorded can’t be reconstructed later.

What an audit log is, and how it differs from other logs

Products produce several kinds of record, and mixing them up causes problems. Application logs help developers debug and are usually deleted after days or weeks. Analytics events show how features are used. An audit log is evidence, so it is complete for the actions it covers and nobody can edit it.

Audit logApplication logProduct analytics
PurposeEvidence of who did whatDebugging and monitoringUnderstanding how features are used
Read byCustomer admins and your security teamYour engineersYour product team
Can entries change?NeverRarely edited, but often sampled or droppedOften sampled or aggregated
RetentionMonths to years, set deliberatelyDays to weeksVaries
ContainsActor, action, target, time, source and changesErrors, timings and stack tracesEvents and their properties

What to record for each event

  • Who. The user ID, their name and role at that moment, and the tenant. If the actor is an API key, an integration, a scheduled job or one of your own support staff acting on a customer’s behalf, record that too.
  • What. A named action such as invoice.approved, user.role_changed or export.created, and whether it succeeded or was refused.
  • Which record. Its type and ID, plus a readable label such as the invoice number.
  • When. A server timestamp in UTC, never the device’s own clock.
  • Where. The IP address, the device or browser, whether the action came through the web app, a mobile app or the API, and a request ID that links to the application logs.
  • Before and after. The old and new values of each changed field.

Store the name and role as they were at the time. If you only store a user ID and the person is later renamed or deleted, the entry stops making sense.

Which actions to log

Log actions that affect security, money, access or large amounts of data. Logging every page view makes the log too large to search and collects personal data you don’t need. A sensible starting list follows.

  1. Sign-ins, failed sign-ins, password resets and changes to multi-factor authentication.
  2. Users invited, removed or given a different role, and records shared with people outside the customer’s company.
  3. Changes to single sign-on, security settings, API keys and integrations.
  4. Exports, bulk downloads and bulk deletions.
  5. Approvals and changes involving money, such as invoices, payments and price changes.
  6. Any access to the customer’s account by your own support staff.

Viewing especially sensitive records, such as children’s details or health information, can be worth logging too, even though ordinary reads are usually left out.

Making audit logs tamper-evident

An audit log that an administrator can quietly edit is worth very little. These measures make it trustworthy.

  • Append-only by design. The code has no update or delete path, and the database account the application uses can only insert into the audit table.
  • Written with the change. Record the audit entry in the same database transaction as the action it describes, so one can’t exist without the other.
  • Copied somewhere separate. Send entries to separate storage with write-once settings, such as object storage with an object lock, held in a different account from the main application.
  • Chained. Each entry can include a hash of the previous one, so any change or deletion breaks the chain and shows up when the chain is checked.

How long to keep audit logs

For most businesses, no UK law sets a single retention period for audit logs. UK GDPR’s storage limitation principle says personal data should be kept no longer than necessary for its purpose, and audit logs contain personal data such as names and IP addresses. So choose a period, write down why, and apply it automatically.

One workable approach is to keep a period of entries searchable in the product, such as 12 months, and move older entries to cheaper archive storage for longer if customer contracts require it. Records with their own legal retention rules, such as the accounting records HMRC expects a business to keep, are a separate question from how long you keep the log of who edited them.

Showing audit logs to customers

Enterprise customers expect their admins to see their own audit log. Give them a screen that filters by person, action, record and date, an export to CSV and, for larger customers, an API or a feed into their own security monitoring tools. Viewing the log should be a permission of its own (roles and permissions), and every query must be limited to that customer’s tenant.

A history tab on individual records works well alongside it. Someone looking at an invoice can see who created, edited and approved it without opening the full log.

How audit logs help with security reviews and UK GDPR

Security questionnaires commonly ask whether you log administrative actions, how long you keep logs, who can access them and how they are protected from tampering. A properly designed audit log answers all four in a sentence each (security before your first enterprise customer).

Under Article 5(2) of UK GDPR, the accountability principle, a controller must be able to demonstrate compliance with the data protection principles. Under Article 32, both controllers and processors must have appropriate security measures. Audit logs support both, and they become essential after a personal data breach. A controller must report a notifiable breach to the ICO within 72 hours of becoming aware of it where feasible, and must document every breach, reported or not. The audit log is often the quickest way to work out which records were touched and by whom.

For most customer data in a B2B SaaS, you act as a processor for your customer, who is the controller. Your contract will usually require you to tell them about a breach without undue delay, and your audit log is what lets you tell them what happened.

Adding audit logs to an existing product? Get in touch and we’ll look at what your data model needs.

Questions people ask

Does UK GDPR require an audit log?

UK GDPR doesn’t name audit logs as a requirement. It does require appropriate security and the ability to demonstrate compliance, and audit logs are one of the most practical ways to do both. Customers’ contracts and security questionnaires often ask for them directly.

Should an audit log include IP addresses?

Usually yes, because the IP address helps show where an action came from during an investigation. IP addresses can be personal data, so mention them in your privacy information, protect them like the rest of the log and delete them when the retention period ends.

Can a user ask for their audit log entries to be deleted?

A person can ask for their personal data to be erased under UK GDPR, and the right has exceptions, for example where data is needed to comply with a legal obligation or for legal claims. Whether an exception applies to your audit log depends on its purpose and your contracts, so take legal advice and record your reasoning.

Should reads be logged as well as changes?

Logging every read makes the log enormous, so most teams log changes and security events and leave ordinary reads out. Log reads where the data is especially sensitive, or where a customer needs to know who viewed it, such as children’s records or exported reports.

Written by Flavoureak

We build and run Estimark, CurioKids and CalcStack, and we build web and mobile software for other businesses. Start a project.