Skip to content

Deployment of the WAF node Docker image to AWS

This quick guide provides the steps to deploy the Docker image of the NGINX-based WAF node to the Amazon cloud platform using the Amazon Elastic Container Service (Amazon ECS).

The instructions limitations

These instructions do not cover the configuration of load balancing and WAF node autoscaling. If setting up these components yourself, we recommend that you review an appropriate part of the AWS instructions.

Requirements

  • AWS account and user with the admin permissions

  • AWS CLI 1 or AWS CLI 2 properly installed and configured

  • Access to the account with the Administrator or Deploy role and two‑factor authentication disabled in the Wallarm Console for the EU Cloud or US Cloud

Options for the WAF node Docker container configuration

The WAF 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 WAF node parameters. Most directives cannot be configured through environment variables.

  • In the mounted configuration file. This option allows full WAF node configuration via any directives. With this configuration method, environment variables with the WAF node and Wallarm Cloud connection settings are also passed to the container.

Deploying the WAF node Docker container configured through environment variables

To deploy the containerized WAF node configured only through environment variables, the AWS Management Console and AWS CLI are used.

  1. Sign in to the AWS Management Console → the Services list → Elastic Container Service.

  2. Proceed to cluster creation by the button Create Cluster:

    1. Select the template EC2 Linux + Networking.
    2. Specify the cluster name, for example: waf-cluster.
    3. If required, set other settings following the AWS instructions.
    4. Save the cluster.
  3. Save the sensitive data used for the WAF node and Wallarm Cloud connection setup in the AWS Secrets Manager or AWS Systems Manager → Parameter Store. Sensitive data includes the following environment variables:

    • <DEPLOY_USER>: email to the Deploy or Administrator user account in the Wallarm Console.
    • <DEPLOY_PASSWORD>: password to the Deploy or Administrator user account in the Wallarm Console.

    In these instructions, sensitive data is stored in the AWS Secrets Manager.

    Access to the sensitive data storage

    To allow the Docker container to read the encrypted sensitive data, please ensure the AWS settings meet the following requirements:

    • Sensitive data is stored in the region used to run the Docker container.
    • The IAM policy SecretsManagerReadWrite is attached to the user specified in the executionRoleArn parameter of the task definition. More details on the IAM policies setup →
  4. Create the following local JSON file with the task definition (task definition sets the Docker container operating scenario):

    {
        "executionRoleArn": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/ecsTaskExecutionRole",
        "containerDefinitions": [
            {
                "memory": 128,
                "portMappings": [
               {
                   "hostPort": 80,
                   "containerPort": 80,
                   "protocol": "tcp"
               }
           ],
           "essential": true,
           "environment": [
               {
                   "name": "NGINX_BACKEND",
                   "value": "<HOST_TO_PROTECT_WITH_WAF>"
               }
           ],
           "secrets": [
               {
                   "name": "DEPLOY_PASSWORD",
                   "valueFrom": "arn:aws:secretsmanager:<SECRETS_MANAGER_AWS_REGION>:<AWS_ACCOUNT_ID>:secret:<SECRET_NAME>:<DEPLOY_PASSWORD_PARAMETER_NAME>::"
               },
               {
                   "name": "DEPLOY_USER",
                   "valueFrom": "arn:aws:secretsmanager:<SECRETS_MANAGER_AWS_REGION>:<AWS_ACCOUNT_ID>:secret:<SECRET_NAME>:<DEPLOY_USER_PARAMETER_NAME>::"
               }
           ],
           "name": "waf-container",
           "image": "registry-1.docker.io/wallarm/node:2.18.1-3"
           }
       ],
       "family": "wallarm-waf-node"
       }
    
    {
        "executionRoleArn": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/ecsTaskExecutionRole",
        "containerDefinitions": [
            {
                "memory": 128,
                "portMappings": [
               {
                   "hostPort": 80,
                   "containerPort": 80,
                   "protocol": "tcp"
               }
           ],
           "essential": true,
           "environment": [
               {
                   "name": "WALLARM_API_HOST",
                   "value": "us1.api.wallarm.com"
               },
               {
                   "name": "NGINX_BACKEND",
                   "value": "<HOST_TO_PROTECT_WITH_WAF>"
               }
           ],
           "secrets": [
               {
                   "name": "DEPLOY_PASSWORD",
                   "valueFrom": "arn:aws:secretsmanager:<SECRETS_MANAGER_AWS_REGION>:<AWS_ACCOUNT_ID>:secret:<SECRET_NAME>:<DEPLOY_PASSWORD_PARAMETER_NAME>::"
               },
               {
                   "name": "DEPLOY_USER",
                   "valueFrom": "arn:aws:secretsmanager:<SECRETS_MANAGER_AWS_REGION>:<AWS_ACCOUNT_ID>:secret:<SECRET_NAME>:<DEPLOY_USER_PARAMETER_NAME>::"
               }
           ],
           "name": "waf-container",
           "image": "registry-1.docker.io/wallarm/node:2.18.1-3"
           }
       ],
       "family": "wallarm-waf-node"
       }
    
    • <AWS_ACCOUNT_ID>: your AWS account ID.
    • The environment object sets the environment variables that should be passed to the Docker container in a text format. The set of available environment variables is described in the table below. It is recommended to pass the variables DEPLOY_USER and DEPLOY_PASSWORD in the secrets object.
    • The secret object sets the environment variables that should be passed to the Docker container as the links to the sensitive data storage. The format of values depends on the selected storage (see more details in the AWS Secrets Manager or AWS Systems Manager → Parameter Store documentation).

      It is recommended to pass the variables DEPLOY_USER and DEPLOY_PASSWORD in the secrets object.

      Environment variable Description Required
      DEPLOY_USER Email to the Deploy or Administrator user account in the Wallarm Console. Yes
      DEPLOY_PASSWORD Password to the Deploy or Administrator user account in the Wallarm Console. Yes
      NGINX_BACKEND Domain or IP address of the resource to protect with WAF. Yes
      WALLARM_API_HOST Wallarm API server:
      • api.wallarm.com for the EU Cloud
      • us1.api.wallarm.com for the US Cloud
      By default: api.wallarm.com.
      No
      WALLARM_MODE WAF node mode:
      • block to block malicious requests
      • monitoring to analyze but not block requests
      • off to disable traffic analyzing and processing
      By default: monitoring.
      No
      TARANTOOL_MEMORY_GB Amount of memory allocated to Tarantool. The value can be an integer or a float (a dot . is a decimal separator). By default: 0.2 gygabytes. No
      WALLARM_ACL_ENABLE Enables the IP blocking functionality with default settings. The following values can be assigned to a variable:
      • true to enable the IP blocking functionality
      • false to disable the IP blocking functionality
      Default value (if the variable is not passed to the container) is false.
      To enable the IP blocking functionality with custom settings, you need to define appropriate NGINX directives and run the container mounting the configuration file with defined directives.

      Values on / enabled / ok / yes

      Since version 2.16.0-8 of the WAF node image, the values on / enabled / ok / yes assigned to this variable disable the IP blocking functionality. We recommend deploying the latest image version as described in the current document and passing the value true or false in this variable.

      No
      DEPLOY_FORCE Replaces an existing WAF node with a new one if an existing WAF node name matches the identifier of the container you are running. The following values can be assigned to a variable:
      • true to replace the WAF node
      • false to disable the replacement of the WAF node
      Default value (if the variable is not passed to the container) is false.
      The WAF node name always matches the identifier of the container you are running. WAF node replacement is helpful if the Docker container identifiers in your environment are static and you are trying to run another Docker container with the WAF node (for example, a container with a new version of the image). If in this case the variable value is false, the WAF node creation process will fail.
      No
    • All configuration file parameters are described in the AWS documentation.

  5. Register the task definition based on the JSON configuration file by using the aws ecs register‑task‑definition command:

    aws ecs register-task-definition --cli-input-json file://<PATH_TO_JSON_FILE>/<JSON_FILE_NAME>
    
    • <PATH_TO_JSON_FILE>: path to the JSON file with the task definition on the local machine.
    • <JSON_FILE_NAME>: name and extension of the JSON file with the task definition.
  6. Run the task in the cluster by using the aws ecs run-task command:

    aws ecs run-task --cluster <CLUSTER_NAME> --launch-type EC2 --task-definition <FAMILY_PARAM_VALUE>
    
    • <CLUSTER_NAME>: name of the cluster created in the first step. For example, waf-cluster.
    • <FAMILY_PARAM_VALUE>: name of the created task definition. The value should correspond to the family parameter value specified in the JSON file with the task definition. For example, wallarm-waf-node.
  7. Open the AWS Management Console → Elastic Container Service → cluster with the running task → Tasks and ensure the task is displayed in the list.

  8. Test the WAF node operation.

