Deploy With Docker-Compose

Docker-Compose deployment for open-appsec is currently in beta status, steps are currently provided for NGINX only, KONG and APISIX will be added here soon as well.

This new deployment option with Docker-Compose will introduce additional containers in case of a standalone deployment (= deployment without any connection to WebUI). These containers introduce some additional functionality, which is relevant for standalone deployments only (already available when connected to central management WebUI): - Local syncing of learning between open-appsec processes and agents - View learning progress on CLI with open-appsec-tuning-tool - Receive configuration recommendations based on the learning progress using the open-appsec-tuning-tool - Receive tuning suggestions and manage them (approve/reject) using the open-appsec-tuning-tool More details on the open-appsec-tuning-tool here: Track Learning and Local Tuning in Standalone Deployments

Prerequisites

Linux Docker Host with root permission
Docker-Compose tool installed
(Optional, Recommended) Sign-Up and Login to WebUI Portal If you want to centrally manage your open-appsec WAF deployment via WebUI (SaaS) OR if you want to locally manage your open-appsec WAF deployment but still connect to central WebUI for viewing the local configuration (in read-only), central monitoring, logging and reporting: Follow the instructions below to sign-up and login to the WebUI available at https://my.openappsec.io:

Sign-Up and Login to Portal

(Optional, Recommended) Create deployment profile for the open-appsec deployment in WebUI Portal If you signed-up and logged in to the WebUI Portal (see prerequisite above), now follow the instructions below to create a new deployment profile for your open-appsec deployment. Once done, don't forget to copy the profile token after policy installation as this is needed in the installation steps further below.

Create a Profile

Deployment

To deploy open-appsec with docker-compose and optionally connect to the central WebUI available at https://my.openappsec.io follow the steps below:

Create a folder for your new open-appsec deployment and switch to that folder, e.g.

mkdir open-appsec-deployment
cd ./open-appsec-deployment

Download the docker compose file for your desired open-appsec integration

wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/nginx/docker-compose.yaml

Below you can see the content of the docker-compose.yaml file:

version: "2"
services:
  appsec-agent:
    image: ghcr.io/openappsec/agent:${APPSEC_VERSION}
    container_name: appsec-agent
    environment:
      - SHARED_STORAGE_HOST=appsec-shared-storage
      - LEARNING_HOST=appsec-smartsync
      - TUNING_HOST=appsec-tuning-svc
      - https_proxy=${APPSEC_HTTPS_PROXY}
      - user_email=${USER_EMAIL}
      - AGENT_TOKEN=${APPSEC_AGENT_TOKEN}
      - autoPolicyLoad=${APPSEC_AUTO_POLICY_LOAD}
    ipc: shareable
    volumes:
      - ${APPSEC_CONFIG}:/etc/cp/conf
      - ${APPSEC_DATA}:/etc/cp/data
      - ${APPSEC_LOGS}:/var/log/nano_agent
      - ${APPSEC_LOCALCONFIG}:/ext/appsec
    command: /cp-nano-agent
  appsec-nginx:
    image: ghcr.io/openappsec/nginx-attachment:${APPSEC_VERSION}
    container_name: appsec-nginx
    ipc: service:appsec-agent
## when mounting own external nginx config uncomment the two lines below, place the config in {NGINX_CONF_DIR}
#   volumes:
#     - ${NGINX_CONF_DIR}:/etc/nginx/conf.d

## advanced configuration - volume mount for nginx.conf file:
## to change global instructions it's possible to also mount your own nginx.conf file by uncommenting the two lines below
## make sure to include the line starting with "load_module" which loads the appsec attachment
## and is included in /etc/nginx/conf.d/nginx.conf file as part of the nginx-attachment container
## make sure to only have one "volumes:" key
#   volumes:
#     - ${NGINX_CONF_FILE}:/etc/nginx/nginx.conf
    ports:
      - "80:80"
      - "443:443"
  appsec-smartsync:
    profiles:
      - standalone
    image: ghcr.io/openappsec/smartsync:${APPSEC_VERSION}
    container_name: appsec-smartsync
    environment:
      - SHARED_STORAGE_HOST=appsec-shared-storage
    depends_on:
      - appsec-shared-storage
  appsec-shared-storage:
    profiles:
      - standalone
    image: ghcr.io/openappsec/smartsync-shared-files:${APPSEC_VERSION}
    container_name: appsec-shared-storage
    ipc: service:appsec-agent
    ## if you do not want to run this container as "root" user you can comment it out and instead run the below command after the deployment
    ## docker exec -u root appsec-shared-storage chown -R appuser:appuser /db
    user: root
    volumes:
      - ${SMART_SYNC_STORAGE}:/db:z
