Skip to content

Commit f64a43f

Browse files
ADubhlaoichADubhlaoich
committed
feat: Push work
1 parent 5e72907 commit f64a43f

File tree

3 files changed

+124
-82
lines changed

3 files changed

+124
-82
lines changed

‎content/waf/policies/directives.md‎

Lines changed: 65 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -12,47 +12,60 @@ nd-content-type: reference
1212
nd-product: NAP-WAF
1313
---
1414

15+
This topic describes the global NGINX directives and directives specific to F5 WAF for NGINX.
16+
17+
1518
## Global directives
1619

17-
Global configuration consists of a series of `nginx.conf` directives at the `http` context controlling aspects that are not specific to a specific application.
20+
Global configuration consists of a series of `nginx.conf` directives at the `http` context controlling aspects that are not specific to a specific application. When applied to a cluster, all cluster members will get the same globals.
21+
22+
The URL in a request determines whether or not it will be inspected by F5 WAF for NGINX. This is defined by `app_protect_enable` and `app_protect_policy_file` directives in the `location` scope.
23+
24+
In the case that the URL itself has violations such as *bad unescape* or *illegal metacharacter*, the request may be assigned to a location in which F5 WAF for NGINX is disabled or has a relaxed policy that does not detect these violations.
1825

19-
When applied to a cluster, all cluster members will get the same globals as expected.
26+
Such malicious requests will be allowed without inspection.
2027

21-
{{< call-out "note" >}} Whether an incoming request is inspected by F5 WAF for NGINX may be determined by the URL in the request. This happens if you configure `app_protect_enable` and `app_protect_policy_file` directives in the `location` scope. In the case where the URL itself has violations such as *bad unescape* or *illegal metacharacter* then the request might be assigned to a location in which F5 WAF for NGINX is disabled or has a relaxed policy that does not detect these violations. Such malicious requests will be allowed without inspection. In order to avoid this, it is recommended to have a basic policy enabled at the `http` scope or at least at the `server` scope to process malicious requests in a more complete manner.{{< /call-out >}}
28+
In order to avoid this, it is recommended to have a basic policy enabled at the `http` scope or at least at the `server` scope to process malicious requests in a more complete manner.
2229

