CSRFGuard 2.0 Installation
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.
- Copy OWASP CSRFGuard files to a directory accessible by your container
- 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.
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.
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:
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.
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:
<filter> <filter-name>CSRFGuard</filter-name> <filter-class>org.owasp.csrf.CSRFGuard</filter-class> <init-param> <param-name>config</param-name> <param-value>WEB-INF/csrfguard.properties</param-value> </init-param> </filter>
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:
<filter-mapping> <filter-name>CSRFGuard</filter-name> <servlet-name>WebGoat</servlet-name> </filter-mapping>
<filter-mapping> <filter-name>CSRFGuard</filter-name> <url-pattern>*.jsp</url-pattern> </filter-mapping>