Ana içeriğe geç

Docker NGINX‑tabanlı İmajı Çalıştırma

Wallarm NGINX tabanlı filtreleme düğümü bir Docker imajı kullanılarak dağıtılabilir. Bu düğüm hem x86_64 hem de ARM64 mimarilerini destekler ve kurulum sırasında otomatik olarak belirlenir. Bu makale, inline trafik filtreleme için düğümün Docker imajından nasıl çalıştırılacağını açıklar.

Docker imajı Alpine Linux’a ve Alpine’in sağladığı NGINX sürümüne dayanır. Şu anda en güncel imaj, NGINX stable 1.28.0 içeren Alpine Linux 3.22 sürümünü kullanır.

Kullanım senaryoları

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.

Gereksinimler

  • 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 and their corresponding hostnames (if any) listed below. This is needed 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

    node-data0.us1.wallarm.com - 34.96.64.17
    node-data1.us1.wallarm.com - 34.110.183.149
    us1.api.wallarm.com - 35.235.66.155
    34.102.90.100
    34.94.156.115
    35.235.115.105
    
    node-data1.eu1.wallarm.com - 34.160.38.183
    node-data0.eu1.wallarm.com - 34.144.227.90
    api.wallarm.com - 34.90.110.226
    

Konteyneri çalıştırma seçenekleri

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.

Ortam değişkenlerini geçirerek konteyneri çalıştırma

Konteyneri çalıştırmak için:

  1. Get Wallarm token of the appropriate type:

    1. Open Wallarm Console → SettingsAPI 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.
  2. Düğüm ile konteyneri çalıştırın:

    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:6.5.1
    
    docker run -d -e WALLARM_API_TOKEN='XXXXXXX' -e WALLARM_LABELS='group=<GROUP>' -e NGINX_BACKEND='example.com' -p 80:80 wallarm/node:6.5.1
    

Aşağıdaki temel filtreleme düğümü ayarlarını -e seçeneği ile konteynere iletebilirsiniz:

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) 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
APIFW_METRICS_ENABLED (6.4.1 and higher) Enables Prometheus metrics for the API Specification Enforcement module.
By default: false (disabled).
No
APIFW_METRICS_HOST (6.4.1 and higher) Defines the host and port on which the API Specification Enforcement exposes metrics.
By default: :9010.
No
APIFW_METRICS_ENDPOINT_NAME (6.4.1 and higher) Defines the HTTP path of the API Specification Enforcement metrics endpoint
By default: metrics.
No
WALLARM_WSTORE__METRICS__LISTEN_ADDRESS Defines the host and port on which Postanalytics and general system metrics are exposed.
By default: http://localhost:9001/metrics.
No
WALLARM_WSTORE__SERVICE__PROTOCOL (6.6.0 and higher) Specifies the protocol family that wstore uses for incoming connections. Possible values:
  • "tcp" - dual-stack mode (listens on both IPv4 and IPv6)
  • "tcp4" - IPv4 only
  • "tcp6" - IPv6 only
By default: "tcp4".
No

Komut şunları yapar:

  • /etc/nginx/http.d konteyner dizininde minimal NGINX yapılandırmasına sahip default.conf dosyasını oluşturur ve filtreleme düğümü yapılandırmasını iletir.

  • Wallarm Cloud’a erişim için filtreleme düğümü kimlik bilgilerini içeren dosyaları /opt/wallarm/etc/wallarm konteyner dizininde oluşturur:

    • Filtreleme düğümü UUID’si ve gizli anahtarıyla node.yaml
    • Wallarm özel anahtarını içeren private.key
  • http://NGINX_BACKEND:80 kaynağını korur.

Yapılandırma dosyasını bağlayarak konteyneri çalıştırma

Hazırlanmış yapılandırma dosyasını -v seçeneğiyle Docker konteynerine bağlayabilirsiniz. Dosya aşağıdaki ayarları içermelidir:

