Skip to main content
Version: 4.6.x.x LTS

CSRFFilter

The filter offers protection from Cross Site Request Forgery and related attacks by imposing additional conditions on incoming requests to filter out those not originating from the legitimate end user. The following tests are available, listed in the order of execution:

Referer Header​

If an incoming HTTP request contains the 'Referer' header, the hostname must match the 'Host' header.

Request ID​

JavaScript code with a random session-bound ID is injected into all HTML responses sent to the client. As the page loads in the browser, the script includes the ID in all the references pointing back to the web application. Depending on the request type, the ID is added either as an HTTP header, query parameter or a hidden field in forms. The filter checks incoming requests for the presence of the correct ID and removes it from all the requests passed through. The test should be enabled selectively for the most sensitive requests only, the injected script is not guaranteed to rewrite all the links.

Milestones​

Certain URIs can be defined to constitute a milestone. If milestone requests are made, they must arrive in a fixed preconfigured order.

Classname
ch::nevis::isiweb4::filter::validation::CSRFFilter

Library
libInputValidationFilter.so.1

Configuration​

RefererHeaderCheck​

  • Type: enum: false, true, or required. Conditional are allowed
  • Usage Constraint: optional
  • Default: true
  • This parameter defines whether the Referer HTTP header check is enabled, disabled or required:
    • false: Referer header check is disabled.
    • true: Referer header check is enabled if the header is present.
    • required: Blocks the request if the referer header is not present, else validates it.

InjectedIdCheck​

  • Type: boolean
  • Usage Constraint: optional
  • Default: false
  • Secure Default: true
  • Enables injection of JavaScript in HTML responses as well as the corresponding check on requests.

IdCheckEnable​

  • Type: boolean, conditions are supported
  • Usage Constraint: optional
  • Default: true
  • Supported pragmas: break
  • With this parameter you can turn on/off the check for the injected Id.

InjectionScriptPath​

  • Type: string
  • Usage Constraint: optional
  • Default: /var/opt/nevisproxy/<instance>/conf/csrf-inject.js
  • Defines the location of the .js file injected to HTML responses. The provided script (csrf-inject.js) works only on outgoing AJAX calls and URLs in the <href> tag.
  • Some use cases:
    • For more complex functions, such as javascript.window.open(), copy the csrf-inject.js script and adapt it to your backend(s).
    • To support some basic JavaScript functions, use a copy of the file csrf-with-basic-javascript-support-csrf-inject.js. You find this file in the examples directory of your installed nevisProxy package.
    • To support Captcha (or other pages containing image links), use a copy of the file csrf-with-image-support-csrf-inject.js. This file is also located in theexamples directory of your installed nevisProxy package.

IdQueryParamName​

  • Type: string
  • Usage Constraint: optional
  • Default: csrfpId
  • Name of the extra parameter with the ID added to requests by the injected JavaScript.

ProtectedURIs​

  • Type: list of regexps
  • Usage Constraint: optional
  • Newline separated list of regular expressions that define request URIs for which an ID is required. All other requests will be allowed. The default regex type is PCRE(da). The list should only contain selected sensitive URIs.

IdCheckWhitelist​

  • Type: list of regexps
  • Usage Constraint: optional
  • Newline separated list of regular expressions that define URIs exempt from ID checks, even if they match ProtectedURIs. The default regex type is PCRE(da).

ProtectPayloadOnly​

  • Type: boolean
  • Usage Constraint: optional
  • Default: true
  • Only requires the ID of requests that carry non-trivial payload. All HTTP requests without parameters will be allowed.

ContentTypes.html​

  • Type: list of content type regexps
  • Usage Constraint: optional, advanced
  • Default: ^text/html; ^application/xhtml
  • Newline separated list of regular expressions defining content types for HTML. If the content type of a response matches one of the configured values, the JavaScript code will be injected. The default regex type is PCRE(da).

RewriteBufferSize​

  • Type: integer
  • Usage Constraint: optional, advanced
  • Default: 16384
  • The size of the internal buffer (in bytes) for buffering HTML tags. Only relevant if the JavaScript is injected. (see InjectedIdCheck).

