Configuration Reference: JavaLogFactory - ESAPI/esapi-java-legacy GitHub Wiki

• Configuration of JavaLogFactory pertains to version 2.5.0.0 or later.
• Content in this document pertaining to java.util.LogManager system property configurations apply to versions AFTER 2.5.0.0 (not inclusive).

The ESAPI.properties file must contain the required key ESAPI.Logger, and the value must be configured to the fully-qualified name of the org.owasp.esapi.LogFactory implementation to be used.

In the most recent releases of the ESAPI library the JavaLogFactory is the default logging configuration set by the project: ESAPI.Logger=org.owasp.esapi.logging.java.JavaLogFactory

ESAPI supports two primary methods for configuring the output from the Java Log implementation. The application must supply at least one of these configurations. Upon initialization, the ESAPI JavaLogFactory will make a best-effort attempt to verify that the Java Log behavior has some configuration in place.

WARNING: ESAPI takes no ownership or responsibility for diagnosing application-specific configuration requirements. This means that we may decline from answering questions about it in GitHub issues, our GitHub Discussions board, either of our ESAPI mailing lists, Stack Overflow, etc. and if we do answer questions about it, it likely will not go beyond referring to this wiki page and noting that "you have been warned".

If either of the following system properties are detected at runtime ESAPI will not look for, or load, the esapi-java-logging.properties file. java.util.logging.config.class java.util.logging.config.file

Note these system properties are a part of Java and not owned, controlled, or managed by ESAPI. JDK8 LogMaganger Javadoc

Since ESAPI must be able to detect the configurations, they must be present as runtime configurations.

Startup System Properties Most java application provide a way to extend the startup configurations/options for the application instance. The exact process and configuration location is dependent on what application is being used. Refer to the application administration guide or documentation as to how to configure this correctly for the targeted environment.

-Djava.util.logging.config.class= -Djava.util.logging.config.file=

In-Code Solutions (Not Recommended) Java provides a mechanism to set System properties in code at runtime. By calling the System.setProperty method, the desired configuration can be applied over the course of normal application exection.

System.setProperty('java.util.logging.config.class", ""); System.setProperty('java.util.logging.config.file", "");

NOTE this method has a heavy dependency on application startup order. The calls to set the system properties must be guaranteed to run before the first call to ESAPI's log is made. Due to this unpredicatable state this method is not recommended for complex applications or any system with dynamic startup execution order.

1. Download the esapi-{version}-configuration.jar from the ESAPI Releases page
2. Extract the default esapi-java-logging.properties file from the configuration jar.
3. Place the properties file next to ESAPI.properties on your application's path.
4. Restart the application.

In the case where the JavaLogFactory is unable to verify the java.logging.LogManger system properties and no esapi-java-logging.properties file exists the library will not load.

To verify, the application startup logs should be inspected for the content identified below.

Caused by: org.owasp.esapi.errors.ConfigurationException: Unable to locate resource: esapi-java-logging.properties
        at org.owasp.esapi.logging.java.JavaLogFactory.readLoggerConfiguration(JavaLogFactory.java:126)
        at org.owasp.esapi.logging.java.JavaLogFactory.<clinit>(JavaLogFactory.java:94)
        ... 47 more

This content will only appear the first time the JavaLogFactory is requested.

The JavaLogFactory class will not be loaded to the runtime, and will cause downstream exceptions containing Caused by: java.lang.NoClassDefFoundError: Could not initialize class org.owasp.esapi.logging.java.JavaLogFactory

(Note: This section only applies if you are using a 2.5.x.y release before 2.5.4.0. Otherwise, see the "Configuring the JavaLogFactory" wiki page.)

If there is no detectable LogMaganger configuration, ESAPI reads a supplied esapi-java-logging.properties configuration and applies those configurations to the java LogManager for the runtime. This can lead to race conditions on startup among projects that supply independent logging configurations, each one setting the local configuration as the java LogManager default.

To resolve this for ESAPI: Set the LogMaganger system properties as identified above in Configure the Java Logging Output/Application-Wide LogManger Configuration

First, verify that ESAPI did correctly start by looking for Caused by: java.lang.NoClassDefFoundError: Could not initialize class org.owasp.esapi.logging.java.JavaLogFactory in your application logs. See Debugging Failed Startup above.

If the application is starting up correctly and the logs are not working as desired, the the likely issue is in the configuration files.

• If the application is using the esapi-java-logging.properties file, verify the file has not been modified. Download the esapi-{version}-configuration.jar from the ESAPI Releases page (linked below) and compare for any local modification.
• If the application is using a more custom logging solution with an application-wide logging configuration, then verify that configuration. The Links section below provides a reference to Oracle's Java Logging Overview that can be referenced for assistance.
  • If the In-Code Solution is being used, stop. Logging issues are likely a result of a dyamic application startup order.

• ESAPI Releases
  • this site can be used to download the esapi-{version}-configuration.jar for the targeted release. It will contain a default implementation of ESAPI.properties and esapi-java-logging.properties
• Java Logging Overview
  • Reference for customizing the Java Log setup and verifying required configuration