Docker NGINXベースイメージの実行¶

WallarmのNGINXベースのフィルタリングノードはDockerイメージを使用してデプロイできます。このノードはx86_64アーキテクチャとARM64アーキテクチャの両方をサポートしており、インストール中に自動で識別されます。本記事はDockerイメージからのノード実行方法について説明します。

DockerイメージはAlpine LinuxとAlpineが提供するNGINXバージョンをベースにしています。現在、最新のイメージはAlpine Linuxバージョン3.20を使用し、NGINX stable 1.26.2が含まれています。

利用事例¶

Among all supported Wallarm deployment options, NGINX-based Docker image is recommended for Wallarm deployment in these use cases:

If your organization utilizes Docker-based infrastructure, Wallarm Docker image is the ideal choice. It integrates effortlessly into your existing setup, whether you are employing a microservice architecture running on AWS ECS, Alibaba ECS, or other similar services. This solution also applies to those using virtual machines seeking a more streamlined management through Docker containers.
If you require fine-grained control over each container, the Docker image excels. It affords a greater level of resource isolation than typically possible with traditional VM-based deployments.

For more information on running Wallarm's NGINX-based Docker image on popular public cloud container orchestration services, refer to our guides: AWS ECS, GCP GCE, Azure Container Instances, Alibaba ECS.

必要条件¶

Docker installed on your host system
Access to https://hub.docker.com/r/wallarm/node to download the Docker image. Please ensure the access is not blocked by a firewall
Access to the account with the Administrator role in Wallarm Console in the US Cloud or EU Cloud
Access to https://us1.api.wallarm.com if working with US Wallarm Cloud or to https://api.wallarm.com if working with EU Wallarm Cloud. Please ensure the access is not blocked by a firewall
Access to the IP addresses below for downloading updates to attack detection rules and API specifications, as well as retrieving precise IPs for your allowlisted, denylisted, or graylisted countries, regions, or data centers
US CloudEU Cloud
34.96.64.17 34.110.183.149 35.235.66.155 34.102.90.100 34.94.156.115 35.235.115.105
34.160.38.183 34.144.227.90 34.90.110.226

コンテナ実行時のオプション¶

The filtering node configuration parameters should be passed to the deployed Docker container in one of the following ways:

In the environment variables. This option allows for the configuration of only basic filtering node parameters. Most directives cannot be configured through environment variables.
In the mounted configuration file. This option allows full filtering node configuration via any directives. With this configuration method, environment variables with the filtering node and Wallarm Cloud connection settings are also passed to the container.

環境変数を渡してコンテナを実行¶

以下の手順でコンテナを実行します。

Get Wallarm token of the appropriate type:
API tokenNode token
1. Open Wallarm Console → Settings → API tokens in the US Cloud or EU Cloud.
2. Find or create API token with the Node deployment/Deployment usage type.
3. Copy this token.
1. Open Wallarm Console → Nodes in the US Cloud or EU Cloud.
2. Do one of the following:
  
  Create the node of the Wallarm node type and copy the generated token.
  
  Use existing node group - copy token using node's menu → Copy token.

ノード付きでコンテナを実行:

US CloudEU Cloud

docker run -d -e WALLARM_API_TOKEN='XXXXXXX' -e WALLARM_LABELS='group=<GROUP>' -e NGINX_BACKEND='example.com' -e WALLARM_API_HOST='us1.api.wallarm.com' -p 80:80 wallarm/node:5.3.0

docker run -d -e WALLARM_API_TOKEN='XXXXXXX' -e WALLARM_LABELS='group=<GROUP>' -e NGINX_BACKEND='example.com' -p 80:80 wallarm/node:5.3.0

以下の基本的なフィルタリングノード設定を-eオプションでコンテナに渡せます:

