waf

NAME
SYNOPSIS
DESCRIPTION
SEE ALSO
AUTHOR
COPYRIGHT

NAME

waf - Configure the Web Application Firewall (WAF)

SYNOPSIS

[1] waf [(score [(response | request) [<score-nb>]]) | level [<level-nb>]]

[2] waf [generic [(dliis | dljava | dlphp | dlsql | java | lfi | nodejs | php | rce | rfi | sf | sqli | xss) (on | off )]]

[3] waf [reputation [(country [raz | (add | del) (<country-code>)+]) | (rbl [set <api-key>])]]

[5] waf [(errors | imethods) [(allow | deny)]]

[6] waf [rweb [generic [<site-name> <generic-filter> (on | off)]]]

[7] waf [rweb [custom [<site-name> [clear | (load | save) (ftp | sftp | tftp) <file-server> <file-name> [new]]]]]

[8] waf [rweb [audit [<site-name> [on | off]]]]

[9] waf [rweb [denyurl [(set <site-name> [<url>]) | raz [<site-name>]]]]

[10] waf [rweb [errors [raz | add <site-name> (allow | deny) | del <site-name> | show [<site-name>]]]]

[11] waf [bypass rule [raz] | rweb bypass [rule [<site-name> [raz | (add | del) (<rule-id>)+]]]]

[13] waf [dos [<requests-limit> <duration-period> <blocking-period>]]

DESCRIPTION

The WAF (Web Application Firewall) blocks malicious requests and prevent data leakages to protect Web applications against unwanted or threatening accesses. This command is used to manage the WAF to protect websites cloaked by the reverse proxy in rweb mode (see the rweb command). To protect Web applications, you can use generic WAF rules or design your own customised WAF rules.

Generic WAF rules are classified by groups called filters (a filter is composed of WAF rules). Each blocking rule in a generic filter has a score point (an integer) and whenever a rule is matched in a Web traffic, its score point is added to a global score. Once a threshold score is reached for a given Web traffic, the Web traffic is blocked by the WAF. The WAF distinguish two types of traffic: requests and responses. The first usage form allows you to configure the scoring system: use the keyword score followed by the keywords request or response to set score thresholds for Web requests and responses. A valid score threshold is an integer between 1 and 9. Rules in generic filters are classified by levels. The higher the WAF level, the more restrictive (paranoic) rules are activated. When activating the WAF for the first time, it is recommended to use the lowest WAF level (1) in order to avoid false positive matches. To configure the WAF level you can use the keyword level followed by the required level. A valid level is an integer between 1 and 4.

