Package 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:
- fatal (highest value)
- error
- warning
- info
- debug
- trace (lowest value)
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:- 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
- filter out any sensitive data specific to the current application or organization, such as credit cards, social security numbers, etc.
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. SeeLog4JLogger
for an explanation of why this method is not simply calledgetLevel()
.- 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 eventmessage
- 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 eventmessage
- the message to logthrowable
- 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 eventmessage
- 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 eventmessage
- the message to logthrowable
- 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 eventmessage
- 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 eventmessage
- the message to logthrowable
- 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 eventmessage
- 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 eventmessage
- the message to logthrowable
- 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 eventmessage
- 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 eventmessage
- the message to logthrowable
- 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 eventmessage
- 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 eventmessage
- the message to logthrowable
- 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 eventmessage
- 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 eventmessage
- the message to logthrowable
- the exception to be logged
-
-