open-appsec
WebsiteManagement PortalPlaygroundGitHub
  • open-appsec Documentation
  • What is open-appsec?
  • open-appsec Video Tutorials
  • Release Notes
  • Getting started
    • Getting Started
    • Start With Kubernetes
      • Install Using Interactive CLI Tool (Ingress NGINX)
      • Configuration Using Interactive CLI Tool
      • Install Using Helm
      • Install Using Helm - new flow (beta)
      • Configuration Using CRDs
      • Configuration Using CRDs - v1beta2
      • Configuration using CRDs - special options for Large Scale Deployments
        • Using appsec class for assigning separate custom resources to specific deployments
        • Using namespace-scoped custom resources
      • Monitor Events
    • Start With Linux
      • Install open-appsec for Linux
      • Using the open-appsec-ctl Tool
      • Configuration Using Local Policy File (Linux)
      • Local Policy File (Advanced)
      • Local Policy File v1beta2 (beta)
      • Monitor Events
    • Start with Docker
      • Install With Docker (Centrally Managed)
      • Install With Docker (Locally Managed)
      • Deploy With Docker-Compose (Beta)
      • Configuration Using Local Policy File (Docker)
      • Local Policy File (Advanced)
    • Using the Web UI (SaaS)
      • Sign-Up and Login to Portal
      • Agents Deployment
      • Connect Deployed Agents to SaaS Management Using Tool (K8s & Linux)
      • Connect Deployed Agents to SaaS Management Using Helm (K8s)
      • Connect Deployed Agents to SaaS Management (Docker)
      • Create a Profile
      • Protect Additional Assets
      • Monitor Events
    • Using the Advanced Machine Learning Model
  • Concepts
    • Agents
    • Management & Automation
    • Security Practices
    • Contextual Machine Learning
  • SETUP INSTRUCTIONS
    • Setup Web Application Settings
    • Setup Custom Rules and Exceptions
    • Setup Web User Response Pages
    • Setup Log Triggers
    • Setup Behavior Upon Failure
    • Setup Agent Upgrade Schedule
  • Additional Security Engines
    • Anti-Bot
    • API Schema Enforcement
    • Data Loss Prevention (DLP) Rules
    • File Security
    • Intrusion Prevention System (IPS)
    • Rate Limit
  • Snort Rules
    • Import Snort Rules
    • Write Snort Signatures
  • HOW TO
    • Configuration and Learning
      • Track Learning and Move From Learn/Detect to Prevent
      • Configure Contextual Machine Learning for Best Accuracy
      • Track Learning and Local Tuning in Standalone Deployments
      • Move From Detect to Prevent in K8s With Many Ingress Rules
  • Deployment and Upgrade
    • Load the Attachment in Proxy Configuration
    • Upgrade Your Reverse Proxy/API Gateway When an Agent is Installed
    • Integration in GitOps CD (K8s)
    • Build open-appsec Based on Source Code
  • Management Web UI
    • Track Agent Status
    • Delete or Reset Management Tenant (SaaS)
    • Disconnect an open-appsec agent from Central Management
  • Integrations
    • About Integrations With 3rd Party Solutions
    • CrowdSec
      • CrowdSec Bouncer Support
      • CrowdSec Intelligence Sharing Using open-appsec Parser/Scenario
    • NGINX Proxy Manager
      • Install NGINX Proxy Manager with open-appsec managed from NPM WebUI
      • Install NGINX Proxy Manager with open-appsec managed from central WebUI (SaaS)
      • Frequently Asked Questions
      • How to Migrate from an Existing NGINX Proxy Manager Deployment and Keep Configuration
    • NPMplus
    • Docker SWAG
      • Install Docker SWAG with open-appsec (locally managed)
      • How to connect locally managed Docker SWAG with open-appsec to WebUI
      • Install Docker SWAG with open-appsec (centrally managed)
      • Deploy Docker SWAG with docker-compose (beta)
      • Frequently Asked Questions
  • Troubleshooting
    • Troubleshooting
    • Troubleshooting Guides
      • Configuration contains ingress/asset with URL which already has asset attached to it in your tenant
      • HTTP Request to Port 80 Not Returning as Expected
      • Agent Fails to Recognize HTTP Transactions with NGINX
      • Agent Not Recognizing Initial HTTP Requests
      • Handling Large Requests (413 Responses)
      • open-appsec on Docker HTTP Transaction Handler Is Set To Ready
      • Traffic Recognition Issue on Single-Core Machine/Connection Timed Out
      • Installing open-appsec on CentOS 7
      • SELinux: checking status and disabling
      • Deploy open-appsec directly on the web server hosting the application to protect
      • object is locked or remote, and therefore cannot be modified
      • Failed to Register to Fog
  • references
    • Agent CLI
    • Event Query Language
    • Events/Logs Schema
    • WAF Comparison Project
