CSRFGuard 2.0 Installation

Overview
The second installment of the OWASP CSRFGuard has been re-written from scratch to increase accuracy, efficiency, and overall usability. This page details all of the steps necessary to deploy CSRFGuard 2.x in your web application.

Quick Steps:


 * Copy OWASP CSRFGuard files to a directory accessible by your container
 * ${PROJECT}/dist/OWASP-CSRFGuard-2.0.jar
 * ${PROJECT}/lib/htmlparser.jar
 * ${PROJECT}/conf/csrfguard.properties
 * Add a 'filter' entry to your web deployment descriptor.
 * Add a mapping for the newly created filter entry.

Add OWASP CSRFGuard To ClassPath
In order for your web application container to invoke the OWASP CSRFGuard filter, it will need to be accessible in the classpath. If you are working with a single application, we recommend placing OWASP CSRFGuard and the htmlparser.jar dependency within the WEB-INF/lib folder of your web application project. If you have multiple projects (ex. an EAR) that make use of the filter, we recommend placing OWASP CSRFGuard and the htmlparser.jar dependency in a single library folder that is accessible by all the applications served by your container. For example, if our application container were Tomcat and we had multiple applications making use of OWASP CSRFGuard, we would place the Jar file in the tomcat/common/lib directory. OWASP CSRFGuard can now be utilized by every application deployed by the container.

Update CSRFGuard Properties File
The properties file controls how CSRFGuard processes malicious HTTP requests and HTML responses. The latest version of CSRFGuard was designed to be flexible to work within diverse environments and organizations. This section provides a brief overview of all of the options available in the properties file.

org.owasp.csrfguard.Debug
The 'org.owasp.csrfguard.Debug' property determines whether or not CSRFGuard should run in 'debug' mode. Currently, there is no difference in behavior between a 'Debug=false' and a 'Debug=true' deployment. The property was included to give developers the ability to add debug code to their custom actions and response handlers.

org.owasp.csrfguard.ResponseHandler
The 'org.owasp.csrfguard.ResponseHandler' property determines what 'ResponseHandler' should be invoked to insert the unique request token in the HTML response. Each of these response handlers implements the org.owasp.csrfguard.ResponseHandler interface and attempts to insert the unique request token in all links, iframes, and forms. CSRFGuard 2.x ships with three possible response handlers:

org.owasp.csrfguard.handlers.HTMLParserHandler

