Website Management Portal Playground GitHub

NGINX Proxy Manager Integration

Deploy and configure open-appsec ML-based WAF integrated with NGINX Proxy Manager to preemptively protect your web apps and APIs against zero-day attacks and OWASP Top 10 attacks.

The NGINX Proxy Manager integration is currently in "beta" stage.

Here we explain how to deploy and use the new integration of open-appsec WAF with NGINX Proxy manager. This enables users of the NGINX Proxy Manager (NPM) to protect their web applications and web APIs exposed by NGINX Proxy Manager by easily activating and configuring open-appsec protection for each of the configured Proxy Host objects in NPM directly from the NPM Web UI and monitor security events.

This new integration of open-appsec WAF with NGINX Proxy Manager not only closes the security gap caused by the soon end-of-life ModSecurity WAF, but provides a modern, even stronger protection alternative in form of open-appsec, a preemptive, machine-learning based, fully automatic WAF that does not rely on signatures at all.

About NGINX Proxy Manager:

Nginx Proxy Manager is a popular open-source project that simplifies the management of NGINX reverse proxy configurations, offering a user-friendly web-based interface for easy setup and maintenance. It was created by “jc21” (https://www.jc21.com/). This project is particularly useful for individuals and organizations looking to streamline the deployment of web applications and services by efficiently managing multiple domains and subdomains through a centralized interface. With NGINX Proxy Manager, users can effortlessly create and manage SSL certificates, enabling secure HTTPS connections for their applications, while also providing advanced features such as Let's Encrypt integration for automated certificate renewal. NGINX Proxy Manager (NPM) is based on NGINX and provided as a container image that can be easily deployed in containerized environments like Docker (typically using Docker Compose) or others. NPM itself does not include any WAF solution for effective Threat Prevention against modern attacks or Zero day attacks. Website and Docs: nginxproxymanager.com Github: www.github.com/NginxProxyManager

Integration of open-appsec WAF with NGINX Proxy Manager:

With this integration we are focusing on maximum simplicity for the user to maintain the low entry barrier as a key design principle of the NGINX proxy manager (NPM) project, which we want in the same way to apply also to the addition of open-appsec.

The actual deployment of NPM with open-appsec is performed using a slightly enhanced docker compose file (see below) which also adds the open-appsec agent container to it, which will perform the actual security inspection. The NGINX proxy manager container deployed as part of the docker compose is using the “open-appsec-npm” image, provided by the open-appsec team, which is based on the regular NPM code but also adds the open-appsec attachment to it as an NGINX module. This attachment enables the connection between the NGINX and the open-appsec agent and provides the HTTP data for inspection to the Agent. The “open-appsec-npm” container also contains various NPM WebUI enhancements and the integration logic allowing the configuration, administration and monitoring of open-appsec. You can read more about open-appsec’s technology here: https://www.openappsec.io/tech

After successful deployment you can then activate and configure open-appsec directly from the enhanced NPM Web UI interface to which the most relevant configuration options for the open-appsec WAF as well as an option to view the open-appsec logs have been added.

The resulting architecture with the open-appsec Agent container and the NGINX Proxy Manager container then looks like this:

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

  1. 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/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/docker-compose.yaml

docker-compose.yaml content:

version: '3.3'
# docker compose for npm open-appsec integration

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

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

  2. Run docker-compose up to start the deployment of all relevant containers:

docker-compose up -d

  1. 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://nginx-proxy-manager.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):

  1. Enable open-appsec by flipping the “open-appsec” switch to enabled.

  2. Select the Enforcement Mode, it can be either “Prevent-Learn” or “Detect-Learn”

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

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

How does this integration work?

open-appsec was developed from the start in a way that would allow two alternative main ways of managing the open-appsec configuration:

  • a user-friendly WebUI for central management (available at my.openappsec.io as a SaaS service)

  • a local declarative configuration which is especially suitable for GitOps CD processes, Dev(Sec)Ops flows, etc.

With the new open-appsec NGINX Proxy Manager (NPM) integration now there’s an additional way to manage open-appsec directly from within the NPM WebUI.

It works in the way that whenever you do any changes for the open-appsec configuration those are saved in the /ext/appsec folder in the local_policy.yaml file. This configuration file is volume-mounted (see docker compose) to both, the open-appsec agent container “appsec-agent” as well as the NPM container “appsec-npm”. This allows the open-appsec agent to automatically apply any changes observed in that file within short time.

In order to allow the open-appsec agent to inspect traffic arriving at the NPM (NGINX) container an open-appsec “attachment” was added to the original NPM container, which technically is an NGINX module which is loaded based on a load_module directive added to the nginx.conf. This “attachment” is responsible for sending the content of incoming http as well as https requests to the open-appsec “agent” container, which will perform the inspection using machine learning and then notify the attachment about the decision, if traffic should be blocked or if it can pass.

Frequently asked questions:

Question: How can I test if open-appsec detects/prevents attacks correctly after enabling it for one of my proxy host objects in NGINX Proxy Manager?

You can append the following to your http(s) requests to simulate an attack which should be detected/prevented by open-appsec: ?shell_cmd=cat/etc/passwd Example: http://localhost/?shell_cmd=cat/etc/passwd

Question: How can I check the status of my open-appsec agent?

You can run the command open-appsec-ctl -s inside the appsec-agent container: docker exec appsec-agent open-appsec-ctl -s Status should be “running” for all services in the list and "Policy load status" should show "Success". Note that the Http Transaction Handler Nano Service will only switch from “ready” to “running” state after it has received some initial packets from the attachment integrated with the NPM Nginx reverse proxy. Here’s an example output:

---- open-appsec Nano Agent ----
Version: 1.1.3-open-source
Status: Running
Management mode: Local management
Policy files:
    /etc/cp/conf/local_policy.yaml
Policy load status: Success
Last policy update: 2023-12-04T11:33:46.083483
AI model version: Simple model V1.0

---- open-appsec Orchestration Nano Service ----
Type: Public, Version: 1.1.3-open-source, Created at: 2023-10-05T17:46:48+0000
Status: Running

---- open-appsec Attachment Registrator Nano Service ----
Type: Public, Version: 1.1.3-open-source, Created at: 2023-10-05T17:46:48+0000
Status: Running

---- open-appsec Http Transaction Handler Nano Service ----
Type: Public, Version: 1.1.3-open-source, Created at: 2023-10-05T17:46:48+0000
Registered Instances: 2
Status: Running

Question: How can I migrate from an existing installation of NGINX Proxy Manager (NPM) to NPM integrated with open-appsec and keep my existing NPM configuration?

To migrate from an existing NGINX Proxy Manager installation to the version which provides also the open-appsec integration here's some guidance:

This is only relevant if you want to keep your existing NGINX Proxy Manager configuration, otherwise we suggest to start fresh with the deployment instructions further above on this page.

Note that the specific steps can vary based on customizations that you might have done to the original NGINX Proxy Manager's docker compose file.

The below is assuming you did a deployment by using the default docker-compose.yml file as shown here: https://nginxproxymanager.com/setup/#running-the-app .

  • Change into your existing folder that contains the docker-compose.yml file and all related files and folders for your current NGINX Proxy Manager deployment.

  • Stop your current deployment with docker compose down in the folder that contains your docker-compose.yaml file used for the NGINX Proxy Manager deployment

  • Make a full backup of your existing folder that contains the NGINX Proxy Manager docker compose environment, including any mounted volumes like ./data and ./letsencrypt, etc. to a safe location. This will allow you to bring it up with docker-compose up later exactly as it was before the migration, if required for some reason.

  • Rename the original docker-compose.yml (or docker-compose.yaml, whatever you called it) to docker-compose.orig.yaml.

  • 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

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

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

  • Create the new docker-compose.yaml file for the open-appsec NGINX Proxy Manager integration:

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

  • 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

  • If you did any special changes to the original docker-compose.yml file now is the time to apply these also to the docker-compose.yaml file for the open-appsec NPM integration you just downloaded/created in step 3 of the deployment instructions. For this compare the new docker-compose.yaml with the renamed docker-compose.orig.yaml file.

  • Below find the relevant folders typically containing the persistent configuration of NGINX Proxy (NPM) Manager, they will also be mounted as part of the open-appsec NPM integration docker-compose.yaml so that all your existing configuration should be kept. Only if for some reason you changed the local folder locations for these specific docker volume mounts in the past, please make sure to adjust those as well in the new docker-compose.yaml file for the open-appsec NGINX Proxy Manager integration.

    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt

Your existing NGINX Proxy Manager (and Let's Encrypt) configuration will still be available also once migrated to the open-appsec enhanced NGINX Proxy Manager deployment as long as it still resides in the local ./data and ./letssencrypt folders (see relevant excerpt from the docker-compose.yaml file below).

  • Run docker-compose up to start the deployment of all relevant containers:

    docker-compose up -d

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

    docker ps

  • Now you can login with your web browser to the WebUI of the NGINX Proxy Manager (NPM) with open-appsec integration as follows: (Note that as you kept your existing NPM configuration your existing user credentials for the login should also still work.)

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

Congratulations, you successfully migrated your existing NGINX Proxy Manager deployment to the NGINX Proxy Manager integrated with open-appsec.

Contribution

We are looking forward to receiving your contributions via the project’s GitHub repo. Please also let us know via info@openappsec.io if you intend to contribute in some way so we can provide you some initial feedback and perhaps align with some improvements we might be already working on on our side.

If you have any questions, feedback or need assistance with some technical issue please contact us at info@openappsec.io or alternatively use the chat on our project website available at www.openappsec.io.

PreviousCrowdSec Intelligence Sharing Using open-appsec Parser/ScenarioNextTroubleshooting

Last updated