Wallarm Configuration Options

NGINX official documentation

The Wallarm configuration is very similar to the NGINX configuration. See the official NGINX documentation. Along with the Wallarm specific configuration options, you have the full capabilities of NGINX configuration.

Wallarm Variables

Name Type Value
wallarm_request_time Float Request execution time in seconds
wallarm_serialized_size Integer Size of the serialized request in bytes
wallarm_is_input_valid Integer Request validity
0: request is valid. The request has been checked by filter node and matches LOM rules.
1: request is invalid. The request has been checked by filter node and does not match LOM rules.
wallarm_attack_type Integer Attack types represented in the request in bit string format
0x00000000: no attack: "0"
0x00000001: agressive mode flag: "1"
0x00000002: xss: "2"
0x00000004: sqli: "4"
0x00000008: rce: "8"
0x00000010: xxe: "16"
0x00000020: ptrav: "32"
0x00000040: crlf: "64"
0x00000080: redir: "128"
0x00000100: nosqli: "256"
0x00000200: infoleak: "512"
0x00000400: brute: "1024"
0x00000800: dirbust: "2048"
0x00001000: marker: "4096"
0x20000000: overlimit_res: "536870912"
0x40000000: zip_bomb: "1073741824"
0x80000000: vpatch: "2147483648"

Example:

log_format wallarm_combined         '$remote_addr - $remote_user [$time_local] '
                                    '"$request" $status $body_bytes_sent '
                                    '"$http_referer" "$http_user_agent"'
                                    ' attack: "$wallarm_attack_type"';

access_log /var/log/nginx/wallarm.log  wallarm_combined if=$wallarm_attack_type;

Wallarm Directives

wallarm_acl

Allows you to restrict access to resources when a request IP address is in the specified ACL (Access Control List).

The specified ACL must be declared with the directive wallarm_acl_db.

You can use the satisfy directive to set constraints from both the ACL and other Nginx modules, such as ngx_http_access_module.

Setting directive to off disables the ACL check.

Example:

satisfy any;

wallarm_acl wapi;

allow 1.2.3.4/0;
deny all;

This parameter can be set in the context of http, server and/or location.

wallarm_acl_api

If this directive is applied within the location context, than this location can be used to manage ACL content.

Example:

location / wallarm-acl {
  allow 127.0.0.1;
  deny all;

  wallarm_acl wapi;
  wallarm_acl_api on;
}

This parameter can be set in the context of http, server and/or location.

wallarm_acl_db

Allows you to declare and configure an ACL database to restrict access by IP addresses.

Example

wallarm_acl_db wapi {
  wallarm_acl_path /var/cache/nginx / wallarm/acl/wapi;
}

The parameter can only be configured at the main level.

wallarm_acl_mapsize

Allows you to set the initial memory size to be allocated for the corresponding ACL.

When the limit is reached, the memory will be automatically reallocated, but the API request that attempted to change the ACL and caused the overflow, will produce an error and should be repeated.

The parameter can only be configured in the wallarm_acl_dbsection.

wallarm_acl_path

Specifies the directory that will be used to save the state of the ACL.

The parameter can only be configured inside the wallarm_acl_db section.

wallarm_block_page

This directive lets you set up the page returned to the client when blocking an invalid request. The directive can take any value which is valid for internal redirection, including a named location. You can also assign a path to the blocking page template to this directive.

To set a custom page that returns on a request sent by a blocked user:

  1. Create a page and put it on your server. For example, a block.html page.
  2. In the configuration file, add the wallarm_block_page directive with the page name and a path to it: wallarm_block_page /path/block.html.

    This will return the block.html page on a request sent by a blocked user.

To set a custom location configuration that will be applied to a request sent by a blocked user:

  1. In the configuration file, add the wallarm_block_page directive with the location configuration.
  2. Enter the desired blocking message into the location block. For example:

     wallarm_block_page @block;
     location @block {'The page is blocked!';}
    

    The page will be blocked with the The page is blocked message.

To set a dynamic page template on a request sent by a blocked user:

  1. Create a custom template for the blocking page and save it on the machine that nginx runs on. You can also use the default template that Wallarm provides you with.

    Including nginx variables into the blocking page template

    You can include nginx variable into your blocking page template to display its value dynamically by specifying the name of the nginx variable starting with the $ symbol.

  2. In the configuration file, add the wallarm_block_page and assign the path to the blocking page template file in the machine file system starting with the & symbol.

wallarm_cache_path

A directory in which the backup catalog for the proton.db and LOM copy storage is created when the server starts. This directory must be writable for the client that runs NGINX.

This parameter is configured at the HTTP level only.

