Running API Firewall on Docker¶

This guide walks through downloading, installing, and starting Wallarm API Firewall on Docker.

Requirements¶

• Installed and configured Docker

• OpenAPI 3.0 specification developed for the REST API of the application that should be protected with Wallarm API Firewall

Methods to run API Firewall on Docker¶

The fastest method to deploy API Firewall on Docker is Docker Compose. The steps below rely on using this method.

If required, you can also use docker run. We have provided proper docker run commands to deploy the same environment in this section.

Step 1. Create the docker-compose.yml file¶

To deploy API Firewall and proper environment using Docker Compose, create the docker-compose.yml with the following content first:

version: '3.8'

networks:
  api-firewall-network:
    name: api-firewall-network

services:
  api-firewall:
    container_name: api-firewall
    image: wallarm/api-firewall:v0.6.9
    restart: on-failure
    volumes:
      - <HOST_PATH_TO_SPEC>:<CONTAINER_PATH_TO_SPEC>
    environment:
      APIFW_API_SPECS: <PATH_TO_MOUNTED_SPEC>
      APIFW_URL: <API_FIREWALL_URL>
      APIFW_SERVER_URL: <PROTECTED_APP_URL>
      APIFW_REQUEST_VALIDATION: <REQUEST_VALIDATION_MODE>
      APIFW_RESPONSE_VALIDATION: <RESPONSE_VALIDATION_MODE>
    ports:
      - "8088:8088"
    stop_grace_period: 1s
    networks:
      - api-firewall-network
  backend:
    container_name: api-firewall-backend
    image: kennethreitz/httpbin
    restart: on-failure
    ports:
      - 8090:8090
    stop_grace_period: 1s
    networks:
      - api-firewall-network

Step 2. Configure the Docker network¶

If required, change the Docker network configuration defined in docker-compose.yml → networks.

The provided docker-compose.yml instructs Docker to create the network api-firewall-network and link the application and API Firewall containers to it.

It is recommended to use a separate Docker network to allow the containerized application and API Firewall communication without manual linking.

Step 3. Configure the application to be protected with API Firewall¶

Change the configuration of the containerized application to be protected with API Firewall. This configuration is defined in docker-compose.yml → services.backend.

The provided docker-compose.yml instructs Docker to start the kennethreitz/httpbin Docker container connected to the api-firewall-network and assigned with the backend network alias. The container port is 8090.

If configuring your own application, define only settings required for the correct application container start. No specific configuration for API Firewall is required.

Step 4. Configure API Firewall¶

Pass API Firewall configuration in docker-compose.yml → services.api-firewall as follows:

With services.api-firewall.volumes, please mount the OpenAPI 3.0 specification to the API Firewall container directory:

• <HOST_PATH_TO_SPEC>: the path to the OpenAPI 3.0 specification for your application REST API located on the host machine. The accepted file formats are YAML and JSON (.yaml, .yml, .json file extensions). For example: /opt/my-api/openapi3/swagger.json.

• <CONTAINER_PATH_TO_SPEC>: the path to the container directory to mount the OpenAPI 3.0 specification to. For example: /api-firewall/resources/swagger.json.

With services.api-firewall.environment, please set the general API Firewall configuration through the following environment variables:

More API Firewall configuration options are described within the link.

With services.api-firewall.ports and services.api-firewall.networks, set the API Firewall container port and connect the container to the created network. The provided docker-compose.yml instructs Docker to start API Firewall connected to the api-firewall-network network on the port 8088.

Step 5. Deploy the configured environment¶

To build and start the configured environment, run the following command:

docker-compose up -d --force-recreate

To check the log output:

docker-compose logs -f

Step 6. Test API Firewall operation¶

To test API Firewall operation, send the request that does not match the mounted Open API 3.0 specification to the API Firewall Docker container address. For example, you can pass the string value in the parameter that requires the integer value.

If the request does not match the provided API schema, the appropriate ERROR message will be added to the API Firewall Docker container logs.

Step 7. Enable traffic on API Firewall¶

To finalize the API Firewall configuration, please enable incoming traffic on API Firewall by updating your application deployment scheme configuration. For example, this would require updating the Ingress, NGINX, or load balancer settings.

API Firewall fine-tuning options¶

To address more business issues by API Firewall, you can fine-tune the tool operation. Supported fine-tuning options are listed below. Please pass them as environment variables when configuring the API Firewall Docker container.