Powered by GitBook
On this page
  • About the integration of NPMplus with open-appsec
  • To deploy NPMplus with open-appsec integration follow the steps below:
  • Prerequisites
  • Deployment
  • Recommended next steps:
  • Configure NPMplus:
  • Configure open-appsec WAF:

Was this helpful?

  1. Integrations

NPMplus

PreviousHow to Migrate from an Existing NGINX Proxy Manager Deployment and Keep ConfigurationNextDocker SWAG

Last updated 3 months ago

Was this helpful?

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.

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

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

Deployment

  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
compose.yaml content
services:
  npmplus:
    container_name: npmplus
    image: docker.io/zoeyvid/npmplus:latest # or ghcr.io/zoeyvid/npmplus:latest
    restart: always
    network_mode: host
#    ipc: service:openappsec-agent # required when you want to use the openappsec attachment module
#    privileged: true # required if you set NGINX_QUIC_BPF to true
    volumes:
      - "/opt/npmplus:/data"
#      - "/var/www:/var/www" # optional, if you want to use NPMplus directly as webserver for html/php
#      - "/path/to/old/npm/letsencrypt/folder:/etc/letsencrypt" # Only needed for first time migration from original nginx-proxy-manager to this fork
    environment:
      - "TZ=your-timezone" # set timezone, required, set it to one of the values from the "TZ identifier" https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
      - "ACME_EMAIL=your-email" # email address which should be used for acme, currently optional, may be required in the future, so I recommend you to enter your email here, optional for letsencrypt, but required for zerossl and google public ca
