Whitelist Handler

Purpose

The arguments of input form fields form a particularly frequently used attack vector, e.g. for SQL injection. The Whitelist Handler prevents manipulated arguments from reaching your web application in the first place.

The Whitelist Handler therefore checks the attributes of the HTTP request (both in the URL as well as in an HTTP POST request). An argument is only valid if it complies with one of the regular expressions specified under protected form fields.

If a form field isn’t covered by any of the regular expressions specified under protected form fields, it depends on the option allow unknown form fields what happens. If this option has been enabled, vWAF accepts the request. If the option has been disabled, vWAF denies the request with a configurable error code.

Despite the fact that the attribute is labeled protected form fields, the Whitelist Handler works just as well for whitelisting URL variables.

ATTENTION
After configuring and enabling the Whitelist Handler, fully check the function of the input forms of your web application again, so as to exclude the unintentional effects of making any unclear specifications for the protected form fields.

For more information regarding adding and editing Handlers, see Editing Handlers.

Severity

Events triggered by this handler are given the severity: high. (For details on severity levels, see Severity of Events Triggered by Handlers).

Recommendations for use

Use the Whitelist Handler in order to validate entries. Depending on the security requirements, you can only add some general rules or invest a lot of time in precisely covering all the input fields of your web application. Setting up the whitelist requires a considerable knowledge of the web application that’s to be protected, but does give you substantial security when you disable the option allow unknown form fields or when you combine the whitelist with a restrictive blacklist.

As an alternative to the Whitelist Handler, you can use the Invalid Args Handler to specify a blacklist instead of a whitelist. You can also combine both approaches and use the Whitelist handler in combination with the blacklist. In this case, if a request doesn’t comply with the whitelist it is checked with a blacklist. Therefore, in this scenario, vWAF only accepts a request either if it complies with the whitelist (regardless of what’s on the blacklist), or if it doesn’t comply with the whitelist but also doesn’t match with the blacklist.

For the whitelist, usually some templates are entered that don’t allow non-complex attacks like SQL injections, command injections or cross site scripting:

The ^\w[A-Za-z0-9_-]{1,32}=\w[A-Za-z0-9_ -]{1,32}$ template, for example, allows for all input fields with alphanumeric names (plus underscore and -) an alphanumeric value of maximum 32 characters (for syntax, refer to Regular Expressions). This usually allows the portrayal of all selection lists.

It can become problematic when entering names, passwords and free text. Here you should set up an independent pattern for each form field. The following template shows a suitable example for a password input field: ^password=.{0,63}$. This way, a field with the name password as a value can have a total of any 63 characters.

Interaction with other handlers

Arguments that pass the Whitelist Handler aren’t checked by the Invalid Args Handler and by the Baseline Protection Handler.

Attributes

Attribute	Meaning
protected form fields	List of regular expressions that describe the template for valid arguments. The name of the form field is given in front of the equals sign, the (valid) argument is positioned after the equals sign. Some examples are already entered as defaults. Delete this if required. Examples: The entry `^\w{1,63}=\w{1,63}$` accepts any arguments for form fields with field names comprising letters and figures and a length between 1 and 63 characters, also those consisting exclusively of letters and figures with a length between 1 and 63 characters. The entry `^\w{1,63}=.*$`accepts any arguments for the same form fields that can also be empty. (For details regarding syntax, refer to Regular Expressions.)
allow unknown form fields	Enable this option if you want vWAF to put form fields that aren't covered by the specified protected form fields attribute onto the whitelist.
log unknown form fields	Enable this option if you want vWAF to create an extra log file entry in case a request relates to a form field that isn't covered by the regular expressions entered for the attribute protected form fields.
shortcut	Enable this option if you want vWAF to accept the request immediately if all form fields are on the whitelist specified under protected form fields. If any further handlers have been defined in your security configuration, these handlers are ignored. This increases performance but might result in some loss of protection. If this option is enabled, also no log file entry is created. ATTENTION If you've configured the Invalid Args Handler, this results in the fact that the blacklist isn't considered for these form fields.
error code	HTTP error code that vWAF returns if the request doesn't comply with one of the specific regular expressions under protected form fields. (Refer to HTTP Error Codes for an overview of possible error codes.)
usertext	Optional: Here you can specify some text that vWAF adds to the log file entries created by this handler. You can use this, for example, to document why you've added the handler to your configuration, and how the handler is intended to behave.
enable logging	Disable this option if you do not want vWAF to create a log file entry when the handler is executed. This can be useful to keep log files smaller in case the handler creates a large number of entries but you don't need these entries. When in detection mode, disabling logging de facto makes the handler ineffective. Disabling logging also prevents the actions of the handler from being taken into account for the Top-10 lists in Attack Analysis, and from being listed in Reports. To decrease the size of the log files, also consider to enable reduced logging, which excludes all non-handler-related information from the log files (see Editing Applications).

For details regarding entries added to the log file by this handler, see the relevant section in Entries in Application-Specific Log Files.