OWASP CSRFGuard 4.x

Overview

Welcome to the home of the OWASP CSRFGuard Project! OWASP CSRFGuard is a library that implements a variant of the synchronizer token pattern to mitigate the risk of Cross-Site Request Forgery (CSRF) attacks. The OWASP CSRFGuard library is integrated through the use of a JavaEE Filter and exposes various automated and manual ways to integrate per-session or pseudo-per-request tokens into HTML. When a user interacts with this HTML, CSRF prevention tokens (i.e. cryptographically random synchronizer tokens) are submitted with the corresponding HTTP request. It is the responsibility of OWASP CSRFGuard to ensure the token is present and is valid for the current HTTP request. Any attempt to submit a request to a protected resource without the correct corresponding token is viewed as a CSRF attack in progress and is discarded. Prior to discarding the request, CSRFGuard can be configured to take one or more actions such as logging aspects of the request and redirecting the user to a landing page. The latest release enhances this strategy to support the optional verification of HTTP requests submitted using Ajax as well as the optional verification of referrer headers.

Project Leads

The CSRFGuard project is run by Azzeddine RAMRAMI and Istvan ALBERT-TOTH.

Using with Maven

Add the following dependencies to your Maven POM file to use the library:
Note: for the Jakarta releases use the -jakarta suffix in the version.

<dependency>
    <groupId>org.owasp</groupId>
    <artifactId>csrfguard</artifactId>
    <version>4.4.0</version>
</dependency>

<!-- Stateful web application support -->
<dependency>
    <groupId>org.owasp</groupId>
    <artifactId>csrfguard-extension-session</artifactId>
    <version>4.4.0</version>
</dependency>

<!-- JSP TAG support -->
<dependency>
    <groupId>org.owasp</groupId>
    <artifactId>csrfguard-jsp-tags</artifactId>
    <version>4.4.0</version>
</dependency>

---

JavaScript Configuration Parameters

CSRFGuard exposes several JavaScript-related configuration parameters that control how the JavaScript servlet behaves. These parameters can be configured in the CSRFGuard properties file and may also be overridden using web.xml context parameters.

The following table lists the available configuration options, their purpose, and default values.

String-based parameters

Property Name	Description	Default Value
cache-control	Cache-Control header value for the generated JavaScript response.	private, max-age=28800
cache-control-tagged	Cache-Control header value when tagged JavaScript responses are used.	private, max-age=600
referer-pattern	Regular expression used to validate HTTP referer headers.	.*
unprotected-extensions	File extensions that should not be protected by CSRFGuard.	empty
source-file	Custom JavaScript source file location for CSRFGuard.	null
x-requested-with	Value used for the X-Requested-With HTTP header.	OWASP CSRFGuard Project
dynamic-node-creation-event	Event name used to detect dynamically created DOM nodes.	null

Boolean-based parameters

Property Name	Description	Default Value
domain-strict	Enforces strict domain matching during referer validation.	true
inject-into-attributes	Enables injection of CSRF tokens into HTML attributes.	true
inject-get-forms	Enables token injection for HTTP GET forms.	true
inject-form-attributes	Enables token injection into form attributes.	true
inject-into-forms	Enables injection of CSRF tokens into HTML forms.	true
inject-into-dynamic	Enables injection into dynamically created DOM nodes.	false
referer-match-protocol	Requires protocol matching during referer validation.	true
referer-match-domain	Requires domain matching during referer validation.	true

Overriding values using web.xml

These configuration options can be overridden using web.xml by defining corresponding context parameters.

Example:

<context-param>
    <param-name>org.owasp.csrfguard.JavascriptServlet.cacheControl</param-name>
    <param-value>no-store</param-value>
</context-param>
-------------------------------------------------------------------------------

## Building the code

