Deploy NGINX Proxy Manager with open-appsec managed from central WebUI (SaaS)

Prerequisites

• Access to a SaaS tenant on my.openappsec.io (WebUI for SaaS management) Follow the instructions available here:

Sign-Up and Login to Portal

• Agent profile created for open-appsec Docker deployment in SaaS tenant Follow the instructions available here. 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

• Linux machine with:

  • Docker and Docker Compose installed

  • Root Permissions

If you want to migrate from an existing NGINX Proxy Manager deployment to use this integration with open-appsec, please check out specific the FAQ further below on this page for specific instructions and further information.

To deploy NGINX Proxy Manager with open-appsec integration follow the steps below:

Docker Compose (recommended)

Prerequisites

• Linux Docker Host with root permission

• Docker-Compose tool installed

• Sign-Up and Login to WebUI Portal For centrally managing your configuration of open-appsec integrated with NPM first follow the instructions below to sign-up and login to the WebUI available at https://my.openappsec.io:

Sign-Up and Login to Portal

• Create deployment profile for the open-appsec deployment in WebUI Portal 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 connect to the central management 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-centrally-managed/docker-compose.yaml

docker-compose.yaml file content:

https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/nginx-proxy-manager-centrally-managed/docker-compose.yamlraw.githubusercontent.com

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-centrally-managed/.env

.env file content:

https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/nginx-proxy-manager-centrally-managed/.envraw.githubusercontent.com

• Edit the .env file and add your token to the key APPSEC_AGENT_TOKEN.

• Replace [e-mail] 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.

Only activate the standalone profile in case you did not set a WebUI deployment profile token as value for the APPSEC_AGENT_TOKEN key (see above) and want to manage open-appsec integrated with NGINX Proxy Manager using open-appsec's local declarative configuration file local_policy.yaml!

The additional containers which get deployed in standalone mode introduce some additional functionality, which is relevant for standalone deployments only (that same functionality is already available when connected to open-appsec's 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

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/

Do not activate the juiceshop profile in production environments as the juiceshop container is intentionally highly vulnerable and meant for testing in lab environments only!

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

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

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

docker ps example output with all containers up

Docker Compose (deprecated)

Congratulations, you successfully deployed NGINX Proxy Manager with open-appsec integration!

For Production usage you might want to switch from using the Basic to the more accurate Advanced Machine Learning model, as described here:

Using the Advanced Machine Learning Model

Now you can login with your web browser to the WebUI of NGINX Proxy Manager with open-appsec integration as follows:

http://[hostname or IP of your host]:81

At first login please use the following default administrator user credentials: E-mail address: [e-mail] Password: changeme

You will then be prompted to provide your own user details and asked to change the password, before being presented with the NGINX Proxy Manager Dashboard view:

NGINX Proxy Manager Dashboard

Configuration

To learn how to use NGINX Proxy Manager (NPM) see project documentation: https://nginxproxymanager.com (NPM usage and configuration will not be explained here).

If you deployed the new docker-compose file (beta) which includes the optional vulnerable juiceshop container (just for testing purposes, do not use in production environments!) and added the value juiceshop to the parameter COMPOSE_PROFILES then you can configure juiceshop-backend in the Forward Hostname / IP field of the Edit Proxy Host window to proxy inbound traffic to it.

Once you created a new Proxy Host within NGINX Proxy Manager WebUI you can now configure open-appsec protection for it in the open-appsec WebUI (https://my.openappsec.io).

1. In the open-appsec Web UI: Navigate to the Agents tab and ensure the new agent is successfully connected.

2. In the open-appsec Web UI: Create one or more assets defining the specific resources that open-appsec should protect and don't forget to install the policy afterwards. One typical approach would be to create one asset in the open-appsec WebUI per each "Proxy Host" you configured in the NGINX Proxy Manager WebUI. This would allow you to have individual open-appsec security settings per each Proxy Host configured in NPM. All required steps are explained here:

Protect Additional Assets