#      - "ACME_SERVER=https://dv.acme-v02.api.pki.goog/directory (google public ca) / https://acme.zerossl.com/v2/DV90 (zerossl)" # acme server used when requesting/renewing certs using certbot, default is set to: https://acme-v02.api.letsencrypt.org/directory (letsencrypt)
#      - "ACME_EAB_KID=123456789abcdef" # Key Identifier for External Account Binding for the acme server, not supported by letsencrypt, optional for zerossl (Login on theier site => Developer), but required for google public ca: https://cloud.google.com/certificate-manager/docs/public-ca-tutorial?hl=de#request-key-hmac
#      - "ACME_EAB_HMAC_KEY=123456789abcdef" # HMAC key for External Account Binding for the acme server, not supported by letsencrypt, optional for zerossl (Login on theier site => Developer), but required for google public ca: https://cloud.google.com/certificate-manager/docs/public-ca-tutorial?hl=de#request-key-hmac
#      - "ACME_MUST_STAPLE=true" # enables must-staple, default false, I recommend you to enable this if your CA supports it, supported by zerossl, google public ca ignores this, unsupported by letsencrypt (will fail)
#      - "ACME_OCSP_STAPLING=false" # enables ocsp stapling, default true, I recommend you to enable this if your CA supports it, supported by zerossl and google public ca, unsupported by letsencrypt certs created after May 7, 2025 (will create warning in your log, default value will change then)
#      - "ACME_KEY_TYPE=rsa" # which key type to use ecdsa or rsa, default and recommended: ecdsa
#      - "ACME_SERVER_TLS_VERIFY=false" # enables checking if ACME_SERVER has a valid TLS cert, default true
#      - "CUSTOM_OCSP_STAPLING=true" # enables ocsp stapling for custom certs, default false, I recommend you to enable this if your custom certs support it
#      - "NGINX_LOAD_OPENAPPSEC_ATTACHMENT_MODULE=true" # loads the openappsec attachment module, you also need to set ipc for NPMplus in this composse file
#      - "PUID=1000" # set group id, needs to be a number greater or equal to 99, or equal to 0, default 0 (root)
#      - "PGID=1000" # set user id, needs to be a number greater or equal to 99, or equal to 0, default 0 (root), requires PUID to be not 0
#      - "NIBEP=48682" # internal port of the NPMplus API, always bound to 127.0.0.1, default 48681, you need to change it, if you want to run multiple npm instances in network mode host
#      - "GOAIWSP=48692" # internal port of goaccess, always bound to 127.0.0.1, default 48691, you need to change it, if you want to run multiple npm with goaccess instances in network mode host
#      - "NPM_PORT=82" # Port the NPM UI should be bound to, default 81, you need to change it, if you want to run multiple npm instances in network mode host
#      - "GOA_PORT=92" # Port the goaccess should be bound to, default 91, you need to change it, if you want to run multiple npm with goaccess instances in network mode host
#      - "IPV4_BINDING=127.0.0.1" # IPv4 address to bind, defaults to all
#      - "NPM_IPV4_BINDING=127.0.0.1" # IPv4 address to bind for the NPM UI, defaults to all
#      - "GOA_IPV4_BINDING=127.0.0.1" # IPv4 address to bind for the goaccess, defaults to all
#      - "IPV6_BINDING=[::1]" # IPv6 address to bind, defaults to all
#      - "NPM_IPV6_BINDING=[::1]" # IPv6 address to bind for the NPM UI, defaults to all
#      - "GOA_IPV6_BINDING=[::1]" # IPv6 address to bind for goaccess, defaults to all
#      - "DISABLE_IPV6=true" # fully disables listing on IPv6 and the IPv6 resolver of nginx, overrides IPV6_BINDING/NPM_IPV6_BINDING/GOA_IPV6_BINDING, default false
#      - "NPM_LISTEN_LOCALHOST=true" # Binds the NPM UI only to localhost, overrides NPM_IPV4_BINDING/NPM_IPV6_BINDING, default false
#      - "GOA_LISTEN_LOCALHOST=true" # Binds goaccess only to localhost, overrides NPM_IPV4_BINDING/NPM_IPV6_BINDING, default false
#      - "DEFAULT_CERT_ID=1" # ID of cert, which should be used instead of dummycerts, default 0/unset/dummycerts
#      - "HTTP_PORT=8080" # tcp port to use for http traffic, changing this may breaks certbot http challenge, default 80
#      - "HTTPS_PORT=8443" # udp and tcp port to use for https traffic, this also needs to be changed if you don't use network_mode host to keep http3/quic working, changing this may breaks certbot http challenge, default 443
#      - "DISABLE_HTTP=true" # disables nginx to listen on port 80, default false
#      - "DISABLE_H3_QUIC=true" # disables nginx to listen on port 443 udp for default host and all your hosts, this will fully disable HTTP/3 and QUIC, even if you enable it inside the UI, not recommended, default false
#      - "NGINX_QUIC_BPF=true" # enables nginxs quic_bpf (https://nginx.org/en/docs/http/ngx_http_v3_module.html#quic_bpf), you also need to to give the NPMplus container privileged permissions to use this, default false
#      - "NGINX_LOG_NOT_FOUND=true" # Allow logging of 404 errors, default false
#      - "NGINX_404_REDIRECT=true" # Redirect to / instead of showing a 404 error page, default false
#      - "NGINX_HSTS_SUBDMAINS=false" # when enabling security headers, also enable hsts for subdomains, default true
#      - "X_FRAME_OPTIONS=sameorigin" # value to use for the X-Frame-Options header when enabling security headers, valid is deny, sameorigin and none (means unset), default deny, since this applies to all hosts I recommend you to instead keep the default and only change it for hosts which need it using the advanced config and more_set_headers
#      - "NGINX_DISABLE_PROXY_BUFFERING=true" # Disables the proxy_buffering/proxy_request_buffering options of nginx, default false, may not work if you use crowdsec/appsec
#      - "NGINX_WORKER_PROCESSES=8" value of worker_processes, default and recommended: auto
#      - "DISABLE_NGINX_BEAUTIFIER=true" # disables nginxbeautifier, useful when it fails parsing non-standard configs, default false
#      - "FULLCLEAN=true" # Clean unused config folders, default false
#      - "SKIP_IP_RANGES=true" # Skip feteching/whitelisting ip ranges from aws and cloudflare, default false
#      - "LOGROTATE=true" # Enables writing http access logs to /opt/npmplus/nginx/access.log, stream access logs to /opt/npmplus/nginx/stream.log and enables daily logrotation, default false
#      - "LOGROTATIONS=7" # Set how often the access.log should be rotated until it is deleted, default 3
#      - "CRT=36" # Set how many hours should be between certbot trying to renew your certs, default 24
#      - "IPRT=3" # Set how many hours should be between updating ip ranges from aws and cloudflare, default 1, ignored when SKIP_IP_RANGES is true
#      - "GOA=true" # Enables goaccess, requires LOGROTATE, default false --- if you download the GeoLite2-Country.mmdb, GeoLite2-City.mmdb AND GeoLite2-ASN.mmdb file from MaxMind and place them in /opt/npmplus/goaccess/geoip it will automatically enable GeoIP in goaccess after restarting NPMplus (no need to change GOACLA below), you may also enable the geoipupdate container below (please change the timezone)
#      - "GOACLA=--agent-list --real-os --double-decode --anonymize-ip --anonymize-level=2 --keep-last=7 --with-output-resolver --no-query-string" # Arguments that should be passed to goaccess, default: --agent-list --real-os --double-decode --anonymize-ip --anonymize-level=1 --keep-last=30 --with-output-resolver --no-query-string
#      - "PHP82=true" # Activate PHP82, default false
#      - "PHP82_APKS=php82-curl php82-openssl" # Add php extensions, see available packages here: https://pkgs.alpinelinux.org/packages?branch=v3.21&repo=community&arch=x86_64&name=php82-*, default none, requires PHP82
#      - "PHP83=true" # Activate PHP83, default false
#      - "PHP83_APKS=php83-curl php83-openssl" # Add php extensions, see available packages here: https://pkgs.alpinelinux.org/packages?branch=v3.21&repo=community&arch=x86_64&name=php83-*, default none, requires PHP83
#      - "PHP84=true" # Activate PHP84, default false
#      - "PHP84_APKS=php84-curl php84-openssl" # Add php extensions, see available packages here: https://pkgs.alpinelinux.org/packages?branch=v3.21&repo=community&arch=x86_64&name=php84-*, default none, requires PHP84
#      - "PHP_APKS=php-pecl-apcu php-pecl-redis" # Add php extensions, see available packages here: https://pkgs.alpinelinux.org/packages?branch=v3.21&repo=community&arch=x86_64&name=php-*, default none, requires PHP82, PHP83 and/or PHP84, not recommended, please use PHP82_APKS, PHP83_APKS or PHP84_APKS
#      - "INITIAL_ADMIN_EMAIL=initial-email" # email to use instead of admin@example.org on first start of NPMplus for the initial user
#      - "INITIAL_ADMIN_PASSWORD=initial-password" # password to use instead of iArhP1j7p1P6TA92FA2FMbbUGYqwcYzxC4AVEe12Wbi94FY9gNN62aKyF1shrvG4NycjjX9KfmDQiwkLZH1ZDR9xMjiG2QmoHXi on first start of NPMplus for the initial user
#      - "INITIAL_DEFAULT_PAGE=444" # default page to set on first start of NPMplus for the initial user, default congratulations, can be one of: 404, 444, redirect, congratulations or html