This ResponseHandler utilizes the open-source htmlparser (http://htmlparser.sourceforge.net) to manipulate the HTML response. The HTMLParserHandler is very accurate, relatively fast, easy to use/develop with, and offers a solid foundation for future enhancements. For example, future versions of CSRFGuard may parse custom JavaScript and insert the token in various (ex. window.location) locations. Such robust enhancements to CSRFGuard cannot be achieved in a clean and easy-to-maintain manner in the other response handlers. However, the htmlparser has interesting side effects with HTML that is not well formed. The htmlparser will sometimes modify HTML that is not well-formed in an attempt to make it well-formed. As such, some of the HTML resulting from the handler may break functionality. One such example is the 'HttpOnly' lesson in WebGoat (written by some guy name Eric Sheridan). The HTML generated by this lesson is not well-formed (nested HTML forms) and the modifications made by the HTMLParserHandler actually break the functionality of the lesson. Specifically, the 'Yes No' radio buttons to not transmit all of the appropriate parameters.

org.owasp.csrfguard.handlers.RegExHandler

This ResponseHandler attempts to parse the HTML response using regular expressions. Any text matching the regular expression will be replaced with text containing the unique request token. The RegExHandler is the exact same implementation used in OWASP CSRFGuard 1.0. While this implementation is faster than the HTMLParserHandler, it is much less accurate. The code is overly complex and not as thoroughly tested as the other response handlers. This handler should be considered experimental.

org.owasp.csrfguard.handlers.JavaScriptHandler

This ResponseHandler searches the HTML response for the tag and prepends custom JavaScript that will insert the unique request token when processed by the clients browser. The JavaScriptHandler is extremely accurate and very fast as it off-loads the work to the client. The JavaScriptHandler does not suffer from the problems the HTMLParserHandler suffers in terms of broken HTML. The custom JavaScript will be executed after the HTML is successfully parsed, decreasing the likelihood of conflicting with broken HTML. Furthermore, all of the work that was previously performed on the server by the two other handlers is now performed on the client. For most environments and applications, the JavaScriptHandler is the preferred response handler.

Note: It is vitally important to thoroughly test the ResponseHandler in your environment before deploying it to production. There is risk that the modification of your HTML might break existing functionality.

org.owasp.csrfguard.TokenName
This directive determines the name of the token placed in the HTML response. The default token name is 'OWASP_CSRFTOKEN'.

org.owasp.csrfguard.TokenLength
This directive determines the length of the unique request token. The default length is 32 characters.

org.owasp.csrfguard.PRNG
This property is used to specify what random number generator should be used to generate the random token. The default PRNG is 'SHA1PRNG'.

org.owasp.csrfguard.action.class.[name]
This directive gives the user the ability to specify actions that should be invoked when a CSRF attack is detected. Every action extends the org.owasp.csrfguard.actions.CSRFAction abstract class. You can specify as many or as little actions as you wish. The default action is org.owasp.csrfguard.actions.DefaultAction. For each action, you can also specify one or more parameters to be passed to the action before it is executed.

The syntax for adding an action to the properties file is a little confusing at first glance. To understand how to add an action, let us consider the 'Redirect' action. Assume that we extends the CSRFAction base class and implemented our own action that redirects the user to an error page that we specify in a parameter. First, we add the following line to csrfguard.properties:

syntax: org.owasp.csrfguard.action.class.[className]=[class] example: org.owasp.csrfguard.action.class.Redirect=org.owasp.csrfguard.actions.Redirect

This directive says 'we have an action called 'Redirect' and its class file is at org.owasp.csrfguard.actions.Redirect'. Next, we want to pass a parameter that tells the action where to redirect the user

syntax: org.owasp.csrfguard.action.class[className].param.[parameterName]=[parameterValue] example: org.owasp.csrfguard.action.class.Redirect.param.ErrorPage=attack

This directive says that 'for the action 'Redirect', we have a parameter called 'ErrorPage' with the value 'attack''.

There are currently three actions included with CSRFGuard:


 * org.owasp.csrfguard.actions.Log
 * org.owasp.csrfguard.actions.Invalidate
 * org.owasp.csrfguard.actions.Redirect
 * The 'Redirect' action accepts one parameter called 'ErrorPage'.

for the sample properties file included with the OWASP CSRFGuard 2.x release.

Update Deployment Descriptor
Java EE filters provide the ability to intercept, view, and modify both the request and associated response for the requesting client. In order for our application to make use of the OWASP CSRFGuard filter, we must modify the application's web.xml file. First we must declare the filter and the 'config' initialization parameter.

The following is a sample entry used to test CSRFGuard in WebGoat:

CSRFGuard org.owasp.csrfguard.CSRFGuardFilter  config WEB-INF/csrfguard.properties 

After declaring the filter in the descriptor, we must specify what resources this filter should handle. We can instruct the filter to handle requests for entire servlets or specific URL patterns. The following example instructs the OWASP CSRFGuard to handle all requests to the 'WebGoat' servlet as well as any requests ending in a .jsp:

 CSRFGuard WebGoat 

 CSRFGuard</filter-name> <url-pattern>*.jsp</url-pattern> </filter-mapping>

Note: If you map OWASP CSRFGuard to a resource that does not contain nor generate HTML (ex. images, Javascript source, etc.), you will may get runtime exceptions depending on the selected ResponseHandler!