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.
This directive determines the name of the token placed in the HTML response. The default token name is 'OWASP_CSRFTOKEN'.
This directive determines the length of the unique request token. The default length is 32 characters.
This property is used to specify what random number generator should be used to generate the random token. The default PRNG is 'SHA1PRNG'.
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:
- The 'Redirect' action accepts one parameter called 'ErrorPage'.
Click here 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:
<filter> <filter-name>CSRFGuard</filter-name> <filter-class>org.owasp.csrfguard.CSRFGuardFilter</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>