wallarm_fallback

With the value set to on, NGINX has the ability to enter an emergency mode: if proton.db or LOM cannot be downloaded, this setting disables the Wallarm module for the http, server, and location blocks, for which the data fails to download. NGINX keeps functioning.

This parameter can be set at the levels of http, server, and location.

wallarm_force

Sets the requests analysis and LOM rules generation based on the NGINX mirrored traffic. See Analyzing mirrored traffic with NGINX.

wallarm_global_trainingset_path

A path to the proton.db file that has the global settings for requests filtering, which do not depend on the application structure.

This parameter can be set at the levels of http, server, and location.

Default value: /etc/wallarm/proton.db

wallarm_instance

An application identifier. The directive is used to visually separate the data of different applications on Dashboard. Numeric values only.

The application identifiers are used solely for the convenience of data presentation. To correctly separate the data of different applications, the same application identifiers must be set in the Wallarm interface.

Any filter node will filter traffic for any number of applications without additional configuration.

This parameter can be set at the level of http, server, location.

wallarm_key_path

A path to the Wallarm license key.

Default value: /etc/wallarm/license.key

wallarm_local_trainingset_path

A path to the LOM file that contains information on the protected application and the filter node settings.

This parameter can be set at the levels of http, server, and location.

Default value: /etc/wallarm/lom

wallarm_mode

Traffic processing mode:

  • off: requests are not processed.
  • monitoring: all requests are processed, but none of them is blocked even if an attack is detected.
  • block: all requests where an attack was detected are blocked.
  • aggressive: all non-standard requests are blocked. For example, mapping a string in the field usually used for passing a number. Use this mode with extreme caution.

The value can include variables that are available after receiving a request string and headers. This can be used for applying various policies for various clients:

map $remote_addr $wallarm_mode_real {
    default block;
    1.1.1.1/24 monitoring;
    2.2.2.2 off;
}
...

wallarm_mode $wallarm_mode_real;

You can see the detailed example of filtration mode configuration by proceeding to the link.

This parameter can be set at the level of http, server, location.

Default value: off

Usage of wallarm_mode can be restricted by the wallarm_mode_allow_override directive.

wallarm_mode_allow_override

Manages the ability to override the wallarm_mode values via filtering rules downloaded from the Wallarm cloud (LOM):

  • off: the rules set in LOM are ignored.
  • strict: LOM can only strengthen the operation mode.
  • on: it is possible to both strengthen and soften the operation mode.

For example, with wallarm_mode monitoring and wallarm_mode_allow_override strict set, the Walalrm cloud can be used to enable blocking of some requests, but the attack analysis cannot be fully disabled.

This parameter can be set at the level of http, server, location.

Default value: on

wallarm_parse_response

The mode of processing web server responses; by default, only the client's request to the web server can be processed.

Possible values:

  • on: analysis of web server responses by a passive vulnerability scanner without sending requests from the Wallarm cloud).
  • off: responses are not analyzed.

This parameter can be set at the levels of http, server, and location.

Default value: on


Improve performance

You are recommended to disable processing of static files through location to improve performance.


wallarm_parse_websocket

Wallarm has full WebSockets support. By default, the WebSockets messages are not analyzed for attacks. To force the feature, use the wallarm_parse_websocket directive.

Possible values:

  • on: message analyses is enabled
  • off: message analyses is disabled.

This parameter can be set at the levels of http, server, and location.

Default value: off

wallarm_parser_disable

Allows to disable parsers.

The following parsers are currently supported:

  • cookie
  • zlib
  • htmljs
  • json
  • multipart
  • base64
  • percent
  • urlenc
  • xml

Example

wallarm_parser_disable base64;
wallarm_parser_disable xml;
location /ab {
    wallarm_parser_disable json;
    wallarm_parser_disable base64;
    proxy_pass http://example.com;
}
location /zy {
    wallarm_parser_disable json;
    proxy_pass http://example.com;
}

This parameter can be set at the levels of http, server, and location.

wallarm_process_time_limit

Sets the time limit of a single request processing in milliseconds. If the time exceeds the limit, an error is recorded into the log and the request is marked as an overlimit_res attack. The requests are blocked in the blocking mode (wallarm_mode block;) and ignored in the monitoring mode (wallarm_mode monitoring;).

Default value is 1000ms (one second).

This parameter can be set at the levels of http, server, and location.

wallarm_process_time_limit_block

The ability to manage the blocking of requests, which exceed the time limit set in the wallarm_process_time_limit directive:

  • on: the requests are always blocked
  • off: the requests are always ignored
  • attack: depends on the attack blocking mode set in the wallarm-mode directive:

    • monitoring: the requests are ignored
    • block and aggressive: the requests are blocked