1. Make sure you have [Apache Maven](https://maven.apache.org/) 3.6.3+, JDK 1.8+ and respectively JDK 11+ for Jakarta installed
2. Clone this repository locally
3. Build the project by running ```mvn clean install``` in the project root directory
4. Build and run the test JSP web application by running one of the following commands:
   ```shell
   mvn pre-integration-test -Pdeploy-jsp-webapp -pl csrfguard-test/csrfguard-test-jsp

mvn -Pdeploy-jsp-webapp -pl csrfguard-test/csrfguard-test-jsp tomcat7:run

6. Optional: you can use mvnDebug to enable remote debugging, then connect your IDE to it (default port is 8000)
7. Use a web browser to access http://localhost:8080 to open the home page of the test project

Uploading to the Maven Central repository (for project leaders)

1. Follow the Sonatype Open-Source Project Maven Repository Usage Guide to create a Sonatype user account;
2. Next, open a support request to get your newly created username added to the Maven groupId org.owasp;
3. The ticket must be approved by a CSRFGuard project leader or someone who already has permissions to deploy under the group and artifactId.
4. Once the support request has been completed, follow the instructions in the Sonatype Maven repository usage guide mentioned above to upload new versions to the Maven Central repository.

GPG Key generation and distribution

See: https://central.sonatype.org/publish/requirements/gpg/

gpg --full-gen-key
gpg --list-keys
gpg --list-secret-keys # if you've migrated your keys from another machine, make sure you have your secret key(s) imported
gpg --keyserver keys.gnupg.net --send-key <your_public_key_here> # you can define other supported key servers as well

Example .m2/settings.xml snippet required for releasing:

<settings xmlns="https://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="https://maven.apache.org/SETTINGS/1.0.0
                      https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <servers>
        <server>
            <id>ossrh</id> <!-- the id must match with the repository id defined in distributionManagement -->
            <username><!--your_oss_sonatype_username--></username>
            <password><!--your_oss_sonatype_password--></password>
        </server>
    </servers>

    <profiles>
        <profile>
            <id>ossrh</id>
            <activation>
                <activeByDefault>true</activeByDefault>
            </activation>
            <properties>
                <gpg.passphrase><!--your_gpg_passphrase--></gpg.passphrase>
            </properties>
        </profile>
    </profiles>
</settings>

Test signing your artifacts manually:

mvn clean verify -Psign-artifacts -Dgpg.passphrase=<your_gpg_passphrase> # should generate .asc files in the target directory

Deploying to OSS Sonatype / Maven Central

Deploy a -SNAPSHOT version:

mvn clean deploy

Prepare a release:

mvn release:clean release:prepare

1. Set the version number you want to release in <MAJOR.MINOR.PATCH> format (e.g. 4.0.0)
2. Set the SCM release tag: (e.g. 4.0.0)
3. Set the new development version (e.g. 4.0.1-SNAPSHOT)

Check the created commits and tag to make sure everything looks as expected:

git log
git show HEAD
git show HEAD^
git tag -l # list tags

Rollback the local release:

mvn release:rollback # or "git reset HEAD^^ --hard"
git tag -d <tag_name_to_delete>

Upload the release to OSS Sonatype (staging):

mvn release:perform 

The maven-release-plugin executes the deploy (default). This triggers the execution of the nexus-staging-maven-plugin, which uploads the artifacts to the OSS Sonatype staging repository and releases them if they meet the requirements.

Manual release of a staging repository (in case autoReleaseAfterClose is set to false)

• Visit https://oss.sonatype.org/#stagingRepositories
• Review the newly created repository against the requirements (JAR files, sources, JavaDocs and associated PGP armored ASCII files are present with the desired version etc.)
• Close the repository to trigger the validation of the uploaded components
• If there were no errors, click Release

Upon release, the new version is published to the Central Repository, typically within 30 minutes, but updates to search can take up to 4 hours.

Push the new release to GitHub:

git push origin master
git push origin <tag_name>

Maven repositories

You can download pre-compiled versions from:

• Maven Central repository
• OSS Sonatype Nexus repository