Environment variable	Description	Required
`WALLARM_API_TOKEN`	Wallarm node or API token.	Yes
`WALLARM_LABELS`	Available starting from node 4.6. Works only if `WALLARM_API_TOKEN` is set to API token with the `Deploy` role. Sets the `group` label for node instance grouping, for example: `WALLARM_LABELS="group=<GROUP>"` ...will place node instance into the `<GROUP>` instance group (existing, or, if does not exist, it will be created).	Yes (for API tokens)
`NGINX_BACKEND`	Domain or IP address of the resource to protect with the Wallarm solution.	Yes
`WALLARM_API_HOST`	Wallarm API server: `us1.api.wallarm.com` for the US Cloud `api.wallarm.com` for the EU Cloud By default: `api.wallarm.com`.	No
`WALLARM_MODE`	Node mode: `block` to block malicious requests `safe_blocking` to block only those malicious requests originated from graylisted IP addresses `monitoring` to analyze but not block requests `off` to disable traffic analyzing and processing By default: `monitoring`. Detailed description of filtration modes →	No
`WALLARM_APPLICATION`	Unique identifier of the protected application to be used in the Wallarm Cloud. The value can be a positive integer except for `0`. Default value (if the variable is not passed to the container) is `-1` which indicates the default application displayed in Wallarm Console → Settings → Application. More details on setting up applications →	No
`SLAB_ALLOC_ARENA` (`TARANTOOL_MEMORY_GB` [NGINX Node 5.x and earlier][what-is-new-wstore])	Amount of memory allocated to wstore. The value can be a float (a dot `.` is a decimal separator). By default: 1.0 (1 gygabyte).	No
`NGINX_PORT`	Sets a port that NGINX will use inside the Docker container. Starting from the Docker image `4.0.2-1`, the `wallarm-status` service automatically runs on the same port as NGINX. Default value (if the variable is not passed to the container) is `80`. Syntax is `NGINX_PORT='443'`.	No
`WALLARM_STATUS_ALLOW`	Custom CIDRs that are allowed to access the `/wallarm-status` endpoint from outside the Docker container. Example value: `10.0.0.0/8`. If you need to pass several values, use a comma `,` as a separator. To access the service externally, use the Docker container's IP, specifying the `/wallarm-status` endpoint path.	No
`DISABLE_IPV6`	The variable with any value except for an empty one deletes the `listen [::]:80 default_server ipv6only=on;` line from the NGINX configuration file which will stop NGINX from IPv6 connection processing. If the variable is not specified explicitly or has an empty value `""`, NGINX processes both IPv6 and IPv4 connections.	No
`WALLARM_APIFW_ENABLE`	This setting toggles API Specification Enforcement on or off, available from release 4.10 onwards. Please note that activating this feature does not substitute for the required subscription and configuration through the Wallarm Console UI. Its default value is `true`, enabling the functionality.	No
`WALLARM_APID_ONLY` (5.3.7 and higher)	In this mode, attacks detected in your traffic are blocked locally by the node (if enabled) but not exported to Wallarm Cloud. Meanwhile, API Discovery and some other features remain fully functional, detecting your API inventory and uploading it to the Cloud for visualization. This mode is for those who want to review their API inventory and identify sensitive data first, and plan controlled attack data export accordingly. However, disabling attack export is rare, as Wallarm securely processes attack data and provides sensitive attack data masking if needed. More details By default: `false`.	No

このコマンドは以下を実行します:

最小限のNGINX設定を含むdefaultファイルを作成し、フィルタリングノードの設定をコンテナ内の/etc/nginx/sites-enabledディレクトリに渡します。
Wallarm Cloudにアクセスするためのフィルタリングノードの認証情報ファイルをコンテナ内の/opt/wallarm/etc/wallarmディレクトリに作成します:
- フィルタリングノードUUIDとシークレットキーを含むnode.yaml
- Wallarmの秘密鍵を含むprivate.key
リソースhttp://NGINX_BACKEND:80を保護します。

設定ファイルをマウントしてコンテナを実行¶

事前に作成した設定ファイルを-vオプションでDockerコンテナにマウントできます。ファイルには以下の設定が含まれている必要があります:

以下の手順でコンテナを実行します:

Get Wallarm token of the appropriate type:
API tokenNode token
1. Open Wallarm Console → Settings → API tokens in the US Cloud or EU Cloud.
2. Find or create API token with the Node deployment/Deployment usage type.
3. Copy this token.
1. Open Wallarm Console → Nodes in the US Cloud or EU Cloud.
2. Do one of the following:
  
  Create the node of the Wallarm node type and copy the generated token.
  
  Use existing node group - copy token using node's menu → Copy token.

ノード付きでコンテナを実行:

US CloudEU Cloud

docker run -d -e WALLARM_API_TOKEN='XXXXXXX' -e WALLARM_LABELS='group=<GROUP>' -e WALLARM_API_HOST='us1.api.wallarm.com' -v /configs/default:/etc/nginx/sites-enabled/default -p 80:80 wallarm/node:5.3.0

docker run -d -e WALLARM_API_TOKEN='XXXXXXX' -e WALLARM_LABELS='group=<GROUP>' -v /configs/default:/etc/nginx/sites-enabled/default -p 80:80 wallarm/node:5.3.0

-eオプションはコンテナに以下の必須環境変数を渡します:

Environment variable	Description	Required
`WALLARM_API_TOKEN`	Wallarm node or API token.	Yes
`WALLARM_API_HOST`	Wallarm API server: `us1.api.wallarm.com` for the US Cloud `api.wallarm.com` for the EU Cloud By default: `api.wallarm.com`.	No
`WALLARM_LABELS`	Available starting from node 4.6. Works only if `WALLARM_API_TOKEN` is set to API token with the `Deploy` role. Sets the `group` label for node instance grouping, for example: `WALLARM_LABELS="group=<GROUP>"` ...will place node instance into the `<GROUP>` instance group (existing, or, if does not exist, it will be created).	Yes (for API tokens)
`SLAB_ALLOC_ARENA` (`TARANTOOL_MEMORY_GB` [NGINX Node 5.x and earlier][what-is-new-wstore])	Amount of memory allocated to wstore. The value can be a float (a dot `.` is a decimal separator). By default: 1.0 (1 gygabyte).	No
`WALLARM_APID_ONLY` (5.3.7 and higher)	In this mode, attacks detected in your traffic are blocked locally by the node (if enabled) but not exported to Wallarm Cloud. Meanwhile, API Discovery and some other features remain fully functional, detecting your API inventory and uploading it to the Cloud for visualization. This mode is for those who want to review their API inventory and identify sensitive data first, and plan controlled attack data export accordingly. However, disabling attack export is rare, as Wallarm securely processes attack data and provides sensitive attack data masking if needed. More details By default: `false`.	No

