top of page
Christopher Lutat
Dec 28, 20239 min read

Announcing open-appsec WAF Integration with NGINX Proxy Manager

How to easily 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 open-appsec team is excited to announce the beta release of a new integration of open-appsec WAF with NGINX Proxy manager. This will allow NGINX Proxy Manager (NPM) users 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 also to monitor security events.

 

This new integration of open-appsec WAF with NGINX Proxy Manager not only closes the security gap caused by the missing WAF security layer in NGINX Proxy Manager, but provides strong, cutting-edge WAF protection in form of open-appsec, a preemptive, machine-learning based, fully automatic WAF that does not rely on signatures at all.


NGINX Proxy Manager and open-appsec are both open-source solutions.


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


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.



About open-appsec WAF

open-appsec WAF provides automatic, preemptive threat prevention for reverse proxies like NGINX. It is machine learning based, which means it doesn’t require signatures (or updating them) at all. This enables it to provide state-of-the-art threat prevention even for true zero-day attacks while significantly reducing both, administrative effort as well as the amount of false-positives. open-appsec therefore is a great fit to provide advanced threat prevention to the services exposed by NGINX Proxy Manager.


 

Integration of open-appsec 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.


Code for this open-appsec NPM integration is available in Github: https://www.github.com/openappsec/open-appsec-npm


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 Step-by-Step

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


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:

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

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

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


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

docker compose up -d

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

docker ps

Now you are all set and 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 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 for 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”.


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.


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

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



How to configure open-appsec advanced settings:

Note: 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”.


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 disabling open-appsec in a “Proxy Host” or “Custom Location” might also remove the corresponding configuration from the open-appsec Configuration File. It might also be a good idea to perhaps do a backup of the open-appsec configuration shown here once in a while.

 

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


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



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’s basic settings directly from within the NPM WebUI and view security logs.


It works in the way that whenever you do any changes for the open-appsec configuration from within the NPM WebUI those are saved in the /ext/appsec folder in the local_policy.yaml file.


This configuration file is volume-mounted (see docker compose file) 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 and 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 be passed.


Frequently Asked Questions


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


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


Example:


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


A: 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: 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.0-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.0-open-source, Created at: 2023-10-05T17:46:48+0000

Status: Running

 

---- open-appsec Attachment Registrator Nano Service ----

Type: Public, Version: 1.1.0-open-source, Created at: 2023-10-05T17:46:48+0000

Status: Running

 

---- open-appsec Http Transaction Handler Nano Service ----

Type: Public, Version: 1.1.0-open-source, Created at: 2023-10-05T17:46:48+0000

Registered Instances: 2

Status: Running


Q: I like this project and want to contribute to it myself, can I?


A: Yes of course! We are looking forward to receiving your contributions via the project’s GitHub repo https://github.com/openappsec/open-appsec-npm, 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.

 

We hope this integration will be useful for you and provide you easy-to-configure yet highly effective protection based on open-appsec for your web services or web APIs against known and especially unknown, zero day attacks!

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


More information is available here:

open-appsec NGINX Proxy Manager Integration


open-appsec


NGINX Proxy Manager

 

 

 

open-appsec is an open-source project that builds on machine learning to provide pre-emptive web app & API threat protection against OWASP-Top-10 and zero-day attacks. It simplifies maintenance as there is no threat signature upkeep and exception handling, like common in many WAF solutions.


To learn more about how open-appsec works, see this White Paper and the in-depth Video Tutorial. You can also experiment with deployment in the free Playground.


Experiment with open-appsec for Linux, Kubernetes or Kong using a free virtual lab

bottom of page