# This can be used with DISABLE_HTTP=true, to force HTTPS redirects for every host
#  npmplus-caddy:
#    container_name: npmplus-caddy
#    image: docker.io/zoeyvid/npmplus:caddy
#    restart: always
#    network_mode: bridge
#    ports:
#      - "80:80"
#    environment:
#      - "TZ=your-timezone"

# This can be used with GOA=true, to keep the geopip database updated, you need to change the envs to make it work
#  geoipupdate:
#    container_name: npmplus-geoipupdate
#    image: docker.io/maxmindinc/geoipupdate:latest
#    restart: always
#    network_mode: bridge
#    environment:
#      - "TZ=your-timezone" # needs to be changed
#      - "GEOIPUPDATE_EDITION_IDS=GeoLite2-Country GeoLite2-City GeoLite2-ASN"
#      - "GEOIPUPDATE_ACCOUNT_ID=<your-account-id>" # needs to be changed
#      - "GEOIPUPDATE_LICENSE_KEY=<your-license-key>" # needs to be changed
#      - "GEOIPUPDATE_FREQUENCY=24"
#    volumes:
#      - "/opt/npmplus/goaccess/geoip:/usr/share/GeoIP"

# This can be used to enable crowdsec, see README for a guide
#  crowdsec:
#    container_name: crowdsec
#    image: docker.io/crowdsecurity/crowdsec:latest
#    restart: always
#    network_mode: bridge
#    ports:
#      - "127.0.0.1:7422:7422"
#      - "127.0.0.1:8080:8080"
#    environment:
#      - "TZ=your-timezone" # needs to be changed
#      - "COLLECTIONS=ZoeyVid/npmplus"
#    volumes:
#      - "/opt/crowdsec/conf:/etc/crowdsec"
#      - "/opt/crowdsec/data:/var/lib/crowdsec/data"
#      - "/opt/npmplus/nginx:/opt/npmplus/nginx:ro"
#      - "/var/run/docker.sock:/var/run/docker.sock:ro"