-vオプションは設定ファイルdefaultが配置されたディレクトリをコンテナ内の/etc/nginx/sites-enabledディレクトリにマウントします。

例 /etc/nginx/sites-enabled 最小限の内容を参照

server {
        listen 80 default_server;
        listen [::]:80 default_server ipv6only=on;
        #listen 443 ssl;

        server_name localhost;

        #ssl_certificate cert.pem;
        #ssl_certificate_key cert.key;

        root /usr/share/nginx/html;

        index index.html index.htm;

        wallarm_mode monitoring;

        location / {

                proxy_pass http://example.com;
                include proxy_params;
        }
}

他の設定ファイルのマウント

NGINXが使用するコンテナ内ディレクトリ:

/etc/nginx/nginx.conf - メインのNGINX設定ファイルです。このファイルをマウントする場合、Wallarmの正常な動作のために追加の手順が必要です:

nginx.confのトップレベルに以下の設定を追加します:
```
include /etc/nginx/modules-enabled/*.conf;
```
nginx.confのhttpブロック内にwallarm_srv_include /etc/nginx/wallarm-apifw-loc.conf;ディレクティブを追加します。これはAPI Specification Enforcementの設定ファイルへのパスを指定します。

wallarm-apifw-loc.confファイルを指定パスにマウントします。内容は以下のとおりです:

location ~ ^/wallarm-apifw(.*)$ {
        wallarm_mode off;
        proxy_pass http://127.0.0.1:8088$1;
        error_page 404 431         = @wallarm-apifw-fallback;
        error_page 500 502 503 504 = @wallarm-apifw-fallback;
        allow 127.0.0.0/8;
        deny all;
}

location @wallarm-apifw-fallback {
        wallarm_mode off;
        return 500 "API FW fallback";
}

/etc/nginx/conf.d/wallarm-status.confファイルを以下の内容でマウントします。ノードメトリクスをWallarm Cloudに正しくアップロードするため、提供された設定のいずれの行も変更しないことが重要です。

server {
  # ポートはNGINX_PORT変数の値と一致する必要があります
  listen 127.0.0.8:80;

  server_name localhost;

  allow 127.0.0.0/8;
  deny all;

  wallarm_mode off;
  disable_acl "on";
  wallarm_enable_apifw off;
  access_log off;

  location ~/wallarm-status$ {
    wallarm_status on;
  }
}

NGINX設定ファイル内で、/wallarm-statusエンドポイントに以下の設定を行います:

location /wallarm-status {
    # 許可するアドレスはWALLARM_STATUS_ALLOW変数の値と一致する必要があります
    allow xxx.xxx.x.xxx;
    allow yyy.yyy.y.yyy;
    deny all;
    wallarm_status on format=prometheus;
    wallarm_mode off;
}

/etc/nginx/conf.d — 共通の設定
/etc/nginx/sites-enabled — バーチャルホストの設定
/opt/wallarm/usr/share/nginx/html — 静的ファイル

必要に応じて、上記のコンテナ内ディレクトリに任意のファイルをマウントできます。フィルタリングノードディレクティブは/etc/nginx/sites-enabled/defaultファイルに記述する必要があります。

このコマンドは以下を実行します:

ファイルdefaultをコンテナ内の/etc/nginx/sites-enabledディレクトリにマウントします。
Wallarm Cloudにアクセスするためのフィルタリングノード認証情報ファイルをコンテナ内の/opt/wallarm/etc/wallarmディレクトリに作成します:
- フィルタリングノードUUIDとシークレットキーを含むnode.yaml
- Wallarmの秘密鍵を含むprivate.key
リソースhttp://example.comを保護します。

ログ設定¶

ログはデフォルトで有効になっています。ログディレクトリは以下のとおりです:

/var/log/nginx — NGINXログ
/opt/wallarm/var/log/wallarm — Wallarmノードログ

Wallarmノード動作のテスト¶

Send the request with test Path Traversal attack to a protected resource address:
```
curl http://localhost/etc/passwd
```
If traffic is configured to be proxied to example.com, include the -H "Host: example.com" header in the request.
Open Wallarm Console → Attacks section in the US Cloud or EU Cloud and make sure the attack is displayed in the list.
Optionally, [test][link-wallarm-health-check] other aspects of the node functioning.

利用事例の構成¶

Dockerコンテナにマウントされる設定ファイルには、利用可能なディレクティブに記載のフィルタリングノード構成を示す必要があります。以下は一般的に使用されるフィルタリングノード構成オプションの例です: