Install NGINX Proxy Manager with open-appsec managed from NPM WebUI

Prerequisites

• Linux Docker Host with root permission

• Docker-Compose tool installed

• (Optional, Recommended) Sign-Up and Login to WebUI Portal If you want to locally manage your open-appsec WAF deployment using the NPM WebUI 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:

• (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.

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:

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

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

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

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

# Copyright (C) 2022 Check Point Software Technologies Ltd. All rights reserved.

# Licensed under the Apache License, Version 2.0 (the "License");
# You may obtain a copy of the License at

#     http://www.apache.org/licenses/LICENSE-2.0

# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

##
## Docker compose file for open-appsec integrated with NGINX Proxy Manager
## with open-appsec management via NGINX Proxy Manager WebUI
##

version: '3.9'

services:
  appsec-agent:
    image: ghcr.io/openappsec/agent:${APPSEC_VERSION}
    container_name: appsec-agent
    ipc: shareable
    restart: unless-stopped
    environment:
      - SHARED_STORAGE_HOST=appsec-shared-storage
      - LEARNING_HOST=appsec-smartsync
      - TUNING_HOST=appsec-tuning-svc
      - https_proxy=${APPSEC_HTTPS_PROXY}
      - user_email=${APPSEC_USER_EMAIL}
      - AGENT_TOKEN=${APPSEC_AGENT_TOKEN}
      - autoPolicyLoad=${APPSEC_AUTO_POLICY_LOAD}
      - nginxproxymanager=true
    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-proxy-manager:
    container_name: appsec-nginx-proxy-manager
    image: ghcr.io/openappsec/nginx-proxy-manager-attachment:${APPSEC_VERSION}
    ipc: service:appsec-agent
    restart: unless-stopped
    ports:
      - 80:80 # Public HTTP Port
      - 443:443 # Public HTTPS Port
      - 81:81 # Admin Web Port
    volumes:
      - ${NPM_DATA}:/data
      - ${NPM_LETSENCRYPT}:/etc/letsencrypt
      - ${APPSEC_LOGS}:/ext/appsec-logs
      - ${APPSEC_LOCALCONFIG}:/ext/appsec

  appsec-smartsync:
    profiles:
      - standalone
    image: ghcr.io/openappsec/smartsync:${APPSEC_VERSION}
    container_name: appsec-smartsync
    environment:
      - SHARED_STORAGE_HOST=appsec-shared-storage
    restart: unless-stopped
    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
    restart: unless-stopped
## 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:
      - ${APPSEC_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=${APPSEC_DB_PASSWORD}
      - QUERY_DB_HOST=${APPSEC_DB_HOST}
      - QUERY_DB_USER=${APPSEC_DB_USER}
## only relevant when deploying own DB 
#     - SSLMODE:
    restart: unless-stopped
    volumes:
      - ${APPSEC_CONFIG}:/etc/cp/conf
    depends_on:
      - appsec-shared-storage
      - appsec-db
      
  appsec-db:
    profiles:
      - standalone
    image: postgres
    container_name: appsec-db
    restart: unless-stopped
    environment:
      - POSTGRES_PASSWORD=${APPSEC_DB_PASSWORD}
      - POSTGRES_USER=${APPSEC_DB_USER} 
    volumes:
      - ${APPSEC_POSTGRES_STORAGE}:/var/lib/postgresql/data

## example juice-shop backend container (vulnerable webserver, USE ONLY FOR TESTING AND IN LAB ENV)
  juiceshop-backend:
    image: bkimminich/juice-shop:latest
    container_name: juiceshop-backend
    profiles:
      - juiceshop

## 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: ":/"

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

wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/nginx-proxy-manager/.env

• 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:

  Set the value standalone for the key COMPOSE_PROFILES which will 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 [email protected] 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: Possible values you can set for this key: (you can set multiple values, separated by comma)

standalone : This will activate the deployment of additional containers which are required only when you are not connected to the WebUI at all, resulting in standalone, locally, declaratively managed deployment.

juiceshop : This will deploy an additional, vulnerable juiceshop-backend container that can be used for demo and testing purposes. In the .env file you also find a download link for the proxy-specific configuration allowing you to access the juiceshop backend via the proxy. More info on the OWASP juiceshop project: https://owasp.org/www-project-juice-shop/

USER_EMAIL: (Optional) Associate your email address with your specific deployment by replacing [email protected] 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:

NPM_DATA: Specify the local folder on the host for the volume mount of the NPM data directory, in the appsec-nginx-proxy-manager container this gets mounted into /data.

NPM_LETSENCRYPT: Specify the local folder on the host for the LetsEncrypt data, in the appsec-nginx-proxy-manager container this gets mounted into /etc/letsencrypt.

For testing purposes in a lab environment you can activate the deployment of the vulnerable juiceshop-backend container via COMPOSE_PROFILES key (see above) and then deploy the available configuration example for exposing it via the proxy, which is provided by the open-appsec team (download link is provided in the .env file).

1. Download the initial declarative configuration file for open-appsec into new subfolder ./appsec-localconfig (note this is a specifically adjusted version for the NPM integration):

   Copy

   mkdir ./appsec-localconfig
   wget https://raw.githubusercontent.com/openappsec/open-appsec-npm/main/deployment/managed-from-npm-ui/local_policy.yaml -O ./appsec-localconfig/local_policy.yaml

1. Perform the deployment

docker-compose up -d

You will see output similar to the below. (The example screenshot below is for an NGINX deployment.) Note that the amount of container will vary based between deployments with and without connection to central WebUI.

1. 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: (The example screenshot below is for an NGINX deployment.)