Interface Logger

  • All Known Implementing Classes:
    Log4JLogger

    public interface Logger
    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)
    There are also several variations of always() methods that will always log a message regardless of the log level.

    ESAPI also allows for the definition of the type of log event that is being generated. The Logger interface predefines 6 types of Log events:

    • SECURITY_SUCCESS
    • SECURITY_FAILURE
    • SECURITY_AUDIT
    • EVENT_SUCCESS
    • EVENT_FAILURE
    • EVENT_UNSPECIFIED

    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:

    1. 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.
    2. 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.
    3. encode any CRLF characters included in log data in order to prevent log injection attacks.
    4. 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.
    5. record the following information with each event:
      1. identity of the user that caused the event,
      2. a description of the event (supplied by the caller),
      3. whether the event succeeded or failed (indicated by the caller),
      4. severity level of the event (indicated by the caller),
      5. that this is a security relevant event (indicated by the caller),
      6. hostname or IP where the event occurred (and ideally the user's source IP as well),
      7. a time stamp
    Custom logger implementations might also:
    1. 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.
    Since:
    June 1, 2007
    Author:
    Jeff Williams (jeff.williams .at. aspectsecurity.com) Aspect Security
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Interface Description
      static class  Logger.EventType
      Defines the type of log event that is being generated.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int ALL
      ALL indicates that all messages should be logged.
      static int DEBUG
      DEBUG indicates that DEBUG messages and above should be logged.
      static int ERROR
      ERROR indicates that ERROR messages and above should be logged.
      static Logger.EventType EVENT_FAILURE
      A non-security type of log event that has failed.
      static Logger.EventType EVENT_SUCCESS
      A non-security type of log event that has succeeded.
      static Logger.EventType EVENT_UNSPECIFIED
      A non-security type of log event that is unspecified.
      static int FATAL
      FATAL indicates that only FATAL messages should be logged.
      static int INFO
      INFO indicates that INFO messages and above should be logged.
      static int OFF
      OFF indicates that no messages should be logged.
      static Logger.EventType SECURITY_AUDIT
      A security type of log event that is associated with an audit trail of some type, but the log event is not specifically something that has either succeeded or failed or that is irrelevant in the case of this logged message.
      static Logger.EventType SECURITY_FAILURE
      A security type of log event that has failed.
      static Logger.EventType SECURITY_SUCCESS
      A security type of log event that has succeeded.
      static int TRACE
      TRACE indicates that TRACE messages and above should be logged.
      static int WARNING
      WARNING indicates that WARNING messages and above should be logged.
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void always​(Logger.EventType type, java.lang.String message)
      Log an event regardless of what logging level is enabled.
      void always​(Logger.EventType type, java.lang.String message, java.lang.Throwable throwable)
      Log an event regardless of what logging level is enabled and also record the stack trace associated with the event.
      void debug​(Logger.EventType type, java.lang.String message)
      Log a debug level security event if 'debug' level logging is enabled.
      void debug​(Logger.EventType type, java.lang.String message, java.lang.Throwable throwable)
      Log a debug level security event if 'debug' level logging is enabled and also record the stack trace associated with the event.
      void error​(Logger.EventType type, java.lang.String message)
      Log an error level security event if 'error' level logging is enabled.
      void error​(Logger.EventType type, java.lang.String message, java.lang.Throwable throwable)
      Log an error level security event if 'error' level logging is enabled and also record the stack trace associated with the event.
      void fatal​(Logger.EventType type, java.lang.String message)
      Log a fatal event if 'fatal' level logging is enabled.
      void fatal​(Logger.EventType type, java.lang.String message, java.lang.Throwable throwable)
      Log a fatal level security event if 'fatal' level logging is enabled and also record the stack trace associated with the event.
      int getESAPILevel()
      Retrieve the current ESAPI logging level for this logger.
      void info​(Logger.EventType type, java.lang.String message)
      Log an info level security event if 'info' level logging is enabled.
      void info​(Logger.EventType type, java.lang.String message, java.lang.Throwable throwable)
      Log an info level security event if 'info' level logging is enabled and also record the stack trace associated with the event.
      boolean isDebugEnabled()
      Allows the caller to determine if messages logged at this level will be discarded, to avoid performing expensive processing.
      boolean isErrorEnabled()
      Allows the caller to determine if messages logged at this level will be discarded, to avoid performing expensive processing.
      boolean isFatalEnabled()
      Allows the caller to determine if messages logged at this level will be discarded, to avoid performing expensive processing.
      boolean isInfoEnabled()
      Allows the caller to determine if messages logged at this level will be discarded, to avoid performing expensive processing.
      boolean isTraceEnabled()
      Allows the caller to determine if messages logged at this level will be discarded, to avoid performing expensive processing.
      boolean isWarningEnabled()
      Allows the caller to determine if messages logged at this level will be discarded, to avoid performing expensive processing.
      void setLevel​(int level)
      Dynamically set the ESAPI logging severity level.
      void trace​(Logger.EventType type, java.lang.String message)
      Log a trace level security event if 'trace' level logging is enabled.
      void trace​(Logger.EventType type, java.lang.String message, java.lang.Throwable throwable)
      Log a trace level security event if 'trace' level logging is enabled and also record the stack trace associated with the event.
      void warning​(Logger.EventType type, java.lang.String message)
      Log a warning level security event if 'warning' level logging is enabled.
      void warning​(Logger.EventType type, java.lang.String message, java.lang.Throwable throwable)
      Log a warning level security event if 'warning' level logging is enabled and also record the stack trace associated with the event.
    • Field Detail

      • SECURITY_SUCCESS

        static final Logger.EventType SECURITY_SUCCESS
        A security type of log event that has succeeded. This is one of 6 predefined ESAPI logging events. New events can be added.
      • SECURITY_FAILURE

        static final Logger.EventType SECURITY_FAILURE
        A security type of log event that has failed. This is one of 6 predefined ESAPI logging events. New events can be added.
      • SECURITY_AUDIT

        static final Logger.EventType SECURITY_AUDIT
        A security type of log event that is associated with an audit trail of some type, but the log event is not specifically something that has either succeeded or failed or that is irrelevant in the case of this logged message.
      • EVENT_SUCCESS

        static final Logger.EventType EVENT_SUCCESS
        A non-security type of log event that has succeeded. This is one of 6 predefined ESAPI logging events. New events can be added.
      • EVENT_FAILURE

        static final Logger.EventType EVENT_FAILURE
        A non-security type of log event that has failed. This is one of 6 predefined ESAPI logging events. New events can be added.
      • EVENT_UNSPECIFIED

        static final Logger.EventType EVENT_UNSPECIFIED
        A non-security type of log event that is unspecified. This is one of 6 predefined ESAPI logging events. New events can be added.
      • OFF

        static final int OFF
        OFF indicates that no messages should be logged. This level is initialized to Integer.MAX_VALUE.
        See Also:
        Constant Field Values
      • FATAL

        static final int FATAL
        FATAL indicates that only FATAL messages should be logged. This level is initialized to 1000.
        See Also:
        Constant Field Values
      • ERROR

        static final int ERROR
        ERROR indicates that ERROR messages and above should be logged. This level is initialized to 800.
        See Also:
        Constant Field Values
      • WARNING

        static final int WARNING
        WARNING indicates that WARNING messages and above should be logged. This level is initialized to 600.
        See Also:
        Constant Field Values
      • INFO

        static final int INFO
        INFO indicates that INFO messages and above should be logged. This level is initialized to 400.
        See Also:
        Constant Field Values
      • DEBUG

        static final int DEBUG
        DEBUG indicates that DEBUG messages and above should be logged. This level is initialized to 200.
        See Also:
        Constant Field Values
      • TRACE

        static final int TRACE
        TRACE indicates that TRACE messages and above should be logged. This level is initialized to 100.
        See Also:
        Constant Field Values
      • ALL

        static final int ALL
        ALL indicates that all messages should be logged. This level is initialized to Integer.MIN_VALUE.
        See Also:
        Constant Field Values
    • Method Detail

      • setLevel

        void setLevel​(int level)
        Dynamically set the ESAPI logging severity level. All events of this level and higher will be logged from this point forward for all logs. All events below this level will be discarded.
        Parameters:
        level - The level to set the logging level to.
      • getESAPILevel

        int getESAPILevel()
        Retrieve the current ESAPI logging level for this logger. See Log4JLogger for an explanation of why this method is not simply called getLevel().
        Returns:
        The current logging level.
      • fatal

        void fatal​(Logger.EventType type,
                   java.lang.String message)
        Log a fatal event if 'fatal' level logging is enabled.
        Parameters:
        type - the type of event
        message - the message to log
      • fatal

        void fatal​(Logger.EventType type,
                   java.lang.String message,
                   java.lang.Throwable throwable)
        Log a fatal level security event if 'fatal' level logging is enabled and also record the stack trace associated with the event.
        Parameters:
        type - the type of event
        message - the message to log
        throwable - the exception to be logged
      • isFatalEnabled

        boolean isFatalEnabled()
        Allows the caller to determine if messages logged at this level will be discarded, to avoid performing expensive processing.
        Returns:
        true if fatal level messages will be output to the log
      • error

        void error​(Logger.EventType type,
                   java.lang.String message)
        Log an error level security event if 'error' level logging is enabled.
        Parameters:
        type - the type of event
        message - the message to log
      • error

        void error​(Logger.EventType type,
                   java.lang.String message,
                   java.lang.Throwable throwable)
        Log an error level security event if 'error' level logging is enabled and also record the stack trace associated with the event.
        Parameters:
        type - the type of event
        message - the message to log
        throwable - the exception to be logged
      • isErrorEnabled

        boolean isErrorEnabled()
        Allows the caller to determine if messages logged at this level will be discarded, to avoid performing expensive processing.
        Returns:
        true if error level messages will be output to the log
      • warning

        void warning​(Logger.EventType type,
                     java.lang.String message)
        Log a warning level security event if 'warning' level logging is enabled.
        Parameters:
        type - the type of event
        message - the message to log
      • warning

        void warning​(Logger.EventType type,
                     java.lang.String message,
                     java.lang.Throwable throwable)
        Log a warning level security event if 'warning' level logging is enabled and also record the stack trace associated with the event.
        Parameters:
        type - the type of event
        message - the message to log
        throwable - the exception to be logged
      • isWarningEnabled

        boolean isWarningEnabled()
        Allows the caller to determine if messages logged at this level will be discarded, to avoid performing expensive processing.
        Returns:
        true if warning level messages will be output to the log
      • info

        void info​(Logger.EventType type,
                  java.lang.String message)
        Log an info level security event if 'info' level logging is enabled.
        Parameters:
        type - the type of event
        message - the message to log
      • info

        void info​(Logger.EventType type,
                  java.lang.String message,
                  java.lang.Throwable throwable)
        Log an info level security event if 'info' level logging is enabled and also record the stack trace associated with the event.
        Parameters:
        type - the type of event
        message - the message to log
        throwable - the exception to be logged
      • isInfoEnabled

        boolean isInfoEnabled()
        Allows the caller to determine if messages logged at this level will be discarded, to avoid performing expensive processing.
        Returns:
        true if info level messages will be output to the log
      • debug

        void debug​(Logger.EventType type,
                   java.lang.String message)
        Log a debug level security event if 'debug' level logging is enabled.
        Parameters:
        type - the type of event
        message - the message to log
      • debug

        void debug​(Logger.EventType type,
                   java.lang.String message,
                   java.lang.Throwable throwable)
        Log a debug level security event if 'debug' level logging is enabled and also record the stack trace associated with the event.
        Parameters:
        type - the type of event
        message - the message to log
        throwable - the exception to be logged
      • isDebugEnabled

        boolean isDebugEnabled()
        Allows the caller to determine if messages logged at this level will be discarded, to avoid performing expensive processing.
        Returns:
        true if debug level messages will be output to the log
      • trace

        void trace​(Logger.EventType type,
                   java.lang.String message)
        Log a trace level security event if 'trace' level logging is enabled.
        Parameters:
        type - the type of event
        message - the message to log
      • trace

        void trace​(Logger.EventType type,
                   java.lang.String message,
                   java.lang.Throwable throwable)
        Log a trace level security event if 'trace' level logging is enabled and also record the stack trace associated with the event.
        Parameters:
        type - the type of event
        message - the message to log
        throwable - the exception to be logged
      • isTraceEnabled

        boolean isTraceEnabled()
        Allows the caller to determine if messages logged at this level will be discarded, to avoid performing expensive processing.
        Returns:
        true if trace level messages will be output to the log
      • always

        void always​(Logger.EventType type,
                    java.lang.String message)
        Log an event regardless of what logging level is enabled.
        Parameters:
        type - the type of event
        message - the message to log
      • always

        void always​(Logger.EventType type,
                    java.lang.String message,
                    java.lang.Throwable throwable)
        Log an event regardless of what logging level is enabled and also record the stack trace associated with the event.
        Parameters:
        type - the type of event
        message - the message to log
        throwable - the exception to be logged