Referer Handler

Purpose

ATTENTION
Using a graylist can reduce performance and should therefore only be used by experienced administrators.

The Referer Handler is used to detect and prevent undesirable links to your web application. To do this, vWAF evaluates the HTTP referer header. This header describes the URL of the page from which the user has arrived via a link. HTTP referers are also sent by most browsers when a user clicks on a link or sends a form (but not in the event of a page reload or with an HTTP Redirect).

If the Referer Handler is active and if the user’s browser also sends an HTTP referer header, the process is as follows:

ATTENTION
This process is an exception to the general rule on how most other blacklists, whitelists, and graylists work (compare How Blacklists, Whitelists, and Graylists Are Processed).

vWAF compares the HTTP referer with a whitelist. If vWAF finds a match, it permits the request.
If vWAF doesn’t find a match with the whitelist and if the option whitelistonly has been activated, the request is handled as if the HTTP referer was on a blacklist (see step 3).
If the option whitelistonly isn’t activated, vWAF then compares the HTTP referer with all hosts on the blacklist. If vWAF finds a match here, it denies the request. This is carried out either using an HTTP error code 403 (Forbidden) if the option blockblacklist has been activated, or using an HTTP redirect to the URL given in the blacklisturl field.
If vWAF is unable to find a match either on the whitelist or on the blacklist, it notes the HTTP referer with the time of the access on an internal graylist. If the number of accesses with this HTTP referer exceeds the number given in the threshold counter field within the time period specified in the threshold timedelta field, vWAF generates an HTTP redirect to the URL given in the graylisturl field. Otherwise vWAF accepts the requests.

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

Severity

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

Recommendations for use

A whitelist with the whitelistonly option activated can make it difficult to link to a page, and a blacklist can explicitly include undesirable links. In both cases, you can redirect the user to a page providing information on the fact that he has reached a potentially dangerous page and that his data may have been obtained by deception. You can also use a blacklist to exclude links from pages very precisely, e.g. pages that are using deep linking or pages that you don’t want to have connected to your company.

A similar thing is possible in graylisting. An inbound link from third party sites is possible in principle, but only if they aren’t used too often. This can also be used to protect against phishing: To begin with (when the attacker is testing the site), the page functions as normal, but when there are frequent requests for a specific page (for example when a phishing page loads images from the original page), vWAF generates an HTTP redirect to another URL and you can issue a warning there, for example, or deliver specific content.

Attributes

Attribute	Meaning
whitelist	HTTP referers with which requests are always to be permitted.
whitelistonly	Activate this option if you only ever want to permit requests where the referer has been entered on the whitelist. In this case, all other requests are handled as requests with a referer on the blacklist.
blacklist	HTTP referers with which requests are always to be denied or redirected.
blacklisturl	Page to which the user is to be redirected when they come from a HTTP referer located on the blacklist. The redirection only becomes active when the blockblacklist option has not been activated.
blockblacklist	Activate this option if you want requests with a HTTP referer located on the blacklist to be answered with an HTTP error code 403 (Forbidden). In this case, this means there's no redirect to the blacklisturl.
threshold counter	Maximum number of requests that can be received within the period specified under threshold timedelta before vWAF triggers a redirect to the page specified under graylisturl.
threshold timedelta	Period in seconds in connection with the attributes graylisturl and threshold counter.
graylisturl	Page to which users are redirected when those users come from a HTTP referer that isn't on either the blacklist or the whitelist and that vWAF has therefore placed on the graylist. The redirect is only carried out if more requests are received from the HTTP referer in the period specified under threshold timedelta than specified under threshold counter.
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.