Deploying the WAF node Docker container configured through the mounted file

To deploy the containerized WAF node configured through environment variables and mounted file, the AWS Management Console and AWS CLI are used.

In these instructions, the configuration file is mounted from the AWS EFS file system. You can review other methods for mounting the file in the AWS documentation.

To deploy the container with environment variables and configuration file mounted from AWS EFS:

  1. Sign in to the AWS Management Console → the Services list → Elastic Container Service.

  2. Proceed to cluster creation by the button Create Cluster:

    • Template: EC2 Linux + Networking.
    • Cluster name: waf-cluster (as an example).
    • Provisioning Model: On-Demand Instance.
    • EC2 instance type: t2.micro.
    • Number of instances: 1.
    • EC2 AMI ID: Amazon Linux 2 Amazon ECS-optimized AMI.
    • Key pair: key pair for SSH connection to the instance. You will need to connect to the instance via SSH to upload the configuration file to the storage.
    • Other settings can be left as default. When changing other settings, it is recommended to follow the instructions on AWS EFS setup.
  3. Configure the AWS EFS storage following steps 2-4 of the AWS instructions.

  4. In the 4th step of AWS instructions, create the configuration file default and place the file in the directory that stores the files for mounting by default. The file default should cover the WAF node configuration. An example of the file with minimal settings:

    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;
        # wallarm_instance 1;
        # wallarm_acl default;
    
        location / {
                proxy_pass http://example.com;
                include proxy_params;
        }
    }
    

    Set of WAF node directives that can be specified in the configuration file →

  5. Save the sensitive data used for the WAF node and Wallarm Cloud connection setup in the AWS Secrets Manager or AWS Systems Manager → Parameter Store. Sensitive data includes the following environment variables:

    • <DEPLOY_USER>: email to the Deploy or Administrator user account in the Wallarm Console.
    • <DEPLOY_PASSWORD>: password to the Deploy or Administrator user account in the Wallarm Console.

    In these instructions, sensitive data is stored in the AWS Secrets Manager.

    Access to the sensitive data storage

    To allow the Docker container to read the encrypted sensitive data, please ensure the AWS settings meet the following requirements:

    • Sensitive data is stored in the region used to run the Docker container.
    • The IAM policy SecretsManagerReadWrite is attached to the user specified in the executionRoleArn parameter of the task definition. More details on the IAM policies setup →
  6. Create the following local JSON file with the task definition (task definition sets the Docker container operating scenario):

    {
        "executionRoleArn": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/ecsTaskExecutionRole",
        "containerDefinitions": [
            {
                "memory": 128,
                "portMappings": [
               {
                   "hostPort": 80,
                   "containerPort": 80,
                   "protocol": "tcp"
               }
           ],
           "essential": true,
           "mountPoints": [
               {
                   "containerPath": "/etc/nginx/sites-enabled",
                   "sourceVolume": "default"
               }
           ],
           "secrets": [
               {
                   "name": "DEPLOY_PASSWORD",
                   "valueFrom": "arn:aws:secretsmanager:<SECRETS_MANAGER_AWS_REGION>:<AWS_ACCOUNT_ID>:secret:<SECRET_NAME>:<DEPLOY_PASSWORD_PARAMETER_NAME>::"
               },
               {
                   "name": "DEPLOY_USER",
                   "valueFrom": "arn:aws:secretsmanager:<SECRETS_MANAGER_AWS_REGION>:<AWS_ACCOUNT_ID>:secret:<SECRET_NAME>:<DEPLOY_USER_PARAMETER_NAME>::"
               }
           ],
           "name": "waf-container",
           "image": "registry-1.docker.io/wallarm/node:2.18.1-3"
           }
       ],
       "volumes": [
           {
               "name": "default",
               "efsVolumeConfiguration": {
                   "fileSystemId": "<EFS_FILE_SYSTEM_ID>",
                   "transitEncryption": "ENABLED"
               }
           }
       ],
       "family": "wallarm-waf-node"
       }
    
    {
        "executionRoleArn": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/ecsTaskExecutionRole",
        "containerDefinitions": [
            {
                "memory": 128,
                "portMappings": [
               {
                   "hostPort": 80,
                   "containerPort": 80,
                   "protocol": "tcp"
               }
           ],
           "essential": true,
           "mountPoints": [
               {
                   "containerPath": "<PATH_FOR_MOUNTED_CONFIG>",
                   "sourceVolume": "<NAME_FROM_VOLUMES_OBJECT>"
               }
           ],
           "environment": [
               {
                   "name": "WALLARM_API_HOST",
                   "value": "us1.api.wallarm.com"
               }
           ],
           "secrets": [
               {
                   "name": "DEPLOY_PASSWORD",
                   "valueFrom": "arn:aws:secretsmanager:<SECRETS_MANAGER_AWS_REGION>:<AWS_ACCOUNT_ID>:secret:<SECRET_NAME>:<DEPLOY_PASSWORD_PARAMETER_NAME>::"
               },
               {
                   "name": "DEPLOY_USER",
                   "valueFrom": "arn:aws:secretsmanager:<SECRETS_MANAGER_AWS_REGION>:<AWS_ACCOUNT_ID>:secret:<SECRET_NAME>:<DEPLOY_USER_PARAMETER_NAME>::"
               }
           ],
           "name": "waf-container",
           "image": "registry-1.docker.io/wallarm/node:2.18.1-3"
           }
       ],
       "volumes": [
           {
               "name": "<VOLUME_NAME>",
               "efsVolumeConfiguration": {
                   "fileSystemId": "<EFS_FILE_SYSTEM_ID>",
                   "transitEncryption": "ENABLED"
               }
           }
       ],
       "family": "wallarm-waf-node"
       }
    
    • <AWS_ACCOUNT_ID>: your AWS account ID.
    • <PATH_FOR_MOUNTED_CONFIG>: directory of the container to mount the configuration file to. Configuration files can be mounted to the following container directories used by NGINX:

      • /etc/nginx/conf.d — common settings
      • /etc/nginx/sites-enabled — virtual host settings
      • /var/www/html — static files

      The WAF node directives should be described in the /etc/nginx/sites-enabled/default file.

    • <NAME_FROM_VOLUMES_OBJECT>: name of the volumes object containing the configuration of the mounted file AWS EFS storage (the value should be the same as <VOLUME_NAME>).

    • <VOLUME_NAME>: name of the volumes object that contains the configuration of the mounted file AWS EFS storage.
    • <EFS_FILE_SYSTEM_ID>: ID of the AWS EFS file system containing the file that should be mounted to the container. ID is displayed in the AWS Management Console → ServicesEFSFile systems.
    • The environment object sets the environment variables that should be passed to the Docker container in a text format. The set of available environment variables is described in the table below. It is recommended to pass the variables DEPLOY_USER and DEPLOY_PASSWORD in the secrets object.
    • The secret object sets the environment variables that should be passed to the Docker container as the links to the sensitive data storage. The format of values depends on the selected storage (see more details in the AWS Secrets Manager or AWS Systems Manager → Parameter Store documentation).

      It is recommended to pass the variables DEPLOY_USER and DEPLOY_PASSWORD in the secrets object.

      Environment variable Description Required
      DEPLOY_USER Email to the Deploy or Administrator user account in the Wallarm Console. Yes
      DEPLOY_PASSWORD Password to the Deploy or Administrator user account in the Wallarm Console. Yes
      WALLARM_API_HOST Wallarm API server:
      • api.wallarm.com for the EU Cloud
      • us1.api.wallarm.com for the US Cloud
      By default: api.wallarm.com.
      No
      DEPLOY_FORCE Replaces an existing WAF node with a new one if an existing WAF node name matches the identifier of the container you are running. The following values can be assigned to a variable:
      • true to replace the WAF node
      • false to disable the replacement of the WAF node
      Default value (if the variable is not passed to the container) is false.
      The WAF node name always matches the identifier of the container you are running. WAF node replacement is helpful if the Docker container identifiers in your environment are static and you are trying to run another Docker container with the WAF node (for example, a container with a new version of the image). If in this case the variable value is false, the WAF node creation process will fail.
      No
    • All configuration file parameters are described in the AWS documentation.

  7. Register the task definition based on the JSON configuration file by using the aws ecs register‑task‑definition command:

    aws ecs register-task-definition --cli-input-json file://<PATH_TO_JSON_FILE>/<JSON_FILE_NAME>
    
    • <PATH_TO_JSON_FILE>: path to the JSON file with the task definition on the local machine.
    • <JSON_FILE_NAME>: name and extension of the JSON file with the task definition.
  8. Run the task in the cluster by using the aws ecs run-task command:

    aws ecs run-task --cluster <CLUSTER_NAME> --launch-type EC2 --task-definition <FAMILY_PARAM_VALUE>
    
    • <CLUSTER_NAME>: name of the cluster created in the first step. For example, waf-cluster.
    • <FAMILY_PARAM_VALUE>: name of the created task definition. The value should correspond to the family parameter value specified in the JSON file with the task definition. For example, wallarm-waf-node.
  9. Open the AWS Management Console → Elastic Container Service → cluster with the running task → Tasks and ensure the task is displayed in the list.

  10. Test the WAF node operation.

Testing the WAF node operation

  1. In the AWS Management Console, open the running task and copy the container IP address from the field External Link.

    Settig up container instance

    If the IP address is empty, please ensure the container is in the RUNNING status.

  2. Send the request with test SQLI and XSS attacks to the copied address:

    curl http://<COPIED_IP>/?id='or+1=1--a-<script>prompt(1)</script>'
    
  3. Open the Wallarm Console → Events section in the EU Cloud or US Cloud and ensure attacks are displayed in the list.

    Attacks in UI

Details on errors that occurred during the container deployment are displayed in the task details in the AWS Management Console. If the container is unavailable, please ensure required WAF node parameters with correct values are passed to the container.