This parameter can be set at the level of http, server, location. Default value: wallarm_process_time_limit_block attack

wallarm_request_memory_limit

Set a limit for the maximum amount of memory that can be used for processing of a single request.

If the limit is exceeded the request processing will be interrupted and a user will get 500 error.

In this parameter, one can use suffixes kKmMgG. Value of 0 turns the limit off.

By default, limits are off.

This parameter can be set in the context of http, server and/or location.

wallarm_proton_log_mask_master

Settings of the debug logging for the master process Nginx.

The parameter can only be configured at the main level.

wallarm_proton_log_mask_worker

Settings of the debug logging for a worker process Nginx.

The parameter can only be configured at the main level.

wallarm_request_chunk_size

Limits the size of the part of the request that is processed during one iteration. You can set up a custom value of the wallarm_request_chunk_size directive in bytes by assigning an integer to it. The directive also supports the following postfixes:

  • k or K for kilobytes
  • m or M for megabytes
  • g or G for gigabytes

This parameter can be set in the context of http, server, and location.

Default value: 8k (8 kilobytes).

wallarm_status

The Wallarm Node status information will be accessible from the corresponding location. Status information can be in json or prometheus format.

Usage:

wallarm_status [on|off] [format=json|prometheus]

This parameter can be set in the context of server and/or location.

The wallarm_status directive lets you set up the server addresses from which the command with the same name can be performed. By default, execution of this command is prohibited everywhere except from the system addresses 127.0.0.1 and ::1 which allows to execute this command on the server where the filter node is installed.

location = /wallarm-status {
    allow 127.0.0.1;
    allow ::1;
    allow 10.41.29.0;
    deny all;
    wallarm_mode off;
    access_log off;
    wallarm_status on;
        }

To allow execution of this command from another server, add the instruction allow with the IP address of that server to the configuration.

For example:

allow 10.41.29.0;

wallarm_set_tag

Defines the key value pair for label each request. A value can contain variables.

Specified tags will be available in postanalytics.

Usage:

wallarm_set_tag somename $var;

This parameter can be set in the context of server and/or location.

wallarm_tarantool_connect_attempts

The number of reconnection attempts to Tarantool. When the specified limit is reached, the reconnection attempts will be paused for the time frame set in the wallarm_tarantool_connect_interval directive.

This parameter is configured at the http level only.

wallarm_tarantool_connect_interval

A delay in reconnecting to Tarantool after a number of failed attempts exceeds the threshold value set in wallarm_tarantool_connect_attempts.

The parameter is configured at the http level only.

wallarm_tarantool_upstream

With the wallarm_tarantool_upstream you can balance the requests between several postanalytics servers.

Example:

     upstream wallarm_tarantool {
        server 127.0.0.1:3313 max_fails=0 fail_timeout=0 max_conns=1;
        keepalive 1;
    }

    ...

    wallarm_tarantool_upstream wallarm_tarantool;

See also Module ngx_http_upstream_module.

Required conditions

It is required that the following conditions are satisfied for the max_conns and the keepalive parameters:

  • The value of the keepalive parameter must not be lower than the number of the tarantool servers.
  • The value of the max_conns parameter must be specified for each of the upstream Tarantool servers to prevent the creation of excessive connections.

The parameter is configured at the http level only.

wallarm_timeslice

A limit on the time that a filter node spends on one iteration of processing a request before it switches to the next request. Upon reaching the time limit, the filter node proceeds to process the next request in the queue. After performing one iteration on each of the requests in the queue, the node performs the second iteration of processing on the first request in the queue.

You can use time intervals suffixes that are described in the nginx documentation to assign different time unit values to the directive.

This parameter can be set in the context of http, server, and location.

Default value: 0 (time limit for single iteration is disabled).


Due to nginx server limitations, it is necessary to disable the request buffering by assigning the off value to the proxy_request_buffering nginx directive for the wallarm_timeslice directive to work.

wallarm_ts_request_memory_limit

Set a limit for the maximum amount of memory that can be used by one instance of proton.db and LOM.

If the memory limit is exceeded while processing of some request, user will get 500 error.

In this parameter, one can use suffixes kKmMgG. Value of 0 turns the limit off.

This parameter can be set in the context of http, server and/or location.

Default value: 1 GB

wallarm_unpack_response

If the backend sends compressed data, the value on decompresses the data before processing. The value off turns off the decompressing.

Default value: on.

wallarm_worker_rlimit_vmem

Deprecated

It is now an alias for wallarm_ts_request_memory_limit directive.

results matching ""

    No results matching ""