Validation of request authentication tokens¶

If using OAuth 2.0 protocol-based authentication, you can configure API Firewall to validate the access tokens before proxying requests to the application's server. API Firewall expects the access token to be passed in the Authorization: Bearer request header.

API Firewall considers the token to be valid if the scopes defined in the specification and in the token meta information are the same. If the value of APIFW_REQUEST_VALIDATION is BLOCK, API Firewall blocks requests with invalid tokens. In the LOG_ONLY mode, requests with invalid tokens are only logged.

To configure the OAuth 2.0 token validation flow, use the following optional environment variables:

Blocking requests with compromised authentication tokens¶

If an API leak is detected, the Wallarm API Firewall is able to stop the compromised authentication tokens from being used. If the request contains compromised tokens, API Firewall responses to this request with the code configured via APIFW_CUSTOM_BLOCK_STATUS_CODE.

To enable the denylist feature:

1. Mount the denylist file with compromised tokens into the Docker container. The denylist text file may look as follows:

   eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzb21lIjoicGF5bG9hZDk5OTk5ODIifQ.CUq8iJ_LUzQMfDTvArpz6jUyK0Qyn7jZ9WCqE0xKTCA
   eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzb21lIjoicGF5bG9hZDk5OTk5ODMifQ.BinZ4AcJp_SQz-iFfgKOKPz_jWjEgiVTb9cS8PP4BI0
   eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzb21lIjoicGF5bG9hZDk5OTk5ODQifQ.j5Iea7KGm7GqjMGBuEZc2akTIoByUaQc5SSX7w_qjY8
   

2. Configure the denylist feature passing the following variables to the Docker container:

   Environment variable	Description
   APIFW_DENYLIST_TOKENS_FILE	The path to the text denylist file mounted to the container. The tokens in the file must be separated by newlines. Example value: /api-firewall/resources/tokens-denylist.txt.
   APIFW_DENYLIST_TOKENS_COOKIE_NAME	The name of the Cookie used to pass the authentication token.
   APIFW_DENYLIST_TOKENS_HEADER_NAME	The name of the Header used to pass the authentication token. If both the APIFW_DENYLIST_TOKENS_COOKIE_NAME and APIFW_DENYLIST_TOKENS_HEADER_NAME variables are specified, API Firewall sequentially checks its values.
   APIFW_DENYLIST_TOKENS_TRIM_BEARER_PREFIX	Whether to trim the Bearer prefix from the authentication header when comparing its value with the denylist contents. If the Bearer prefix is passed in the authentication header and tokens in the denylist do not contain this prefix, tokens will not be validated reliably. The value can be true or false. The default value is false.

Protected application SSL/TLS settings¶

To facilitate the connection between API Firewall and the protected application's server signed with the custom CA certificates or insecure connection, use the following optional environment variables:

API Firewall SSL/TLS settings¶

To set up SSL/TLS for the server with the running API Firewall, use the following optional environment variables:

System settings¶

To fine-tune system API Firewall settings, use the following optional environment variables:

Stopping the deployed environment¶

To stop the environment deployed using Docker Compose, run the following command:

docker-compose down

Using docker run to start API Firewall¶

To start API Firewall on Docker, you can also use regular Docker commands as in the examples below:

1. To create a separate Docker network to allow the containerized application and API Firewall communication without manual linking:

   docker network create api-firewall-network
   

2. To start the containerized application to be protected with API Firewall:

   docker run --rm -it --network api-firewall-network \
       --network-alias backend -p 8090:8090 kennethreitz/httpbin
   

3. To start API Firewall:

   docker run --rm -it --network api-firewall-network --network-alias api-firewall \
       -v <HOST_PATH_TO_SPEC>:<CONTAINER_PATH_TO_SPEC> -e APIFW_API_SPECS=<PATH_TO_MOUNTED_SPEC> \
       -e APIFW_URL=<API_FIREWALL_URL> -e APIFW_SERVER_URL=<PROTECTED_APP_URL> \
       -e APIFW_REQUEST_VALIDATION=<REQUEST_VALIDATION_MODE> -e APIFW_RESPONSE_VALIDATION=<RESPONSE_VALIDATION_MODE> \
       -p 8088:8088 wallarm/api-firewall:v0.6.9
   

4. When the environment is started, test it and enable traffic on API Firewall following steps 6 and 7.