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.
ch::nevis::isiweb4::filter::validation::CSRFFilter
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.
<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>
Modifying the injected JavaScript to rewrite only specific links
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)
}
index = index + 2;
try {
var desthost = attribute.substring(index, location.hostname.length+index);
var destpath = attribute.substring(location.hostname.length+index);
}
catch(e) {
return false;
}
if (desthost == location.hostname) {
return relativeCheck(destpath);
}
return false;
}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.