Code Excursion

Setting up ESAPI with Apache Tomcat

As a developer I have been tasked with making sure our application is compliant with Defense Information Systems Agency’s (DISA) Security Technical Implementation Guide (STIG). DISA publishes a list of STIGs periodically which the development team needs to implement. One of the tools we use to accomplish this is the Open Web Application Security Project’s (OWASP) Enterprise Security API (ESAPI). Many of the STIGs published by DISA can be implemented using the ESAPI. Both the current version, ESAPI 2.0, and the upcoming ESAPI 3.0 are hosted on Github. Do not be thrown off by ESAPI 2.0 being labeled “legacy”. It is the current version. While we will be using it with Java other languages/frameworks sunch as PHP, .Net and Javascript.

ESAPI helps you by providing industry accepted solutions to security vulnerabilities in your application. Log forging, cross site scripting and LDAP injection are a few examples. In addition it also provides data validation and encryption support. This article is written in the context of using ESAPI to secure Liferay on a Tomcat application server. I am using Maven 3 as my build environment.

I found few helpful resources concerning setting up ESAPI. Documentation and configuration files seem to be scattered between Google code and the OWASP site. As I have mentioned it is now also on Github. Thus the reason for this article. The following is what I found to be the most helpful in fully installing and configuring ESAPI. The first step is to checkout the source code from Github. I recommend this because this gives you access to all the necessary configuration files and to some documentation.

checkout ESAPI 2.0 from Github

bash$ git clone https://github.com/ESAPI/esapi-java-legacy.git
Cloning into 'esapi-java-legacy'...
remote: Counting objects: 24393, done.
remote: Compressing objects: 100% (95/95), done.
remote: Total 24393 (delta 40), reused 0 (delta 0), pack-reused 24277
Receiving objects: 100% (24393/24393), 36.03 MiB | 1.67 MiB/s, done.
Resolving deltas: 100% (15356/15356), done.
Checking connectivity... done.

The configuration files will be located in the “configuration” subdirectory. Copy the “esapi” and “properties” directories to the location where you will be storing your configuration. In my case I placed them in the “<tomcat directory>/lib/ext” folder. ESAPI scans your classpath looking for an “esapi” directory to load the configuration. Unfortunately the “ant-sammy” part of it does not work unless you add a JVM startup parameter. You will want to add “-D-Dorg.owasp.esapi.resources” to your Tomcat setenv.sh script.

bin/setenv.sh

CATALINA_OPTS=" -Dorg.owasp.esapi.resources=../lib/ext/esapi"

Next you will want to add the esapi-2.1.0.jar and antisamy-1.5.3.jar to your class path. The easiest way, as shown below, to accomplish this with a maven project is to add ESAPI as a dependency to your project pom.xml. This has the advantage of Maven downloading all the necessary dependencies. I placed the jar files in the Tomcat “lib/ext” directory and modified the scope of the dependency to be “provided”. The second way gives access to all applications running on the server without having to include the jar file in each seperate war file. The most reliable and easiest place to download the jar files is the Maven Central Repository.

pom.xml

<dependencies>
    ...
   <dependency>
      <groupId>org.owasp.antisamy</groupId>
      <artifactId>antisamy</artifactId>
      <version>1.5.3</version>
    </dependency>
    <dependency>
      <groupId>org.owasp.esapi</groupId>
      <artifactId>esapi</artifactId>
      <version>2.1.0</version>
    </dependency>

    ...
</dependencies>

The dependencies require by ESAPI are automatically downloaded by Maven. If however you decide to do it manually here are a list of dependencies.

• antisamy-1.4.3.jar
• xercesImple-2.8.0.jar
• batik-ext-1.7.jar
• batik-css-1.7.jar
• nekohtml-1.9.12.jar

These steps provide you with default ESAPI functionality. You will want to customize the properties and configuration files to suit your needs and security considerations. Options which I will discuss in further articles.