23-
{{< bootstrap-table "table table-striped table-bordered table-sm table-responsive" >}}
24-
|Directive Name | Syntax | Description | Default |
25-
| ---| ---| ---| --- |
26-
|app_protect_physical_memory_util_thresholds | app_protect_physical_memory_util_thresholds high=<number_0-100> low=<number_0-100> | Sets the physical memory utilization thresholds for entering (high) and exiting (low) failure mode. When the high threshold is exceeded the system enters failure mode until memory drops below the low threshold. Setting the value of 100 disables this feature. | high=low=100 (disabled) |
27-
|app_protect_cpu_thresholds | app_protect_cpu_thresholds high=<number_0-100> low=<number_0-100> | Sets the CPU utilization thresholds for entering and exiting failure mode respectively: when the high threshold is exceeded the system enters failure mode until CPU drops below the low threshold. Setting the value of 100 disables this feature.<br> **Note**: The system does not enter failure mode during policy compilation after reload even if the threshold is exceeded. | high=low=100 (disabled) |
28-
|app_protect_failure_mode_action | app_protect_failure_mode_action pass &#124; drop | How to handle requests when the App Protect Enforcer cannot process them, either because it is down, disconnected or because of excessive CPU or memory utilization. There are two values:<ul><li>**pass**: Pass the request without App Protect Enforcer inspection, a.k.a. "fail-open".</li><li>**drop**: Drop the request by returning the response "503 Service Unavailable", a.k.a. "fail-close".</li></ul> | pass |
29-
|app_protect_cookie_seed | app_protect_cookie_seed <string> | A long randomized string that serves to generate the encryption key for the cookies generated by App Protect. The string should contain only alphanumeric characters and be no longer than 1000 characters. | Auto-generated random string |
30-
|app_protect_compressed_requests_action | app_protect_compressed_requests_action pass &#124; drop | Determines how to handle compressed requests. There are two values:<ul><li>**pass**: Pass the request without App Protect Enforcer inspection, a.k.a. "fail-open".</li><li>**drop**: Drop the request by returning the response "501 Not Implemented", a.k.a. "fail-close".</li></ul> **Note**: Starting with App Protect release version 4.6, this directive has been deprecated from the `nginx.conf` file. | drop |
31-
|app_protect_request_buffer_overflow_action | app_protect_request_buffer_overflow_action pass &#124; drop | Determines how to handle requests in case the NGINX request buffer is full and requests cannot be buffered anymore. There are two values:<ul><li>**pass**: Pass the request without App Protect Enforcer inspection, a.k.a. "fail-open".</li><li>**drop**: Drop the request by resetting connection. No response page is returned, a.k.a. "fail-close".</li></ul> | pass |
32-
|app_protect_user_defined_signatures | app_protect_user_defined_signatures <path> | Imports the user-defined tagged signature file with the respective tag name from the provided path. Multiple instances of this directive are supported. In order to import multiple signatures files, each file must have a different tag. | N/A |
30+
{{< table >}}
31+
32+
| Name | Syntax | Description | Default |
33+
| ---- | -------| ----------- | ------- |
34+
| app_protect_physical_memory_util_thresholds | app_protect_physical_memory_util_thresholds high=<number_0-100> low=<number_0-100> | Sets the physical memory utilization thresholds for entering (high) and exiting (low) failure mode. When the high threshold is exceeded the system enters failure mode until memory drops below the low threshold. Setting the value of 100 disables this feature. | high=low=100 (disabled) |
35+
| app_protect_cpu_thresholds | app_protect_cpu_thresholds high=<number_0-100> low=<number_0-100> | Sets the CPU utilization thresholds for entering and exiting failure mode respectively: when the high threshold is exceeded the system enters failure mode until CPU drops below the low threshold. Setting the value of 100 disables this feature.<br> **Note**: The system does not enter failure mode during policy compilation after reload even if the threshold is exceeded. | high=low=100 (disabled) |
36+
| app_protect_failure_mode_action | app_protect_failure_mode_action pass &#124; drop | How to handle requests when the F5 WAF for NGINX Enforcer cannot process them, either because it is down, disconnected or because of excessive CPU or memory utilization. There are two values:<ul><li>**pass**: Pass the request without F5 WAF for NGINX Enforcer inspection, a.k.a. "fail-open".</li><li>**drop**: Drop the request by returning the response "503 Service Unavailable", a.k.a. "fail-close".</li></ul> | pass |
37+
| app_protect_cookie_seed | app_protect_cookie_seed <string> | A long randomized string that serves to generate the encryption key for the cookies generated by F5 WAF for NGINX. The string should contain only alphanumeric characters and be no longer than 1000 characters. | Auto-generated random string |
38+
| app_protect_compressed_requests_action | app_protect_compressed_requests_action pass &#124; drop | Determines how to handle compressed requests. There are two values:<ul><li>**pass**: Pass the request without F5 WAF for NGINX Enforcer inspection, a.k.a. "fail-open".</li><li>**drop**: Drop the request by returning the response "501 Not Implemented", a.k.a. "fail-close".</li></ul> **Note**: Starting with F5 WAF for NGINX release version 4.6, this directive has been deprecated from the `nginx.conf` file. | drop |
39+
| app_protect_request_buffer_overflow_action | app_protect_request_buffer_overflow_action pass &#124; drop | Determines how to handle requests in case the NGINX request buffer is full and requests cannot be buffered anymore. There are two values:<ul><li>**pass**: Pass the request without F5 WAF for NGINX Enforcer inspection, a.k.a. "fail-open".</li><li>**drop**: Drop the request by resetting connection. No response page is returned, a.k.a. "fail-close".</li></ul> | pass |
40+
| app_protect_user_defined_signatures | app_protect_user_defined_signatures <path> | Imports the user-defined tagged signature file with the respective tag name from the provided path. Multiple instances of this directive are supported. In order to import multiple signatures files, each file must have a different tag. | N/A |
3341
|app_protect_reconnect_period_seconds| app_protect_reconnect_period_seconds <value> <br> **Value type**: number with decimal fraction <br> **Value Range**: 0-60. 0 is illegal | Determines the period of time between reconnect retries of the module to the web application firewall (WAF) engine. The time unit is seconds.| 5 |
34-
{{< /bootstrap-table >}}
3542

