# 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: \ NGINX Proxy Manager project on GitHub: ## 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. ```yaml 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: ```yaml 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: {% hint style="info" %} This integration of open-appsec WAF and NPMplus is not directly maintained by the open-appsec team, you find the relevant repo here: \ Project maintainers:\ \ \ \ 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). {% endhint %} 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 : {% content-ref url="../getting-started/using-the-web-ui-saas/sign-up-and-login-to-portal" %} [sign-up-and-login-to-portal](https://docs.openappsec.io/getting-started/using-the-web-ui-saas/sign-up-and-login-to-portal) {% endcontent-ref %} * **(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.** {% content-ref url="../getting-started/using-the-web-ui-saas/create-a-profile" %} [create-a-profile](https://docs.openappsec.io/getting-started/using-the-web-ui-saas/create-a-profile) {% endcontent-ref %} ## Deployment #### To deploy open-appsec with docker-compose and optionally connect to the central WebUI available at follow the steps below: 1. Create a folder for your new open-appsec deployment and switch to that folder, e.g. ```bash mkdir open-appsec-deployment cd ./open-appsec-deployment ``` 2. Download the docker compose file for NPMplus which includes the open-appsec integration and adjust the configuration: ```bash wget https://raw.githubusercontent.com/ZoeyVid/NPMplus/develop/compose.yaml ``` {% embed url="" %} * **Configure loading of the open-appsec attachment module** in npmplus by uncommenting the relevant environment variable in the npmplus container configuration: ```yaml 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: ```yaml 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):
```yaml - "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!):
```yaml # - "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: ```yaml - "TZ=Europe/Berlin" ``` Set it to one of the values from the "TZ identifier"\ * **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: ```yaml - "ACME_EMAIL=user@email.com" ``` * **Configure email for open-appsec** (optional):\ Associate your email address with your specific deployment of open-appsec WAF by replacing `user@email.com` 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](#prerequisites "mention") above). **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. 3. **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` : ```bash mkdir /opt/openappsec/localconf ``` ```bash wget https://raw.githubusercontent.com/openappsec/openappsec/main/config/linux/v1beta1/prevent/local_policy.yaml -O /opt/openappsec/localconf/local_policy.yaml ``` {% hint style="info" %} This example configuration file is already set to `mode: prevent-learn`so 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.\ \ (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-learn`for better detection accuracy and strongly reduced false positives.\ \ Read more about this here: \ [track-learning-and-move-from-learn-detect-to-prevent](https://docs.openappsec.io/how-to/configuration-and-learning/track-learning-and-move-from-learn-detect-to-prevent "mention") {% endhint %} 4. Perform the deployment ```bash docker-compose up -d ``` Note that the amount of container will vary based between deployments with and without connection to central WebUI. 5. 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. ```bash docker ps ``` **Congratulations, you successfully deployed NPM plus integrated with open-appsec WAF!** {% hint style="info" %} 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](https://docs.openappsec.io/getting-started/using-the-advanced-machine-learning-model "mention") {% endhint %} ## 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: admin@example.org 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

{% hint style="info" %} To learn how to use the WebUI of NPMplus see the NGINX Proxy Manager (NPM) project documentation:\ (NPM usage and configuration will not be explained here). {% endhint %} ### 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 (). * **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](https://docs.openappsec.io/getting-started/using-the-web-ui-saas/protect-additional-assets "mention") {% hint style="warning" %} Don't forget to Enforce policy in the WebUI after you did any changes for those changes to become effective! {% endhint %} * **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](https://docs.openappsec.io/getting-started/start-with-docker/configuration-using-local-policy-file-docker "mention")\ \ 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 . {% hint style="warning" %} 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! {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.openappsec.io/integrations/npmplus.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.