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

Deployment:

Before you start, make sure to have a Linux environment with Docker and Docker Compose available.

If you want to migrate from an existing NGINX Proxy Manager deployment to use this integration with open-appsec, please check out our guide in the FAQ section.

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

Within the directory which you want to use for the deployment: Create a folder appsec-localconfig which will hold the appsec declarative configuration file (this will be managed by the enhanced NPM WebUI).

mkdir ./appsec-localconfig

2. Download the initial declarative configuration file for open-appsec into that folder:

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

3. Create a docker-compose.yaml file with the content below, it can be downloaded as follows:

wget https://raw.githubusercontent.com/openappsec/open-appsec-npm/main/deployment/managed-from-npm-ui/docker-compose.yaml

docker-compose.yaml content:

version: '3.3'
# docker compose for nginx proxy manager open-appsec integration
# open-appsec managed and monitored from nginx proxy manager web ui

services:
  appsec-npm:
    container_name: npm-attachment
    image: 'ghcr.io/openappsec/nginx-proxy-manager-attachment:latest'
    ipc: host
    restart: unless-stopped
    ports:
      - '80:80' # Public HTTP Port
      - '443:443' # Public HTTPS Port
      - '81:81' # Admin Web Port
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
      - ./appsec-logs:/ext/appsec-logs
      - ./appsec-localconfig:/ext/appsec

  appsec-agent:
    container_name: appsec-agent
    image: 'ghcr.io/openappsec/agent:latest'
    network_mode: service:appsec-npm
    ipc: host
    restart: unless-stopped
    environment:
      # adjust with your own email below
      - user_email=user@email.com
      - nginxproxymanager=true
      - autoPolicyLoad=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 --standalone

Edit the docker-compose.yaml file and replace "user@email.com" with your own email address, so we can provide assistance in case of any issues with the specific deployment in the future and provide information proactively regarding open-appsec.
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
Start the deployment of all relevant containers using docker-compose:

docker-compose up -d

Check if the appsec-npm and the appsec-agent containers are up and running:

docker ps

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: admin@example.com 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:

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

Once you created a new Proxy Host within NGINX Proxy Manager WebUI you can now easily enable and configure open-appsec protection (see also screenshot below):

Enable open-appsec by flipping the “open-appsec” switch to enabled.
Select the Enforcement Mode, it can be either “Prevent-Learn” or “Detect-Learn”
Select the minimum confidence level for open-appsec to prevent an attack (only relevant when in prevent mode), it can be either “Critical”, “High” or “Medium” confidence.
Click “Save”

This screenshot as an example shows a “Proxy Host” reverse proxy configuration in NPM that will listen to inbound traffic for hostnames “100.25.161.101”, “localhost” or “my.webserver.com”.

This Proxy Host has open-appsec enabled in “Prevent-Learn” mode and therefore will prevent incoming http or https requests when there’s a minimum confidence level of “High” or higher, as configured for the “Minimum confidence for prevent” setting.

Non-malicious traffic will then be proxied using “http” protocol to the configured backend webserver with the IP address “192.168.160.2” on port “80”.

Using Custom Locations in Proxy Host objects

If you are using “Custom locations” in NPM for a more granular backend configuration you can configure open-appsec in similar same way as described above, but configuration will then be specific and applied only to this “Custom location”:

This gives you for example the flexibility to set open-appsec to “Detect-Learn” for a specific “Custom location” while the main Proxy Host configuration is set to “Prevent-Learn”. Alternatively, you could also use this option to have open-appsec configured to “Detect-Learn” for your Proxy Host configuration but already set it to “Prevent-Learn” for some specific paths which require immediate protection or which you want to test prevent mode before enabling it for the “whole” Proxy Host.

Changes in the open-appsec configuration performed and saved in the NPM Web UI can take up to 30 seconds before they become effective.

How to view open-appsec Logs in NPM Web UI:

If you want to check out the open-appsec Logs click on the new menu option “Security Log” which allows you to view the open-appsec specific logs directly from the NPM Web UI. Within the Security Log view you can chose between three separate views:

Important Events
All Events
Notifications

The "open" button at the beginning of each log allows you to view the full log in json format:

How to configure open-appsec advanced settings:

Performing direct changes of the local declarative configuration file for open-appsec in the "open-appsec Advanced" section will be "at your own risk", as you might break the configuration. Only do this if required and if you know what you do or test stuff in a risk-free lab environment.

What if you want to configure some advanced settings of open-appsec which are not covered or not covered “yet” as part of the open-appsec enhanced NPM WebUI? We thought about this as well and added an extra editor allowing you to adjust the declarative open-appsec configuration under “Settings” -> “open-appsec Advanced”.

The local policy file specification is available here: Local Policy File (Advanced)

Make sure to push the “save” button once you did any changes here and be especially careful with the configuration that has “npm-managed...” as part of the name, as these configuration elements are created and partly managed by the open-appsec configuration in the NPM WebUI. As a rule of thumb only adjust stuff for which there’s no UI element yet to configure it and be aware that e.g. disabling open-appsec in a “Proxy Host” or “Custom Location” might also remove the corresponding configuration from the open-appsec Configuration File.

Check out the open-appsec documentation if you want to learn more about all the additional options and security layers which are available in open-appsec: docs.openappsec.io

PreviousNGINX Proxy Manager Integration NextInstall NGINX Proxy Manager with open-appsec managed from central WebUI (SaaS)

Last updated 3 months ago