Logging Cheat Sheet

= Introduction =

This article is focused on providing developers with concentrated guidance on building application logging mechanisms, especially related to security logging. Many systems enable network device, operating system, web server, mail server and database server logging, but often custom application event logging is missing, disabled or poorly configured. It provides much greater insight than infrastructure logging alone. Web application (e.g. web site or web service) logging is much more than having web server logs enabled.

Application logging should be consistent within the application, consistent across an organization's application portfolio and use industry standards where relevant, so the logged event data can be consumed, correlated, analyzed and managed by a wide variety of systems.

= Purpose =

Application logging should be always be included for security events. Application logs are invaluable data for identifying security incidents, monitoring policy violations, establishing baselines, providing information about problems and unusual conditions, contributing additional application-specific data for incident investigation which is lacking in other log sources, and helping defend against vulnerability identification and exploitation through attack detection. Application logging might also be used to record other types of events too. Thus application logging could include:


 * Security events
 * Business process monitoring e.g. sales process abandonment
 * Audit trails e.g. data addition, modification and deletion
 * Performance monitoring e.g. data load time, page timeouts
 * Compliance monitoring
 * Data for subsequent requests for information e.g. subject access, freedom of information, litigation, police and other regulatory investigations
 * Other business-specific requirements

= Design, implementation and testing =

Event data sources
The application itself has access to a wide range of information events that should be used to generate log entries. Thus, the primary event data source is the application code itself. Other sources that could also be considered are:


 * Client software e.g. actions on desktop software and mobile devices in local logs or using messaging technologies, web browser such as using Content Security Policy (CSP) reporting mechanism
 * Network firewalls
 * Network and host intrusion detection systems (NIDS and HIDS)
 * Closely-related applications e.g. filters built into web server software, web server URL redirects/rewrites to scripted custom error pages and handlers
 * Application firewalls e.g. filters, guards, XML gateways, database firewalls, web application firewalls (WAFs)
 * Database applications e.g. automatic audit trails, trigger-based actions
 * Reputation monitoring services e.g. uptime or malware monitoring
 * Related applications e.g. fraud monitoring, CRM

The degree of confidence in the event information has to be considered when including event data from systems in a different trust zone. Data may be missing, modified, forged, replayed and could be malicious – it must always be treated as untrusted data. Consider how the source can be verified, and how integrity and non-repudiation can be enforced.

Note that the application itself has the most information about the user (e.g. identity, roles, permissions) and the context of the event (target, action, outcomes), and often this data is not available to infrastructure devices, or even closely-related applications.

Where to record event data
Applications most commonly write event log data to the file system or a database (SQL or NoSQL). Applications installed on desktops and on mobile devices may use local storage and local databases. Your selected framework may limit the available choices. All types of applications may send event data to remote systems (instead of or as well as more local storage). This could be a centralized log collection and management system (e.g. SIEM or SEM) or another application elsewhere.


 * When using the file system, it is preferable to use a separate partition than those used by the operating system, other application files and user generated content
 * For file-based logs, apply strict permissions concerning which users can access the directories, and the permissions of files within the directories
 * In web applications, the logs must never be exposed in web-accessible locations
 * When using a database, it is preferable to utilize a separate database account that is only used for writing log data and which has very restrictive database, table, function and command permissions
 * Use standard formats over secure protocols to send event data, or log files, to other systems

Consider separate files/tables for extended event information such as error stack traces or a record of HTTP request and response headers and bodies.

Which events to log
The level and content of security monitoring, alerting and reporting needs to be set during the requirements and design stage of projects, and should be proportional to the information security risks. This can then be used to define what should be logged. There is no one size fits all solution, and a blind checklist approach can lead to unnecessary "alarm fog" that means real problems go undetected. Always log:


 * Input validation failures e.g. protocol violations, unacceptable encodings, invalid parameter names and values
 * Output validation failures e.g. database record set mismatch, invalid data encoding
 * Authentication successes and failures
 * Authorization failures
 * Session management failures e.g. cookie session identification value modification
 * Application errors and system events e.g. syntax and runtime errors, connectivity problems, performance issues, third party service error messages, file system errors, file upload virus detection
 * Start-ups and shut-downs
 * Use of higher-risk functionality e.g. changes to privileges, submission of user-generated content - especially file uploads, administrative tasks, data import and export, including screen-based reports
 * Legally binding opt-ins (e.g. terms of use, terms & conditions, consent)

Optionally consider if the following events can be logged and whether it is desirable information:


 * Sequencing failure
 * Excessive use
 * Data changes
 * Fraud and other criminal activities
 * Suspicious, unacceptable or unexpected behavior
 * Modifications to configuration
 * Application code file and/or memory changes

Event attributes
Each log entry needs to include sufficient information for the intended subsequent monitoring and analysis. The application logs must record for each event:


 * Log date and time
 * Event date and time - the event time stamp may be different to the time of logging e.g. server logging where the client application is hosted on remote device that is only periodically or intermittently online
 * Interaction identifier [Note A]
 * Application identifier e.g. name and version
 * Application address e.g. host name or server IPv4 or IPv6 address and port number, workstation identity, local device identifier
 * Service e.g. name and protocol
 * Window/form/page e.g. entry point URL and HTTP method for a web application, dialogue box name
 * Code location e.g. script name, module name
 * Source address e.g. user's device/machine identifier, user's IP address
 * User identity (if authenticated or otherwise known) e.g. user database table primary key value, user name, license number
 * Type of event [Note B]
 * Severity of event [Note B] e.g. {0=emergency, 1=alert, ..., 7=debug}, {fatal, error, warning, info, debug, trace}
 * Security relevant event flag (if the logs contain non-security event data too)
 * Description

Additionally consider recording:


 * Action - original intended purpose of the request e.g. Log in, Refresh session ID, Log out, Update profile
 * Object e.g. the affected component or other object (user account, data resource, file) e.g. URL, Session ID, User account, File
 * Result status - whether the ACTION aimed at the OBJECT was successful e.g. Success, Fail, Defer
 * Reason - why the status above occurred e.g. User not authenticated in database check ..., Incorrect credentials
 * HTTP Status Code (web applications only) - the status code returned to the user (often 200 or 301)
 * Request HTTP headers or HTTP User Agent (web applications only)
 * User type classification e.g. public, authenticated user, CMS user, search engine, authorized penetration tester, uptime monitor (see "Data to exclude" below)
 * Analytical confidence in the event detection [Note B] e.g. low, medium, high or a numeric value
 * Responses seen by the user and/or taken by the application e.g. status code, custom text messages, session termination, administrator alerts
 * Extended details e.g. stack trace, system error messages, debug information, HTTP request body, HTTP response headers and body
 * Internal classifications e.g. responsibility, compliance references
 * External classifications e.g. NIST Security Content Automation Protocol (SCAP), Mitre Common Attack Pattern Enumeration and Classification (CAPEC), OWASP AppSensor

For more information on these, see the "other" related articles listed at the end, especially the comprehensive article by Anton Chuvakin and Gunnar Peterson.

Note A: The "Interaction identifier" is a method of linking all (relevant) events for a single user interaction (e.g. desktop application form submission, web page request, mobile app button click, web service call). The application knows all these events relate to the same interaction, and this should be recorded instead of losing the information and forcing subsequent correlation techniques to re-construct the separate events. For example a single SOAP request may have multiple input validation failures and they may span a small range of times. As another example, an output validation failure may occur much later than the input submission for a long-running "saga request" submitted by the application to a database server.

Note B: Each organisation should ensure it has a consistent, and documented, approach to classification of events (type, confidence, severity), the syntax of descriptions, and field lengths & data types including the format used for dates/times.

Data to exclude
Never exclude any events from "known" users such as other internal systems, "trusted" third parties, search engine robots, uptime/process and other remote monitoring systems, pen testers, auditors. However, you may want to include a classification flag for each of these in the recorded data.

The following should not usually be recorded directly in the logs, but instead should be removed, masked, sanitized, hashed or encrypted:


 * Session identification values (consider replacing with a hashed value if needed to track session specific events)
 * Sensitive personal data and some forms of personally identifiable information (PII)
 * Authentication passwords
 * Database connection strings
 * Bank account or payment card holder data
 * Data of a higher security classification than the logging system is allowed to store
 * Commercially-sensitive information
 * Information it is illegal to collect in the relevant jurisdiction
 * Information a user has opted out of collection or not consented to e.g. use of do not track

Sometimes the following data can also exist, and whilst useful for subsequent investigation, it may also need to be treated in some special manner before the event is recorded:


 * File paths
 * Database connection strings
 * Internal network names and addresses
 * Non sensitive personal data (e.g. personal names, telephone numbers, email addresses)

In some systems, sanitization can be undertaken post log collection, and prior to log display.

Customizable logging
It may be desirable to be able to alter the level of logging (type of events based on severity or threat level, amount of detail recorded). If this is implemented, ensure that:


 * The default level must provide sufficient detail for business needs
 * It should not be possible to completely inactivate application logging or logging of events that are necessary for compliance requirements
 * Alterations to the level/extent of logging must be intrinsic to the application (e.g. undertaken automatically by the application based on an approved algorithm) or follow change management processes (e.g. changes to configuration data, modification of source code)
 * The logging level must be verified periodically