36-
### App Protect Specific Directives
43+
{{< /table >}}
44+
45+
## F5 WAF for NGINX directives
46+
47+
{{< table >}}
3748

38-
This table summarizes the nginx.conf directives for F5 WAF for NGINX functionality.
49+
| Name | Syntax | Functionality | Contexts | Example |
50+
| ---- | ------ | ------------- | -------- | ------- |
51+
| load_module | load_module <library_file_path> | NGINX directive to load the F5 WAF for NGINX module. It must be invoked with the F5 WAF for NGINX library path | Global | load_module modules/ngx_http_app_protect_module.so |
52+
| app_protect_enable | app_protect_enable on &#124; off | Whether to enable F5 WAF for NGINX at the respective context. If not present, inherits from the parent context | HTTP, Server, Location | app_protect_enable on |
53+
| app_protect_policy_file | app_protect_policy_file <file_path> | Set a F5 WAF for NGINX policy configuring behavior for the respective context. | HTTP, Server, Location | app_protect_policy_file /config/waf/strict_policy.json |
54+
| app_protect_security_log_enable | app_protect_security_log_enable on &#124; off | Whether to enable the F5 WAF for NGINX per-request log at the respective context. | HTTP, Server, Location | app_protect_security_log_enable on |
55+
| app_protect_security_log | app_protect_security_log <file_path> <destination> | Specifies the per-request logging: what to log and where | HTTP, Server, Location | app_protect_security_log /config/waf/log_illegal.json syslog:localhost:522 |
56+
| app_protect_custom_log_attribute | app_protect_custom_log_attribute <key_value> | Specifies the assigned location/server/http dimension of each request. | HTTP, Server, Location | app_protect_custom_log_attribute ‘environment' 'env1' |
3957

40-
{{<bootstrap-table "table table-striped table-bordered table-sm table-responsive">}}
41-
|Directive Name | Syntax | Functionality | nginx.conf Contexts | Example |
42-
| ---| ---| ---| ---| --- |
43-
|load_module | load_module <library_file_path> | NGINX directive to load the App Protect module. It must be invoked with the App Protect library path | Global | load_module modules/ngx_http_app_protect_module.so |
44-
|app_protect_enable | app_protect_enable on &#124; off | Whether to enable App Protect at the respective context. If not present, inherits from the parent context | HTTP, Server, Location | app_protect_enable on |
45-
|app_protect_policy_file | app_protect_policy_file <file_path> | Set a App Protect policy configuring behavior for the respective context. | HTTP, Server, Location | app_protect_policy_file /config/waf/strict_policy.json |
46-
|app_protect_security_log_enable | app_protect_security_log_enable on &#124; off | Whether to enable the App Protect per-request log at the respective context. | HTTP, Server, Location | app_protect_security_log_enable on |
47-
|app_protect_security_log | app_protect_security_log <file_path> <destination> | Specifies the per-request logging: what to log and where | HTTP, Server, Location | app_protect_security_log /config/waf/log_illegal.json syslog:localhost:522 |
48-
|app_protect_custom_log_attribute | app_protect_custom_log_attribute <key_value> | Specifies the assigned location/server/http dimension of each request. | HTTP, Server, Location | app_protect_custom_log_attribute ‘environment' 'env1' |
49-
{{</bootstrap-table>}}
58+
{{< /table >}}
5059

51-
#### Horizontal Scaling
60+
### Horizontal scaling
5261

53-
F5 WAF for NGINX can be deployed in multiple instances that share the traffic to the same applications. In that case all the instances must share the same configuration files. It is your responsibility to synchronize the files on all instances. You also have to provide a load balancing solution in front of those instances such as another NGINX instance.
62+
F5 WAF for NGINX can be deployed in multiple instances that share the traffic to the same applications.
5463

55-
When deploying multiple scalability instances you have to add the `app_protect_cookie_seed` directive to nginx.conf in the `http` block:
64+
In this case, all instances must share the same configuration files.
65+
66+
It is your responsibility to synchronize the files on all instances. You must also load balancing each of those instances, such as using additional NGINX instances.
67+
68+
When deploying multiple scalability instances add the `app_protect_cookie_seed` directive to nginx.conf in the `http` block:
5669