# This can be used to run openappsec, you also need to set NGINX_LOAD_OPENAPPSEC_ATTACHMENT_MODULE to true and set ipc for NPMplus
#  openappsec-agent:
#    container_name: openappsec-agent
#    image: ghcr.io/openappsec/agent:latest
#    restart: always
#    ipc: shareable
#    volumes:
#      - "/opt/openappsec/conf:/etc/cp/conf"
#      - "/opt/openappsec/data:/etc/cp/data"
#      - "/opt/openappsec/logs:/var/log/nano_agent"
#      - "/opt/openappsec/localconf:/ext/appsec" # if you don't set AGENT_TOKEN, then please put a local_policy.yaml in the /opt/openappsec/localconf folder before deploying
#      - "/opt/openappsec/open-appsec-advanced-model.tgz:/advanced-model/open-appsec-advanced-model.tgz" # optional, if you want to use a different model
#    environment:
#      - "TZ=your-timezone" # needs to be changed
#      - "autoPolicyLoad=true"
#      - "registered_server=NPMplus"
#      - "user_email=your-email" # optional, not sure what they do exactly with it, but it should work fine without it
#      - "AGENT_TOKEN=abc" # optional, can be set if you use theier webinterface, if you leave this commented, please uncomment all other openappsec containers below, see: https://docs.openappsec.io/getting-started/using-the-web-ui-saas/create-a-profile
#      - "SHARED_STORAGE_HOST=openappsec-shared-storage" # uncomment if you don't set AGENT_TOKEN
#      - "LEARNING_HOST=openappsec-smartsync" # uncomment if you don't set AGENT_TOKEN
#      - "TUNING_HOST=openappsec-tuning-svc" # uncomment if you don't set AGENT_TOKEN
#    command: /cp-nano-agent

# uncomment if you don't set AGENT_TOKEN
#  openappsec-smartsync:
#    container_name: openappsec-smartsync
#    image: ghcr.io/openappsec/smartsync:latest
#    restart: always
#    environment:
#      - "TZ=your-timezone" # needs to be changed
#      - "SHARED_STORAGE_HOST=openappsec-shared-storage"
#    depends_on:
#      - openappsec-shared-storage
#  openappsec-shared-storage:
#    container_name: openappsec-shared-storage
#    image: ghcr.io/openappsec/smartsync-shared-files:latest
#    restart: always
#    ipc: service:openappsec-agent
#    user: root # if you do not want to run this container as "root" user you can comment it out and instead run the following command after the deployment: docker exec -u root openappsec-shared-storage chown -R appuser:appuser /db
#    environment:
#      - "TZ=your-timezone" # needs to be changed
#    volumes:
#      - "/opt/openappsec/storage:/db"
#  openappsec-tuning-svc:
#    container_name: openappsec-tuning-svc
#    image: ghcr.io/openappsec/smartsync-tuning:latest
#    restart: always
#    environment:
#      - "TZ=your-timezone" # needs to be changed
#      - "SHARED_STORAGE_HOST=openappsec-shared-storage"
#      - "QUERY_DB_HOST=openappsec-db"
#      - "QUERY_DB_PASSWORD=password" # replace with something secure, should match POSTGRES_PASSWORD from openappsec-db container
#      - "QUERY_DB_USER=appsec"
#    volumes:
#      - "/opt/openappsec/conf:/etc/cp/conf"
#    depends_on:
#      - openappsec-shared-storage
#      - openappsec-db
#  openappsec-db:
#    image: postgres
#    container_name: openappsec-db
#    restart: always
#    environment:
#      - "TZ=your-timezone" # needs to be changed
#      - "POSTGRES_PASSWORD=password" # replace with something secure, should match QUERY_DB_PASSWORD from openappsec-tuning-svc container
#      - "POSTGRES_USER=appsec"
#    volumes:
#      - "/opt/openappsec/pgdb:/var/lib/postgresql/data"
  • 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"
  • 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:

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

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

Configure open-appsec WAF:

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

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!

Learn more about NPMplus and the steps for "Quick Setup" with Docker Compose in the project's GitHub repo:

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

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

To deploy open-appsec with docker-compose and optionally connect to the central WebUI available at follow the steps below:

Set it to one of the values from the "TZ identifier"

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

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

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 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://github.com/ZoeyVid/NPMplus?tab=readme-ov-file#quick-setup
https://github.com/ZoeyVid/NPMplus
https://github.com/ZoeyVid
https://github.com/ZoeyVid/NPMplus
https://my.openappsec.io
Sign-Up and Login to Portal
Create a Profile
https://my.openappsec.io
https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
https://raw.githubusercontent.com/openappsec/openappsec/main/config/linux/v1beta1/detect/local_policy.yaml
https://nginxproxymanager.com
https://my.openappsec.io
https://my.openappsec.io
https://github.com/ZoeyVid/NPMplus
https://github.com/NginxProxyManager/nginx-proxy-manager
NPMplus Dashboard