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.

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.csrf.CSRFGuard  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!