5770
```nginx
5871
...
@@ -67,14 +80,17 @@ http {
6780
...
6881
```
6982

70-
As the argument of this directive, put a random alphanumeric string of at least 20 characters length (but not more than 1000 characters). That seed is used by F5 WAF for NGINX to generate the encryption key for the cookies it creates. These cookies are used for various purposes such as validating the integrity of the cookies generated by the application.
83+
The argument for the directive should be a random alphanumeric string of at least 20 characters length (Maximum 1000 characters).
7184

72-
In the absence of this directive, App Protect generates a random string by itself. In that case, each instance will have a different seed. A cookie created and encrypted on one instance of App Protect will fail to be decrypted when sent by the same client to another App Protect instance having a different encryption key.
85+
This is a seed used by F5 WAF for NGINX to generate the encryption key for the cookies it creates. These cookies are used for various purposes such as validating the integrity of the cookies generated by the application.
7386

87+
In the absence of this directive, F5 WAF for NGINX generates a random string by itself. In that case, each instance will have a different seed.
7488

75-
#### Failure Mode
89+
A cookie created and encrypted on one instance of F5 WAF for NGINX will fail to be decrypted when sent by the same client to another F5 WAF for NGINX instance having a different encryption key.
7690

77-
If the App Protect daemons are down or disconnected from the NGINX workers, there are two modes of operation until they are up and connected again:
91+
### Failure modes
92+
93+
If the F5 WAF for NGINX daemons are down or disconnected from the NGINX workers, there are two modes of operation until they are up and connected again:
7894

7995
- **Pass** the traffic without inspection. Use this when preferring availability over security. This mode is also known as "fail open".
8096
- **Drop** the traffic. Use this when preferring security over availability. This mode is also known as "fail closed".
@@ -96,16 +112,26 @@ http {
96112
...
97113
```
98114

99-
#### Handling Compressed Requests
115+
## Handling compressed requests
116+
117+
{{< call-out "warning" >}}
118+
119+
From F5 WAF for NGINX release version 4.6, the `app_protect_compressed_requests_action` directive was removed deprecated from the nginx configuration.
120+
121+
When configuring this directive in the `nginx.conf` file, F5 WAF for NGINX will disregard any previously used values ("pass" or "drop") and issue a warning.
122+
123+
{{< /call-out >}}
100124

101-
Starting with F5 WAF for NGINX release version 4.6, the [`app_protect_compressed_requests_action`](#global-directives) directive has been deprecated from the nginx configuration. When configuring this directive in the `nginx.conf` file, App Protect will disregard any previously used values ("pass" or "drop") and issue a warning.
125+
By default, the enforcer will now decompress all the HTTP compressed payload request and will apply the enforcment.
102126

103-
#### Handling Decompression
127+
The supported compression algorithms for this feature are "**gzip**" and "**deflate**".
104128

105-
Now by default the enforcer will decompress all the HTTP compressed payload request and will apply the enforcment. The supported compression algorithms for this feature are "**gzip**" and "**deflate**". There will be no decompression, if the compression method is not supported.
129+
Decompression may fail under certain conditions:
106130

107-
The 'Content-Encoding' header must match the compression algorithm used while sending compressed payload in a HTTP request, else the enfocer will fail to decompress the payload.
131+
- If the compression method is not supported
132+
- If the 'Content-Encoding' header does not match the compression algorithm used while sending a compressed payload in a HTTP request
133+
- If thehe decompressed request is larger than 10 MB
108134

109-
The decompressed request must not exceed the size limit of 10 MB. If it does exceed this limit, F5 WAF for NGINX will only decompress the first 10 KB, ignoring the remainder, and trigger the `VIOL_REQUEST_MAX_LENGTH` violation, just as it would for an uncompressed request that exceeds 10 MB.
135+
If it does exceed this limit, F5 WAF for NGINX will only decompress the first 10 KB, ignoring the remainder, and trigger the `VIOL_REQUEST_MAX_LENGTH` violation, just as it would for an uncompressed request that exceeds 10 MB.
110136

111137
In the cases where decompression fails, F5 WAF for NGINX will continue with the scan in the same manner as it does for uncompressed requests.

0 commit comments

Comments
 (0)