org.owasp.esapi
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:

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:

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
static class Logger.EventType
          Defines the type of log event that is being generated.
 
Field Summary
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
 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


Copyright © 2011 The Open Web Application Security Project (OWASP). All Rights Reserved.