MilestoneCheck​

  • Type: boolean
  • Usage Constraint: optional
  • Default: false
  • Specifies whether the milestone URLs check is enabled.

Milestones​

  • Type: list of regexps
  • Usage Constraint: optional
  • Newline separated list of regular expressions that define milestone URIs. The milestone requests, if any, must be made precisely in the order listed. The default regex type is PCRE(da).

MilestoneRevisit​

  • Type: boolean
  • Usage Constraint: optional, advanced
  • Default: true
  • If enabled, repeated requests to milestone URIs are allowed, as long as all the earlier milestones have been requested at least once. When disabled, every milestone request can be made at most once during a session.

CSRFPolicy​

  • Type: space or newline separated list of error policies
  • Usage Constraint: optional, advanced
  • Default: REFERER_MISMATCH:block:403 MILESTONE_MISMATCH:block:403 ID_MISMATCH:block:403
  • Defines actions to perform when a particular test fails.
  • Format: <status>:<action>[:<error-code>][:<url>]
    • <status>: REFERER_MISMATCH, MILESTONE_MISMATCH, ID_MISMATCH.
    • <action>: BLOCK, REDIRECT, PASSTHROUGH, TRACE
    • <error code>: HTTP Error code to return, 403 by default (only applies to BLOCK)
    • <url>: The destination URL for REDIRECT (colon characters within the url must be escaped)

RedirectPolicy​

  • Type: enum: on, off, protectedUriOnly
  • Usage Constraint: optional
  • Default: on
  • This parameter controls the rewriting of redirect URIs. The default value is on, which means that the system will overwrite every redirect URI. If you set the parameter to protectedUriOnly, only the configured (and not whitelisted) URIs will be rewritten. To disable the feature, set the parameter to off.

RegenerateId​

  • Type: boolean
  • Usage Constraint: optional
  • Default: false
  • If this parameter is set to true, the system will generate a new ID for each request. If set to false, which is the default, the existing ID remains in use.

Examples​

This filter injects Javascript code to implement Cross Site Request Forgery.

Example
<filter>
 <filter-name>CSRFInjectionFilter</filter-name>
 <filter-class>ch::nevis::isiweb4::filter::validation::CSRFFilter</filter-class>
 <init-param>
  <param-name>InjectionScriptPath</param-name>
  <param-value>/opt/nevisproxy/template/conf/csrf-inject.js</param-value>
 </init-param>
 <init-param>
  <param-name>InjectedIdCheck</param-name>
  <param-value>true</param-value>
 </init-param>
 <init-param>
  <param-name>IdQueryParamName</param-name>
  <param-value>csrfpId</param-value>
 </init-param>
 <init-param>
  <param-name>ProtectedURIs</param-name>
  <param-value>/foo/.*</param-value>
 </init-param>
</filter>

If there are links pointing to non-protected URIs, you can modify the injected JavaScript to avoid these unprotected-URI links, and to rewrite only specific links. Below follows an example of how to do this.

  • First, replace the csrfCheckDomain function with the following one:
function csrfCheckDomain(attribute) {
 var index;
 index = attribute.indexOf("//");
 if(index != 0 && index != 5 && index != 6) {
 return relativeCheck(attribute)
 }

  • Then add one of the next relativeCheck function implementations:

    • Rewrite links pointing to a specific path:

      function relativeCheck(path) {
         var protected = "/example/auth/emailchange";
         return (path.indexOf(protected) == 0)
      }

    • Rewrite links pointing to the same page:

      function relativeCheck(path) {
         return (path.indexOf(location.pathname) == 0)
      }

Handling very simple HTML documents​

The CSRF filter requires a minimal structure of the HTML page. The page must include at least an html, head, and body tag. Although normal documents always have these tags, the HTML standard allows for missing these tags. Even a plaintext document is valid HTML.

The CSRF filter can handle missing head or body tags. But if your document lacks all of the abovementioned tags, you need to add them with a LuaFilter. Map the LuaFilter between the backend and the CSRFFilter. For an example, see the file LuaFilter_simple_html_fixer_for_CSRF.example.