## instead of using local storage for local learning (see line above)
## you can also configure central nfs storage by configuring nfs volume (uncomment the relevant section at end of this file)
## use a shared nfs storage which is recommended in redundant deployments (uncomment line below, comment out the line above) 
#     - learning_nfs:/db:z
  appsec-tuning-svc:
    profiles:
      - standalone
    image: ghcr.io/openappsec/smartsync-tuning:${APPSEC_VERSION}
    container_name: appsec-tuning-svc
    environment:
      - SHARED_STORAGE_HOST=appsec-shared-storage
      - QUERY_DB_PASSWORD=${DB_PASSWORD}
      - QUERY_DB_HOST=${DB_HOST}
      - QUERY_DB_USER=${DB_USER}
## only relevant when deploying own DB 
#     - SSLMODE:
    volumes:
      - ${APPSEC_CONFIG}:/etc/cp/conf
    depends_on:
      - appsec-shared-storage
      - appsec-db
  appsec-db:
    profiles:
      - standalone
    image: postgres
    container_name: appsec-db
    restart: always
    environment:
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_USER=${DB_USER} 
    volumes:
      - ${POSTGRES_STORAGE}:/var/lib/postgresql/data

## example juice-shop backend container (vulnerable webserver, USE ONLY FOR TESTING AND IN LAB ENV)
##
## uncomment this block for testing purposes only, make sure to also adjust the nginx.conf file 
## to include a proxy_pass directive forwarding external traffic on e.g. port 80 to the juiceshop-backend container
## you can use the example file available here:
## https://github.com/openappsec/openappsec/blob/main/examples/juiceshop/default.conf
## place the file above in {NGINX_CONF_DIR} and uncomment the two lines for creating a volume mount
## in the appsec-nginx service definition
## note that juiceshop container listens on HTTP port 3000 by default
#
# juiceshop-backend:
#   image: bkimminich/juice-shop:latest
#   container_name: juiceshop-backend


## advanced configuration: learning_nfs volume for nfs storage in shared_storage container
##
## when configuring nfs storage in shared_storage container configuration above, make sure to also specify learning_nfs volume (see example below for using AWS EFS storage)
# 
# volumes:
#   learning_nfs:
#     driver: local
#     driver_opts:
#       type: nfs
#       o: addr=fs-abcdef.efs.eu-west-1.amazonaws.com,rw,nfsvers=4.1,rsize=1048576,wsize=1048576,hard,timeo=600,retrans=2,noresvport
#       device: ":/"

Download the .env file for your desired open-appsec integration and adjust the configuration to your requirements as described below:

Download the default .env file here:

wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/nginx/.env

Here are the contents of the .env file:

## .env file for docker-compose deployments of open-appsec integrated with NGINX
## for more info see https://docs.openappsec.io

APPSEC_VERSION=latest
APPSEC_CONFIG=./appsec-config
APPSEC_DATA=./appsec-data
APPSEC_LOGS=./appsec-logs
APPSEC_LOCALCONFIG=./appsec-localconfig
APPSEC_AUTO_POLICY_LOAD=false
## Example for configuring HTTPS Proxy:
## APPSEC_HTTPS_PROXY=user:password@proxy_address:port
APPSEC_HTTPS_PROXY=
SMART_SYNC_STORAGE=./smartsync-storage
USER_EMAIL=user@email.com
DB_PASSWORD=pass
DB_USER=postgres
DB_HOST=appsec-db
POSTGRES_STORAGE=./postgres-data
NGINX_CONF_DIR=./nginx-proxy-config

## To connect your deployment to central WebUI you can uncomment following line
## and provide the token for a profile which you created in open-appsec WebUI at https://my.openappsec.io
## Example: APPSEC_AGENT_TOKEN=111-22222-111
APPSEC_AGENT_TOKEN=

## When not providing token for connection to central WebUI please uncomment following line
## which will enable sharing of learning between processes and allow you to perform tuning locally on CLI
# COMPOSE_PROFILES=standalone

If you created a deployment profile in the WebUI and copied the Token from it:
Edit the .env file and add your token to the key APPSEC_AGENT_TOKEN.
If you did not create a deployment profile in the WebUI and do not want to connect your deployment to central WebUI (SaaS) at all:
Uncomment the line with the COMPOSE_PROFILES key, which will set the standalone mode and activate the deployment of additional containers which are required only when not connected to the WebUI at all (resulting in standalone, locally, declaratively managed deployment).
Replace user@email.com in the .env file with your own email. (More details below.)

Available settings in the `.env` file allowing further customization of the deployment:

APPSEC_AGENT_TOKEN: For connecting your open-appsec deployment to central WebUI set APPSEC_AGENT_TOKEN to your own deployment profile token as copied from profile settings in the open-appsec central WebUI (see section Prerequisites above).

COMPOSE_PROFILES: ONLY in case you did not set a WebUI deployment profile token as value for the APPSEC_AGENT_TOKEN key (see above): Uncomment the line with the COMPOSE_PROFILES key, which will activate the deployment of additional containers required only when not connected to the WebUI at all (resulting in standalone, locally, declaratively managed deployment).

