ESAPI Swingset Interactive - Logging
Tutorial
The ESAPI Logger should promote secure logging functionality while allowing organizations to choose their own logging framework. The primary benefit of the ESAPI Logger is the addition of relevant security information to the log message and the use of specific tags that allow log messages to be identified as SECURITY related (as opposed to FUNCTIONAL, PERFORMANCE, etc).
The Logger interface defines a set of methods that can be used to log security events. It supports a hierarchy of logging levels which can be configured at runtime to determine the severity of events that are logged, and those below the current threshold that are discarded. Implementors should use a well established logging library as it is quite difficult to create a high-performance logger.
The logging levels defined by this interface (in descending order) are:
- fatal (highest value)
- error
- warning
- info
- debug
- trace (lowest value)
ESAPI also allows for the definition of the type of log event that is being generated. The Logger interface predefines 4 types of Log events: SECURITY_SUCCESS, SECURITY_FAILURE, EVENT_SUCCESS, EVENT_FAILURE. Your implementation can extend or change this list if desired. This Logger allows callers to determine which logging levels are enabled, and to submit events at different severity levels.
Implementors of this interface should:
- provide a mechanism for setting the logging level threshold that is currently enabled. This usually works by logging all events at and above that severity level, and discarding all events below that level. This is usually done via configuration, but can also be made accessible programmatically.
- ensure that dangerous HTML characters are encoded before they are logged to defend against malicious injection into logs that might be viewed in an HTML based log viewer.
- encode any CRLF characters included in log data in order to prevent log injection attacks.
- avoid logging the user's session ID. Rather, they should log something equivalent like a generated logging session ID, or a hashed value of the session ID so they can track session specific events without risking the exposure of a live session's ID.
- record the following information with each event:
- identity of the user that caused the event,
- a description of the event (supplied by the caller),
- whether the event succeeded or failed (indicated by the caller),
- severity level of the event (indicated by the caller),
- that this is a security relevant event (indicated by the caller),
- hostname or IP where the event occurred (and ideally the user's source IP as well),a time stamp
- Custom logger implementations might also filter out any sensitive data specific to the current application or organization, such as credit cards, social security numbers, etc. There are both Log4j and native Java Logging default implementations. JavaLogger uses the java.util.logging package as the basis for its logging implementation. Both default implementations implements requirements #1 thru #5 above.
Customization
It is expected that most organizations will implement their own custom Logger class in order to integrate ESAPI logging with their logging infrastructure. The ESAPI Reference Implementation is intended to provide a simple functional example of an implementation.
Configuration
There are various steps required to configure ESAPI for logging
- Define the Log factory in the ESAPI.properties file (in your resources directory)
- Define the Logger.* properties in ESAPI.properties
Use
The Log4JLogFactory reference implementation can be used in the following way:
//sample usage of ESAPI's Logger
Logger logger = ESAPI.getLogger("some Class or String");
logger.fatal(Logger.SECURITY_FAILURE, "some log message");
logger.debug(Logger.EVENT_FAILURE, "another log message");