NPMplus

NPMplus is an enhanced fork of the nginx-proxy-manager open-source project and comes as a prebuilt docker image that enables you to easily forward traffic to your websites running at home or otherwise, including free TLS, without having to know too much about Nginx or Certbot. NPMplus adds many additional features and improvements to the original NGINX Proxy Manager project. You find all details on the project's GitHub repo: NPMplus project in GitHub: https://github.com/ZoeyVid/NPMplus NGINX Proxy Manager project on GitHub: https://github.com/NginxProxyManager/nginx-proxy-manager

About the integration of NPMplus with open-appsec

NPMplus provides native integration with open-appsec WAF starting from NPMplus version 2025-01-26-r1 and higher.

The npmplus container already includes the open-appsec attachment natively, if you want to protect your NPMplus with open-appsec WAF please make sure to activate loading of the attachment module as follows using the relevant environment variable in the NPMplus compose.yaml file.

environment:
- "NGINX_LOAD_OPENAPPSEC_ATTACHMENT_MODULE=true"

Also make sure to uncomment this line in the npmplus service to allow the open-appsec attachment module to communicate with the openappsec-agent container:

ipc: service:openappsec-agent # required when you want to use the openappsec attachment module

Learn more about NPMplus and the steps for "Quick Setup" with Docker Compose in the project's GitHub repo: https://github.com/ZoeyVid/NPMplus?tab=readme-ov-file#quick-setup

This integration of open-appsec WAF and NPMplus is not directly maintained by the open-appsec team, you find the relevant repo here: https://github.com/ZoeyVid/NPMplus Project maintainers: https://github.com/ZoeyVid https://github.com/ZoeyVid/NPMplus As the NPMplus project is actively maintained make sure to also check out the NPMplus project repo for latest changes, updates and documentation as well (see also comments in the compose.yaml file).

Below you find the full deployment steps to get you started with NPMplus and open-appsec WAF integration:

To deploy NPMplus with open-appsec integration follow the steps below:

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:

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 NPMplus which includes the open-appsec integration and adjust the configuration:

wget https://raw.githubusercontent.com/ZoeyVid/NPMplus/develop/compose.yaml

https://raw.githubusercontent.com/ZoeyVid/NPMplus/develop/compose.yamlraw.githubusercontent.com

• Configure loading of the open-appsec attachment module in npmplus by uncommenting the relevant environment variable in the npmplus container configuration:

  environment:
  - "NGINX_LOAD_OPENAPPSEC_ATTACHMENT_MODULE=true"

• Configure IPC for openappsec-agent: Uncomment the following line in the npmplus service to allow the open-appsec attachment module to communicate with the openappsec-agent container:

  ipc: service:openappsec-agent # required when you want to use the openappsec attachment modu

• If you created a deployment profile in the WebUI and copied the Token from it:

  Edit the compose.yaml file and add your token to the env variable AGENT_TOKEN of the openappsec-agent container: Example (add your own token copied from the deployment profile in the open-appsec WebUI):

    - "AGENT_TOKEN=11111-22222222222-333" 

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

  Comment out the following line in the openappsec-agent service definition as shown in the example below: (otherwise you get an error!):

   # - "AGENT_TOKEN=abc" 

  In the compose.yaml file uncomment the lines for the deployment of the following additional services/containers: openappsec-smartsync openappsec-shared-storage openappsec-tuning-svc openappsec-db. These are required only when not connected to the WebUI at all (resulting in standalone, locally, declaratively managed deployment).

• Configure timezone by adjusting TZ environment variable for setting Timezone in npmplus container (Mandatory for successful start of npmplus container!) Do this also in same way for the TZ environment variables of all other containers you are running Example:

  - "TZ=Europe/Berlin"

  Set it to one of the values from the "TZ identifier" https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List

• Configure email for acme by adjusting ACME_EMAIL environment variable for the npmplus container for setting email address for acme, optional for letsencrypt, but required for zerossl and google public ca. Example:

    - "[email protected]" 

• Configure email for open-appsec (optional): Associate your email address with your specific deployment of open-appsec WAF by replacing [email protected] in the user_email parameter in openappsec-agent container with your own email address (more details on email purpose/usage below)

Available environment variables for the openappsec-agent service/container in the compose.yaml file allowing further customization of the deployment:

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

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.

1. If you want to locally, declaratively manage open-appsec with local_policy.yaml file: Download the initial declarative configuration file for open-appsec into the subfolder /opt/openappsec/localconf :

mkdir /opt/openappsec/localconf

wget https://raw.githubusercontent.com/openappsec/openappsec/main/config/linux/v1beta1/prevent/local_policy.yaml -O /opt/openappsec/localconf/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

1. Perform the deployment

docker-compose up -d

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

Congratulations, you successfully deployed NPM plus integrated with open-appsec WAF!

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

Using the Advanced Machine Learning Model

Recommended next steps:

Configure NPMplus:

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:

Email:    [email protected]
Password: iArhP1j7p1P6TA92FA2FMbbUGYqwcYzxC4AVEe12Wbi94FY9gNN62aKyF1shrvG4NycjjX9KfmDQiwkLZH1ZDR9xMjiG2QmoHXi

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:

NPMplus Dashboard

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

Configure open-appsec WAF:

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

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