Konteyneri çalıştırmak için:

  1. Get Wallarm token of the appropriate type:

    1. Open Wallarm Console → SettingsAPI 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.
  2. Düğüm ile konteyneri çalıştırın:

    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/http.d/default.conf -p 80:80 wallarm/node:6.5.1
    
    docker run -d -e WALLARM_API_TOKEN='XXXXXXX' -e WALLARM_LABELS='group=<GROUP>' -v /configs/default:/etc/nginx/http.d/default.conf -p 80:80 wallarm/node:6.5.1
    
    • -e seçeneği, aşağıdaki zorunlu ortam değişkenlerini konteynere iletir:

      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) 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
      APIFW_METRICS_ENABLED (6.4.1 and higher) Enables Prometheus metrics for the API Specification Enforcement module.
      By default: false (disabled).
      No
      APIFW_METRICS_HOST (6.4.1 and higher) Defines the host and port on which the API Specification Enforcement exposes metrics.
      By default: :9010.
      No
      APIFW_METRICS_ENDPOINT_NAME (6.4.1 and higher) Defines the HTTP path of the API Specification Enforcement metrics endpoint
      By default: metrics.
      No
      WALLARM_WSTORE__SERVICE__PROTOCOL (6.6.0 and higher) Specifies the protocol family that wstore uses for incoming connections. Possible values:
      • "tcp" - dual-stack mode (listens on both IPv4 and IPv6)
      • "tcp4" - IPv4 only
      • "tcp6" - IPv6 only
      By default: "tcp4".
      No
    • -v seçeneği, default.conf yapılandırma dosyasını içeren dizini /etc/nginx/http.d konteyner dizinine bağlar.

      Örnek /etc/nginx/http.d/default.conf minimal içeriği için bakın
      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;
              }
      }
      
      Diğer yapılandırma dosyalarını bağlama

      NGINX tarafından kullanılan konteyner dizinleri:

      • /etc/nginx/nginx.conf - Bu, ana NGINX yapılandırma dosyasıdır. Bu dosyayı bağlamaya karar verirseniz, Wallarm’ın düzgün çalışması için ek adımlar gereklidir:

        1. nginx.conf dosyasında, en üst düzeye aşağıdaki ayarı ekleyin:

          include /etc/nginx/modules/*.conf;
          
        2. nginx.conf içinde, http bloğuna wallarm_srv_include /etc/nginx/wallarm-apifw-loc.conf; yönergesini ekleyin. Bu, API Spesifikasyonu Zorlaması için yapılandırma dosyasının yolunu belirtir.

        3. wallarm-apifw-loc.conf dosyasını belirtilen yola bağlayın. İçeriği şu şekilde olmalıdır:

          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.8/8;
                  deny all;
          }
          
          location @wallarm-apifw-fallback {
                  wallarm_mode off;
                  return 500 "API FW fallback";
          }
          
        4. Aşağıdaki içerikle /etc/nginx/conf.d/wallarm-status.conf dosyasını bağlayın. Sağlanan yapılandırmadaki herhangi bir satırı değiştirmemek kritik önemdedir; aksi halde düğüm metriklerinin Wallarm Cloud’a başarılı şekilde yüklenmesini engelleyebilir.

          server {
            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;
            }
          }
          
        5. NGINX yapılandırma dosyanız içinde, /wallarm-status uç noktası için aşağıdaki yapılandırmayı oluşturun:

          location /wallarm-status {
              # İzin verilen adresler, WALLARM_STATUS_ALLOW değişkeninin değeriyle eşleşmelidir
              allow xxx.xxx.x.xxx;
              allow yyy.yyy.y.yyy;
              deny all;
              wallarm_status on format=prometheus;
              wallarm_mode off;
          }
          
      • /etc/nginx/conf.d — genel ayarlar

      • /etc/nginx/http.d — sanal ana bilgisayar ayarları
      • /opt/wallarm/usr/share/nginx/html — statik dosyalar

      Gerekirse, listelenen konteyner dizinlerine herhangi bir dosyayı bağlayabilirsiniz. Filtreleme düğümü yönergeleri /etc/nginx/http.d/default.conf dosyasında tanımlanmalıdır.

Komut şunları yapar:

  • default.conf dosyasını /etc/nginx/http.d konteyner dizinine bağlar.

  • Wallarm Cloud’a erişim için filtreleme düğümü kimlik bilgilerini içeren dosyaları /opt/wallarm/etc/wallarm konteyner dizininde oluşturur:

    • Filtreleme düğümü UUID’si ve gizli anahtarıyla node.yaml
    • Wallarm özel anahtarını içeren private.key
  • http://example.com kaynağını korur.

Günlükleme yapılandırması

Günlükleme varsayılan olarak etkindir. Günlük dizinleri şunlardır:

Wallarm düğümünün çalışmasını test etme

  1. 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.

  2. Open Wallarm Console → Attacks section in the US Cloud or EU Cloud and make sure the attack is displayed in the list.

    Attacks in the interface

  3. Optionally, [test][link-wallarm-health-check] other aspects of the node functioning.

Kullanım senaryolarını yapılandırma

Docker konteynerine bağlanan yapılandırma dosyası, filtreleme düğümü yapılandırmasını mevcut yönergelerde tanımlamalıdır. Aşağıda yaygın olarak kullanılan bazı filtreleme düğümü yapılandırma seçenekleri verilmiştir: