11 best-practice security event logging guidelines

Logging is one aspect of ensuring some level of application security. The purpose of logging is to:

• have a basis for representing and monitoring application health
• have data necessary to investigate and fix possible issues and to address security incidents

This article focuses on the security side of logging and how it could be implemented effectively to support prompt investigation of incidents and minimise adverse impact on business.

For those applications or integrations in the Xero ecosystem (though this could be extended to other applications as well), we’ve pulled together the following guidelines to help you set up your logging.

11 security event logging guidelines

1. Define a Data Retention Policy and align on what is logged and for how long within that policy. The terms and content could be specific to your business and may depend on local legislation or other standards and compliance requirements you may follow. Audit logs must be retained for as long as appropriate to enable future investigation. In most cases logs should be kept for a minimum of one year.

2. Design log entries to be clear, unambiguous and understandable for later analysis. You should be able to easily tell:

• all the activities taken or attempted by a user or by the application
• whether the activities were successful or not
• resources participating in the activities
• targets affected by the activities
• when the activity took place and where it originated from
• what user or application session the activity is linked to

3. Record authentication and authorisation events. An ‘authentication event’ is when a user or an application is logging in or attempting to log in. An ’authorisation event’ is when a user or an application is performing, or attempting to perform, an action which requires a pre-defined permission or role, eg a permission to send an invoice, to generate a report.

In the case where your application does not define permissions and it is assumed that a logged in user can perform any action within the application, still consider these actions as security events (and log these events appropriately).

4. Ensure you have logs of all security events originating from the systems, applications and services you support.

5. Have some form of risk assessment or threat modeling that helps with listing all possible authentication and authorisation related events to log.

6. Include into the log records at least the following:

• Timestamp of when the event took place. In ETC/UTC, synchronised to an NTP source, stratum 1, 2 or 3. Format according to ISO 8601 or other standard, e.g. seconds/milliseconds since epoch.
• User identifier. This could be a unique userID but not a user login name which is considered sensitive and should not be logged.
• A description of the activity being performed by the user or application.
• An indication of whether the activity was successful or failed.
• Identifier(s) that can be used to unambiguously trace the event back to the originating user. This could be a user session ID and the client IP address of the user. If session ID is not available or is sensitive by design of the application, a correlation ID may be used instead.
• If more than one authenticated session is possible at a time for a user, the identifier(s) must be able to trace to the precise session for that user.

7. For authentication events, in addition to the above include:

• user device ID
• HTTP Referer Header
• HTTP User Agent header or comparable identifier
• the method of authentication used if more than one is possible in case of MFA

8. For authorisation events, in addition to the above include:

• what action a user is attempting to perform (eg delete)
• on what resource (eg a report, invoice)
• ID of the resource and other related IDs, eg if the resources are grouped or scoped in some way in your application, the group and scope IDs

9. Clearly distinguish security events from other application or system events if security and non-security events are stored in the same log stream. Optionally, have a separate log stream for security events only.

10. Protect log information against tampering and unauthorised access. Use a dedicated log management service and submit the log events there as soon as they occur. Select a log management service that supports logs immutability and integrity. System administrators must not have a capability to erase or change the log records containing their own activities. Monitor attempts or successful deletion or alteration of security logs.

11. Do not log confidential, personal and other sensitive data. Instead, use identifiers such as user ID or other IDs specific to your application, that are not sensitive but can be used to link the trace of logging events to a particular user or session.

Helping keep the Xero ecosystem secure

Security event logging is one of our security requirements for Xero app partners when they grow past 1000 connections, or when they use our Practice APIs. However, we highly encourage all those building integrations to the Xero API to implement these guidelines into their operations. This helps both you and Xero to respond quickly when security incidents arise, by making it easier to identify what, when, where and who is involved.

How to report an incident

If you think you have spotted any security problem, breach or incident, contact our API Support team at email api@support.xero.com right away.