The second usage form allows you to activate or deactivate global generic WAF filters applicable to all websites. Generic rules are provided by OWASP (https://owasp.org/). Please note that generic rules may produce false positive matching. In this case, you can review your Web application for adjustment instead of deactivating the related generic rule. You can use the Web auditing module to inspect Web requests and rule matching (see below).

Here is a brief description of generic WAF rules:

• dliis: rules to prevent from IIS applications Data Leakage.

• dljava: rules to prevent from Java applications Data Leakage

• dlphp: rules to prevent from PHP applications Data Leakage.

• dlsql: rules to prevent from SQL requests Data Leakage.

• java: rules to protect Java Applications.

• lfi: rules to protect against Local File Inclusion attacks.

• nodejs: rules to protect Node.js Applications.

• php: rules to protect PHP Applications.

• rce: rules to protect against Remote Code Execution attacks.

• rfi: rules to protect against Remote File Inclusion attacks.

• sf: rules to protect against Session Fixation attacks.

• sqli: rules to protect against SQL Injection attacks.

• xss: rules to protect against Cross-site Scripting attacks.

You can find more information about OWASP CRS at https://owasp.org/

The third usage form allows you to block Web requests according to the client reputation. Two types of reputation are available: reputation based on countries and reputation based on IP Real Time Blacklists (RBL). RBL are provided by the Project Honey Pot. To benefit from IP blacklists you must have an API key. Please refer to https://www.projecthoneypot.org/ to get a free API key. Country based reputation use data provided by MaxMind (https://www.maxmind.com/). Country data are automatically updated on a monthly basis.

To block all Web requests coming from a particular country use the keywords reputation country add followed by the ISO 3166-1 alpha-2 code of that country. To block multiple countries you can specify a list of country code separated by a blank or use this command usage form several times. You can use the keyword del to disable the blocking for countries. The keyword raz allows you to disable all country based blockings. To activate the reputation based on RBL use the keywords reputation rbl set followed by your private API key. You can deactivate this feature by using an ampty string as the API key.

The fourth usage form allows you to specify limits for all Web requests and responses. These limits are applied globally to all responses and requests. The following limits can be configured:

• response: maximum response body size in KB.

• request: maximum request body size in KB, excluding the size of any files being transported in the request.

• assertions: maximum number of assertions (attributes=values) or arguments in a request (the separator should be ’&’).

• name: maximum length for an argument name in a request.

• value: maximum length for an argument value in a request.

• arguments: total arguments (names and values) length limit in a request.

• files: maximum size in KB for combined uploaded files. This value can’t be greater than the value given during the installation for uploaded files.

The fifth usage form allows you to globally configure some WAF policies. The keyword errors allows you to expose or rewrite original error pages sent by websites. By an error page we mean a page sent with an HTTP status code other than 200. To allow the exposure of original error pages use the keyword allow. To rewrite original error pages use the keyword deny. The keyword imethods allows you to allow or deny insecure HTTP methods. Insecure HTTP methods are "PUT", "PATCH", "DELETE", "CONNECT" and "TRACE". To allow insecure HTTP methods use the keyword allow. To deny insecure HTTP methods use the keyword deny.

For security reasons, even if you globally allow insecure HTTP methods, you should bypass some OWASP rules using the waf rweb bypass usage form and then create custom rules to allow them. Please note that by default, insecure HTTP methods are not allowed and if you decide to globally allow them, you should know what you are doing. Otherwise you expose your Web applications to severe threats.

The sixth usage form allows you to activate or deactivate generic filters for a specific website. A website that no specific generic filters are defined for inherits global filters.

The seventh usage form allows you to load/save custom rule files from/to a file server. Custom rules allow you to have restrictive controls on allowed or denied requests on a website. The "GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "CONNECT", "OPTIONS" and "TRACE", HTTP methods can be filtered by defining regular expressions for allowed or denied requests.

The process of custom rule definition is very easy. To do so, just create your rule file for a specific website and then load it into the system. Because regular expressions may be complex, this process allows you to use your favourite text editor (vi, emacs...) to edit the rules file.

In the custom rule file, each rule definition begins with a line having the following syntax:

rule <rule-name> (allow | deny) <method>

Where <method> is a valid HTTP method (get, head, post, put, patch, delete, connect, options, trace) in lower-case or a list of valid HTTP methods separated by the pipe charcter.

Followed by optionnal lines having the following syntax:

(uri | body | ip) "<regular-rexpression>"

Keywords and arguments must be separated with blanks or tabulations delimiters.

If a line begins with the rule statement, three mandatory arguments must be specified:

The first argument is the rule identifier. It allows you to identify the rule in audit mode (see below). A rule identifier must be a combination of alphanumeric characters and the characters "_", "-" or "." (the dot) and begin with an alphanumeric character.

The second argument specifies the action (allow deny) and finally the third argument is the HTTP method in lowercase. Optional lines begins with the following keywords:

• uri: The part after the "/" character in a URL (can be used with POST and GET methods)

• body: Arguments in the body of a POST (can be used only in conjunction with a uri statement and POST method)

• ip: the source IP address of the client making the Web request

followed by a regular expression between quotation marks. Note that a quotation mark in a regular expression should not be preceded by a back slash character here. Regular expressions are based on PCRE (Perl Compatible Regular Expression).

For instance to allow only the GET on "/" and the POST on "/cgi-bin/set-phone.cgi" with arguments "name=<string> phone=<numbers>" the custom rule file looks like:

rule r10 allow get
uri "^/$"

rule r20 allow get
uri "^/cgi-bin/get-phone\.cgi"

rule r30 allow post
uri "^/cgi-bin/set-phone\.cgi$"
body "^name=[[:print:]]*\&phone=[[:digit:]]*$"
ip "^192\.168\.155\.254$"

rule r40 deny get|post
uri "^/cgi-bin/set-phone\.cgi$"

After a custom rule file is loaded, its syntax is verified and the loading is confirmed only if no errors are detected. Note that generic filters are always applied (when activated) before custom rules.

The eighth usage form allows you to manage the audit mode for a website. Auditing allows you to inspect HTTP/S request contents and facilitate the filtering rule design process. To activate the audit mode for a website use the keyword on. To deactivate the audit mode use the keyword off. Without specifying a state (on or off), this command prints the audit mode for a website (or for all websites if no website is specified).

Caution: Note that the auditing feature is for debugging purpose only and in normal circumstances, it should not be activated.

When the audit mode is activated for a website and when the administration audit mode is turned on (see the command admin), all related Web request contents can be inspected at the URL https://<admin-ip>:<wadmin-port>.

In audit mode, an HTTP request header and body (for the POST method), the matched filtering rule and the resulting state (allowed or denied) are logged. In this way, the security staff can easily design custom filtering rules for managed websites.

Note that the audit mode is helpful during the filtering rule design process and should not be activated on a production appliance. Auditing consumes lots of hardware resources and, in terms of security, is not recommended for production appliances.

When the audit mode is deactivated for a website, all auditing data for that website is lost.

By default when access is denied, a generic deny page is displayed. The ninth usage form allows you to set a custom deny page to redirect to a website. To set a deny URL page for a website, use the keyword denyurl followed by the keyword set, the website name and the URL you want to redirect to. To reset to the default behaviour use the keyword raz followed by the website name. To reset to the default behaviour for all websites give no website name. When no optional arguments are used, this usage form displays the current settings. If a URL is given it should be in the form: (http|https|ftp)://<domain-name>[/<URI>] where an URI may contain an alphanumeric or any of the following characters: -._~:/?#[]@!$&()*+,;=. Any other character needs to be encoded with the percent-encoding. A percent-encoding is in the form %(a-fA-F0-9)(a-fA-F0-9) (use %27 for the quote character).

Note: When both the waf and the antivirus modes are activated, the system filters all attempts to upload malware files on protected Web servers (usually files are uploaded using the post method and the multipart/form-data encryption type).

The tenth usage form allows you specifically set the exposure or rewriting of original error pages for a website. If no specific rule is defined for a website the global behaviour is used (see the fifth usage form). Keywords add, del, show and raz allows you respectively add a rule, delete a rule, show a rule and erase all rules. To allow the exposure of original error pages use the keyword allow. To rewrite original error pages use the keyword deny.

OWASP CRS may generate false positive matches. The term false positive refers to legitimate Web traffic denied by the WAF. To avoid this situation you can review your Web application source code in order to bypass false positive matches. But in most cases this is not an option because you don’t own the application or just don’t want to modify things. In this case you have the possibility to bypass the rule causing the false positive match. To do so you can use the eleventh and twelfth usage forms. To bypass an OWASP rule for a given website use the keywords rweb bypass rule followed by the website name, the keyword add and one or more rule IDs to bypass. To remove a bypass statement use the keyword del instead of the keyword add. To remove all bypass statements for a given website use the keyword raz. To remove all bypass statements for all websites use the keyword bypass rule followed by the keyword raz. Please note that the rule ID is a numerical value and is different than the rule name given for custom rules. You can find the ID of the rule causing false positive match by using the auditing module. See the command admin waudit for further information on the auditing module.

Some well-known applications such as WordPress or Drupal are known to produce false positive matches. To bypass all known rules that produce false positive matches for a given application you can use the twelfth usage form. Supported applications are as follows:

• cPanel

• DokuWiki

• Drupal

• Nextcloud

• WordPress

• XenForo

The WAF has the ability to protect Web applications against DoS (Denial of Service) by blocking clients that make requests (excluding static files) above a certain limit. The thirteenth usage form allows you to tune the DoS protection by specifying how many requests is allowed by a client (<requests-limit>) in a given duration (<duration-period>) and how long block (<blocking-period>) that client. Periods should be specified in seconds. For instance values 120 300 180fR would mean that if a client makes more than 300 requests in 120 seconds, he will no longer be able to submit requests for 180 seconds. Allowed values for arguments are as follows: <requests-limit> is an integer between 1 and 1000000, <duration-period> is an integer value between 1 and 86400 and <blocking-period> is an integer value between 1 and 604800.

AUTHOR

CacheGuard Technologies Ltd <www.cacheguard.com>

Send bug reports or comments to the above author.