Event collection
If your development framework supports suitable logging mechanisms use, or build upon that. Otherwise, implement an application-wide log handler which can be called from other modules/components. Document the interface referencing the organisation-specific event classification and description syntax requirements. If possible create this log handler as a standard module that can is thoroughly tested, deployed in multiple application, and added to a list of approved & recommended  modules.


 * Perform input validation on event data from other trust zones to ensure it is in the correct format (and consider alerting and not logging if there is an input validation failure)
 * Perform sanitization on all event data to prevent log injection attacks e.g. carriage return, line feed and delimiter characters (and optionally to remove sensitive data)
 * Encode data correctly for the output (logged) format
 * If writing to databases read, understand and apply the SQL injection cheat sheet
 * Ensure failures in the logging processes/systems do not prevent the application from otherwise running or allow information leakage
 * Synchronize time across all servers and devices [Note C]

Note C: This is not always possible where the application is running on a device under some other party's control (e.g. on an individual's mobile phone, on a remote customer's workstation which is on another corporate network). In these cases attempt to measure the time offset, or record a confidence level in the event time stamp.

Where possible record data in a standard format, or at least ensure it can be exported/broadcast using an industry-standard format.

Testing
Logging functionality and systems must be including in application testing:


 * Ensure the logging is working correctly and as specified
 * Check events are being classified consistently and the field names, types and lengths are correctly defined to an agreed standard
 * Ensure logging is implemented and enabled during application security, fuzz, penetration and performance testing
 * Check the effect on the logging mechanisms when external network connectivity is lost (if this is usually required)
 * Ensure logging cannot be used to deplete system resources, for example by filling up disk space or exceeding database transaction log space, leading to denial of service
 * Test the effect on the application of logging failures such as simulated database connectivity loss, lack of file system space, missing write permissions to the file system, and runtime errors in the logging module itself

= Deployment and operation =

Release
Provide security configuration information by adding details about the logging mechanisms to release documentation.

Operation
Enable processes to detect whether logging has stopped, and to identify tampering or unauthorized access and deletion (see protection below).

Protection
The logging mechanisms and collected event data must be protected from mis-use such as tampering in transit, and unauthorized access, modification and deletion once stored. Logs may contain personal and other sensitive information, or the data may contain information regarding the application's code and logic. In addition, the aggregated information in the logs may itself have business value (to competitors, gossip-mongers, journalists and activists) such as allowing the estimate of revenues, or providing performance information about employees. Consider whether parts of the data may need to be excluded, masked, sanitized, hashed or encrypted during examination or extraction.

At rest:


 * Build in tamper detection so you know if a record has been modified or deleted
 * Store or copy log data to read-only media as soon as possible
 * All access to the logs must be recorded and monitored (and may need prior approval)
 * The privileges to read log data should be restricted and reviewed periodically

In transit:


 * If log data is sent over untrusted networks (e.g. for collection, for dispatch elsewhere, for analysis, for reporting), use a secure transmission protocol
 * Consider whether the origin of the event data needs to be verified
 * Perform due diligence checks (regulatory and security) before sending event data to third parties

Monitoring of events
The logged event data needs to have appropriate monitoring, alerting and reporting:


 * Ensure the application/process owner and incident response team is aware of the application logging mechanisms
 * Incorporate the application logging into any existing log management systems/infrastructure e.g. centralized logging and analysis systems
 * Ensure event information is available to appropriate teams
 * Alert the responsible teams about more serious events immediately

Disposal of logs
Log data, and backups/copies/extractions, must not be destroyed before the duration of the required data retention period, and must not be kept beyond this time. Legal, regulatory and contractual obligations may impact on these periods.

= Related articles =

OWASP ESAPI Documentation

OWASP Logging Project

IETF syslog protocol

Mitre Common Event Expression (CEE)

NIST SP 800-92 Guide to Computer Security Log Management

W3C Extended Log File Format

Other How to Do Application Logging Right, Anton Chuvakin & Gunnar Peterson, IEEE Security & Privacy Journal

Other Build Visibility In, Richard Bejtlich, TaoSecurity blog

Other Common Event Format (CEF), Arcsight

Other Application Security Logging, Colin Watson, Web Security Usability and Design Blog

Other Building Secure Applications: Consistent Logging, Rohit Sethi & Nish Bhalla, Symantec Connect

= Authors and primary contributors =

Colin Watson - colin.watson[at]owasp.org