org.owasp.esapi

Interface Logger

All Known Implementing Classes:

JavaLogger, Slf4JLogger

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 custom 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 date/time stamp.

Custom logger implementations might also:

6. Filter out any sensitive data specific to the current application or organization, such as credit cards, social security numbers, etc.

There are both SLF4J and native Java Logging (i.e., java.util.logging, aka JUL) implementations of the ESAPI logger with JUL being our default logger for our stock ESAPI.properties file that is delivered along with ESAPI releases in a separate esapi-configuration jar available from the releases mentioned on ESAPI's GitHub Releases page.

The org.owasp.esapi.logging.java.JavaLogger class uses the java.util.logging package as the basis for its logging implementation. Both provided implementations implement requirements #1 through #5 above.

Customization: It is expected that most organizations may wish to implement their own custom Logger class in order to integrate ESAPI logging with their specific logging infrastructure. The ESAPI feference implementations can serve as a useful starting point to intended to provide a simple functional example of an implementation, but they are also largely usuable out-of-the-box with some additional minimal log configuration.

Since:

June 1, 2007

Author:

Jeff Williams (jeff.williams .at. aspectsecurity.com) Aspect Security

Nested Class Summary

Nested Classes

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

Field Summary

Fields

Modifier and Type	Field and 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

Modifier and Type	Method and Description
void	always(Logger.EventType type, String message) Log an event regardless of what logging level is enabled.
void	always(Logger.EventType type, String message, 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, String message) Log a debug level security event if 'debug' level logging is enabled.
void	debug(Logger.EventType type, String message, 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, String message) Log an error level security event if 'error' level logging is enabled.
void	error(Logger.EventType type, String message, 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, String message) Log a fatal event if 'fatal' level logging is enabled.
void	fatal(Logger.EventType type, String message, 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, String message) Log an info level security event if 'info' level logging is enabled.
void	info(Logger.EventType type, String message, 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, String message) Log a trace level security event if 'trace' level logging is enabled.
void	trace(Logger.EventType type, String message, 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, String message) Log a warning level security event if 'warning' level logging is enabled.
void	warning(Logger.EventType type, String message, 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.

Returns:

The current logging level.

fatal

void fatal(Logger.EventType type,
           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,
           String message,
           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,
           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,
           String message,
           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,
             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,
             String message,
             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,
          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,
          String message,
          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,
           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,
           String message,
           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,
           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,
           String message,
           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,
            String message)

Log an event regardless of what logging level is enabled.
Note that logging will not occur if the underlying logging implementation has logging disabled.

Parameters:

type - the type of event

message - the message to log

always

void always(Logger.EventType type,
            String message,
            Throwable throwable)

Log an event regardless of what logging level is enabled and also record the stack trace associated with the event.
Note that logging will not occur if the underlying logging implementation has logging disabled.

Parameters:

type - the type of event

message - the message to log

throwable - the exception to be logged