USER_EMAIL: (Optional) Associate your email address with your specific deployment by replacing user@email.com with your own email address.

This allows the open-appsec team to provide you easy assistance in case of any issues you might have with your specific deployment in the future and also to provide you information proactively regarding open-appsec in general or regarding your specific deployment. This is an optional parameter and can be removed. If we send automatic emails there will also be an opt-out option included for receiving similar communication in the future.

APPSEC_HTTPS_PROXY: (Optional) Configure an HTTP(S) proxy server to be used by the agent.

APPSEC_AUTO_POLICY_LOAD: (Optional) When set to true, allows you to set the open-appsec agent to automatically apply any new changes in the local_policy.yaml file without having to restart the agent container or applying the changes with open-appsec-ctl -ap (note that this can take up to 30 seconds). This is useful especially in DevOps scenarios with continuous deployment scenarios.

APPSEC_VERSION: Allows you to specify a specific version for deployment instead of using the default latest version for the containers provided by open-appsec (not relevant for postgres container).

Additional configuration available specifically for this integration type:

NGINX_CONF_DIR: Set the directory on the docker host used for the volume mount to the NGINX conf.d directory. For this parameter to be applied also uncomment the following line in the docker-compose.yaml file so that the volume mount for the nginx configuration will get created: - ${NGINX_CONF_DIR}:/etc/nginx/conf.d

You find some additional advanced configuration options described within the docker-compose.yaml file as comments.

The docker-compose.yaml file also shows instructions for easily deploying an example nginx backend server based on the "juiceshop" container. This includes many vulnerabilities and therefore should be used in lab environments for testing purposes only.

If you decided to locally, declaratively manage open-appsec with local_policy.yaml file: Download the initial declarative configuration file for open-appsec into new subfolder ./appsec-localconfig:
```
mkdir ./appsec-localconfig
wget https://raw.githubusercontent.com/openappsec/openappsec/main/config/linux/v1beta1/prevent/local_policy.yaml -O ./appsec-localconfig/local_policy.yaml
```

This example configuration file is already set to mode: prevent-learnso that open-appsec will prevent attacks right from the start.Here's the path for an alternative local-config.yaml file set to detect-learn mode. https://raw.githubusercontent.com/openappsec/openappsec/main/config/linux/v1beta1/detect/local_policy.yaml (or simply adjust the setting in the mode setting in the earlier local_policy.yaml file to detect-learn) In production environments it's always recommended to start in detect-learn mode to allow open-appsec to achieve a certain learning level based on traffic observed before moving to prevent-learnfor better detection accuracy and strongly reduced false positives. Read more about this here: Track Learning and Move From Learn/Detect to Prevent

Perform the deployment

docker-compose up -d

You will see output similar to the below. Note that the amount of container will vary based between deployments with and without connection to central WebUI.

Verify that all containers are up and running by verifying their status in docker ps output. Note that the amount of container will vary based between deployments with and without connection to central WebUI.

docker ps

You will see output similar to the below:

Congratulations, you successfully deployed open-appsec WAF!

Recommended next steps:

If you connected to central WebUI AND configured your deployment profile in the WebUI to "This management" mode for centrally managing open-appsec configuration: Create one or more assets in the WebUI which represent web applications and/or Web APIs which you want to be protected by open-appsec WAF and allows you to adjust the open-appsec configuration specifically for each of them.
Make sure to link your assets to the specific WebUI Profile which you created earlier (General -> Profiles) and adjust the Threat Prevention mode to Detect-Learn or Prevent (Threat Prevention -> Mode), the steps are described here: Protect Additional Assets

Don't forget to Enforce policy in the WebUI after you did any changes for those changes to become effective!

If you decided to locally, declaratively manage open-appsec (with or without connection to central WebUI in "Declarative configuration" mode): Follow the steps described here to configure your open-appsec deployment using the local_policy.yaml file: Configuration Using Local Policy File (Docker) In case you connected your locally managed deployment also to the central WebUI in "Declarative Configuration" mode, you can check security logs and view agent status and configuration also in the central WebUI at https://my.openappsec.io .

Don't forget to apply the policy using open-appsec-ctl -ap in the open-appsec-agent container or by setting APPSEC_AUTO_POLICY_LOAD in the .env file to true for automatic application of any configuration changes done in the local_policy.yaml file for the changes to become effective!

PreviousInstall With Docker (Locally Managed)NextConfiguration Using Local Policy File (Docker)

Last updated 1 day ago

Prerequisites

Deployment

To deploy open-appsec with docker-compose and optionally connect to the central WebUI available at https://my.openappsec.io follow the steps below:

Available settings in the .env file allowing further customization of the deployment:

Recommended next steps:

Available settings in the `.env` file allowing further customization of the deployment: