Audit Trail

Which events should I log?


There is no "one size fits all" answer to the question: "Which events should I be logging?"

The ISO 27002:2013 standard is often used as a reference to determine events to log. It gives a very thorough overview of what enterprise customers want to have in their event logs. But, there are some very broad terms in the standard. Terms like “system activities,” “key events,” and “use of system utilities and applications.”

This guidance is nice, but it's rather broad. Not particularly actionable. There's a few key questions that remain unanswered, such as:

  • “How do we determine exactly what 'activities' and 'events' and 'uses' are necessary to send to the audit trail?” and
  • "Which events should I be logging that are specific to my application?"
  • To answer the first question, we have to differentiate between audit trails and system logs. After that, we'll cover necessary security events to log. These will surface and provide insight into any potential misuses or abuses of your application.

Finally, after covering those general requirements, we'll explore constructing meaningful, application-specific events. To do so, it's important to ask:

  1. “Who are the people that are going to be managing my product, and reading these logs?”
  2. “What questions will they want to answer with a log of our events?”

Events to log

System Logs vs. Audit Trail

To begin, it's helpful to understand which events not to log. So, let's start by differentiating between system logs and an audit trail.

System Logs

As developers, we enjoy system-level logs all the time. System logs help us with tasks related to technical implementation. (Consider the contextual logs you use for error handling or diagnosing performance issues.) To perform those tasks, system logs are comprehensive. They record every event to answer the general question: “What's happening?” This makes them great for monitoring feedback during development. That way, when something breaks, it's fixed soon as possible.

Audit Trail

To contrast, an audit trail records application-level events. These are events that are relevant to answering the specific question: “Who did what and when?” Audit trails also have stricter requirements than system logs surrounding their use. These requirements can include: data immutability, how they're stored, and how they're accessed. Audit trails can contain sensitive or personal, identifiable information as well. So, they're also held to regulatory and compliance standards that system logs are not.

Asking that question: “Who did what and when?” will provide an excellent starting point to begin defining and naming events from.

Security events to log

It's important to define the level and content of security events in the early design stages of a project. Decide what sensitive data you'll be working with as early as possible. Doing so will help decide the security events you should log.

As best practices go, strive to log the following events when possible:

  • Authentication failures and successes
  • Authorization failures and successes
  • Admin Configuration changes
  • Privilege uses and changes
  • Login failures and successes
  • Data access, export failures and successes
  • Anti-automation detection
  • File modifications
  • Session management failures

There are many industry-specific security compliance standards. While they have stricter, longer requirements for events to log, it's safe to start with the list above.

Application-specific events to log

Like we started, there's no “one size fits all” solution to logging events. Especially for application-specific activities. After all, those specific activities are what make your application unique!

Choosing to log every action will generate noise, and likely cause confusion. This means that actual problems will likely go undetected and unresolved. So, it's important to consider: who's going to be using these logs? What questions will they want to answer?

The customers using your audit trail are often going to be IT managers. They're generally going to be asking questions like:

  • “How can I maintain individual accountability of each of the people using my systems?”
  • “Am I able to reliably reconstruct events after a problem has occurred?”
  • “How can I identify intrusion attempts or behaviors performed with unauthorized access?"

By asking these questions and carefully naming the actions that answer them, you'll generate a set of events unique to your application. Doing so will be invaluable to your customers.

Example Events

Productivity tools

  • user.added_integration
  • user.invited_observer
  • user.exported_team_data

Communication tools

  • user.joined_team
  • user.changed_channel_history
  • user.added_bot

Platform as a Service products

  • user.promoted_staging
  • user.promoted_production
  • user.deploy_failed