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
  • Prerequisites
  • Configuration

Was this helpful?

  1. Integrations
  2. NGINX Proxy Manager

Install NGINX Proxy Manager with open-appsec managed from central WebUI (SaaS)

PreviousInstall NGINX Proxy Manager with open-appsec managed from NPM WebUINextFrequently Asked Questions

Last updated 4 months ago

Was this helpful?

Prerequisites

  • Access to a SaaS tenant on my.openappsec.io (WebUI for SaaS management) Follow the instructions available here:

  • Agent profile created for open-appsec Docker deployment in SaaS tenant Follow the instructions available here. Once done, don't forget to copy the profile token after policy installation as this is needed in the installation steps further below:

  • Linux machine with:

    • Docker and Docker Compose installed

    • Root Permissions

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. 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/managed-from-open-appsec-ui/docker-compose.yaml

docker-compose.yaml content:

version: '3.3'
# docker compose for nginx proxy manager open-appsec integration
# open-appsec managed and monitored from central web ui (https://my.openappsec.io)

services:
  appsec-npm:
    container_name: npm-attachment
    image: 'ghcr.io/openappsec/nginx-proxy-manager-centrally-managed-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-agent:
    container_name: appsec-agent
    image: 'ghcr.io/openappsec/agent:latest'
    ipc: host
    restart: unless-stopped
    environment:
      # adjust with your own email below
      - user_email=user@email.com
      - nginxproxymanager=true
    volumes:
      - ./appsec-config:/etc/cp/conf
      - ./appsec-data:/etc/cp/data
      - ./appsec-logs:/var/log/nano_agent
    command: /cp-nano-agent --token <TOKEN>
  1. Replace the <TOKEN> parameter in the docker-compose.yaml file with the token you copied from the profile in the WebUI before (see Prerequisites section above).

  2. Start the deployment of all relevant containers using docker-compose:

docker-compose up -d
  1. Check if the appsec-npm and the appsec-agent containers are up and running:

docker ps

The new version of Docker-Compose deployment for NPM open-appsec integration as documented below is currently in beta status.

This new deployment option with Docker-Compose introduces additional containers in case of a standalone deployment (= deployment without any connection to WebUI). These containers introduce some additional functionality, which is relevant for standalone deployments only (already available when connected to central management WebUI): - Local syncing of learning between open-appsec processes and agents - View learning progress on CLI with open-appsec-tuning-tool - Receive configuration recommendations based on the learning progress using the open-appsec-tuning-tool - Receive tuning suggestions and manage them (approve/reject) using the open-appsec-tuning-tool More details on the open-appsec-tuning-tool here: Track Learning and Local Tuning in Standalone Deployments

Prerequisites

  • Linux Docker Host with root permission

  • Docker-Compose tool installed

  • Create deployment profile for the open-appsec deployment in WebUI Portal 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 your desired open-appsec integration

wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/nginx-proxy-manager-centrally-managed/docker-compose.yaml
docker-compose.yaml file content
# Copyright (C) 2022 Check Point Software Technologies Ltd. All rights reserved.

# Licensed under the Apache License, Version 2.0 (the "License");
# You may obtain a copy of the License at

#     http://www.apache.org/licenses/LICENSE-2.0

# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

##
## Docker compose file for open-appsec integrated with NGINX Proxy Manager
## with open-appsec management via central open-appsec WebUI (SaaS)
##

version: '3.9'

services:
  appsec-agent:
    image: ghcr.io/openappsec/agent:${APPSEC_VERSION}
    container_name: appsec-agent
    ipc: shareable
    restart: unless-stopped
    environment:
      - SHARED_STORAGE_HOST=appsec-shared-storage
      - LEARNING_HOST=appsec-smartsync
      - TUNING_HOST=appsec-tuning-svc
      - https_proxy=${APPSEC_HTTPS_PROXY}
      - user_email=${APPSEC_USER_EMAIL}
      - AGENT_TOKEN=${APPSEC_AGENT_TOKEN}
      - autoPolicyLoad=${APPSEC_AUTO_POLICY_LOAD}
      - nginxproxymanager=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

  appsec-nginx-proxy-manager:
    container_name: appsec-nginx-proxy-manager
    image: ghcr.io/openappsec/nginx-proxy-manager-centrally-managed-attachment:${APPSEC_VERSION}
    ipc: service:appsec-agent
    restart: unless-stopped
    ports:
      - 80:80 # Public HTTP Port
      - 443:443 # Public HTTPS Port
      - 81:81 # Admin Web Port
    volumes:
      - ${NPM_DATA}:/data
      - ${NPM_LETSENCRYPT}:/etc/letsencrypt

  appsec-smartsync:
    profiles:
      - standalone
    image: ghcr.io/openappsec/smartsync:${APPSEC_VERSION}
    container_name: appsec-smartsync
    environment:
      - SHARED_STORAGE_HOST=appsec-shared-storage
    restart: unless-stopped
    depends_on:
      - appsec-shared-storage

  appsec-shared-storage:
    profiles:
      - standalone
    image: ghcr.io/openappsec/smartsync-shared-files:${APPSEC_VERSION}
    container_name: appsec-shared-storage
    ipc: service:appsec-agent
    restart: unless-stopped
## if you do not want to run this container as "root" user you can comment it out and instead run the below command after the deployment
## docker exec -u root appsec-shared-storage chown -R appuser:appuser /db
    user: root
    volumes:
      - ${APPSEC_SMART_SYNC_STORAGE}:/db:z
## instead of using local storage for local learning (see line above)
## you can also configure central nfs storage by configuring nfs volume (uncomment the relevant section at end of this file)
## use a shared nfs storage which is recommended in redundant deployments (uncomment line below, comment out the line above) 
#     - learning_nfs:/db:z

  appsec-tuning-svc:
    profiles:
      - standalone
    image: ghcr.io/openappsec/smartsync-tuning:${APPSEC_VERSION}
    container_name: appsec-tuning-svc
    environment:
      - SHARED_STORAGE_HOST=appsec-shared-storage
      - QUERY_DB_PASSWORD=${APPSEC_DB_PASSWORD}
      - QUERY_DB_HOST=${APPSEC_DB_HOST}
      - QUERY_DB_USER=${APPSEC_DB_USER}
## only relevant when deploying own DB 
#     - SSLMODE:
    restart: unless-stopped
    volumes:
      - ${APPSEC_CONFIG}:/etc/cp/conf
    depends_on:
      - appsec-shared-storage
      - appsec-db
      
  appsec-db:
    profiles:
      - standalone
    image: postgres
    container_name: appsec-db
    restart: unless-stopped
    environment:
      - POSTGRES_PASSWORD=${APPSEC_DB_PASSWORD}
      - POSTGRES_USER=${APPSEC_DB_USER} 
    volumes:
      - ${APPSEC_POSTGRES_STORAGE}:/var/lib/postgresql/data

## example juice-shop backend container (vulnerable webserver, USE ONLY FOR TESTING AND IN LAB ENV)
  juiceshop-backend:
    image: bkimminich/juice-shop:latest
    container_name: juiceshop-backend
    profiles:
      - juiceshop

## advanced configuration: learning_nfs volume for nfs storage in shared_storage container
##
## when configuring nfs storage in shared_storage container configuration above, make sure to also specify learning_nfs volume (see example below for using AWS EFS storage)
##
#volumes:
# learning_nfs:
#   driver: local
#   driver_opts:
#     type: nfs
#     o: addr=fs-abcdef.efs.eu-west-1.amazonaws.com,rw,nfsvers=4.1,rsize=1048576,wsize=1048576,hard,timeo=600,retrans=2,noresvport
#     device: ":/"
  1. Download the .env file for your desired open-appsec integration and adjust the configuration to your requirements as described below:

wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/nginx-proxy-manager-centrally-managed/.env
.env file content
## .env file for docker-compose deployments of open-appsec integrated with NGINX Proxy Manager
## for more info see https://docs.openappsec.io

APPSEC_VERSION=latest
APPSEC_CONFIG=./appsec-config
APPSEC_DATA=./appsec-data
APPSEC_LOGS=./appsec-logs
APPSEC_LOCALCONFIG=./appsec-localconfig

## Make sure the parameter APPSEC_AUTO_POLICY_LOAD is set to false when centrally managing
## open-appsec configuration via open-appsec Web UI.
## You can optionally set it to true when using local, declarative management for open-appsec,
## declarative configuration will then get applied automatically when changed.
APPSEC_AUTO_POLICY_LOAD=false

## Example for configuring HTTPS Proxy:
## APPSEC_HTTPS_PROXY=user:password@proxy_address:port
APPSEC_HTTPS_PROXY=

APPSEC_SMART_SYNC_STORAGE=./appsec-smartsync-storage
APPSEC_USER_EMAIL=user@email.com
APPSEC_DB_PASSWORD=pass
APPSEC_DB_USER=postgres
APPSEC_DB_HOST=appsec-db
APPSEC_POSTGRES_STORAGE=./appsec-postgres-data

# Volume mounts for NGINX Proxy Manager have been moved here as well allowing configuration via .env file 
NPM_DATA=./data
NPM_LETSENCRYPT=./letsencrypt

## To connect your deployment to central open-appsec Web UI provide the token for a profile
## which you created in open-appsec WebUI at https://my.openappsec.io
## Example: APPSEC_AGENT_TOKEN=111-22222-111
APPSEC_AGENT_TOKEN=

## Important: When not providing token for connection to central WebUI:
## Make sure to add the value "standalone" to the COMPOSE_PROFILES value, this will enable
## sharing of learning between processes and allow you to perform tuning locally on CLI
COMPOSE_PROFILES=

## JUICE SHOP DEMO CONTAINER:
## In order to deploy the optional, additional, vulnerable juiceshop container (for demo and testing purposes only!):
## Add the value "juiceshop" to the COMPOSE_PROFILES value above.

## Make sure to also create a new proxy host in the NGINX Proxy Manager WebUI 
## which accepts traffic on http port 80 and proxies traffic to juiceshop-backend on port 3000.
## note that juiceshop container listens on HTTP port 3000 by default

## Note that COMPOSE_PROFILES can also receive multiple values, e.g. as shown here:
## COMPOSE_PROFILES=standalone,juiceshop
  • Edit the .env file and add your token to the key APPSEC_AGENT_TOKEN.

  • Replace user@email.com in the .env file with your own email. (More details below.)

Available settings in the .env file allowing further customization of the deployment:

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

COMPOSE_PROFILES: Possible values you can set for this key: (you can set multiple values, separated by comma)

standalone : This will activate the deployment of additional containers which are required only when you are not connected to the WebUI at all, resulting in standalone, locally, declaratively managed deployment.

Only activate the standalone profile in case you did not set a WebUI deployment profile token as value for the APPSEC_AGENT_TOKEN key (see above)!

Do not activate the juiceshop profile in production environments as the juiceshop container is intentionally highly vulnerable and meant for testing in lab environments only!

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.

APPSEC_VERSION: Allows you to specify a specific version for deployment instead of using the default latest version for the containers provided by open-appsec (not relevant for postgres container).

Additional configuration available specifically for this integration type:

NPM_DATA: Specify the local folder on the host for the volume mount of the NPM data directory, in the appsec-nginx-proxy-manager container this gets mounted into /data.

NPM_LETSENCRYPT: Specify the local folder on the host for the LetsEncrypt data, in the appsec-nginx-proxy-manager container this gets mounted into /etc/letsencrypt.

For testing purposes in a lab environment you can activate the deployment of the vulnerable juiceshop-backend container via COMPOSE_PROFILES key (see above) and then deploy the available configuration example for exposing it via the proxy, which is provided by the open-appsec team (download link is provided in the .env file).

You find some additional advanced configuration options described within the docker-compose.yaml file as comments.

  1. Perform the deployment

docker-compose up -d
  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

You will see output similar to the below: (The example screenshot below is for an NGINX deployment.)

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:

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

If you deployed the new docker-compose file (beta) which includes the optional vulnerable juiceshop container (just for testing purposes, do not use in production environments!) and added the value juiceshop to the parameter COMPOSE_PROFILES then you can configure juiceshop-backend in the Forward Hostname / IP field of the Edit Proxy Host window to proxy inbound traffic to it.

  1. In the open-appsec Web UI: Navigate to the Agents tab and ensure the new agent is successfully connected.

  2. In the open-appsec Web UI: Create one or more assets defining the specific resources that open-appsec should protect and don't forget to install the policy afterwards. One typical approach would be to create one asset in the open-appsec WebUI per each "Proxy Host" you configured in the NGINX Proxy Manager WebUI. This would allow you to have individual open-appsec security settings per each Proxy Host configured in NPM. All required steps are explained here:

Sign-Up and Login to WebUI Portal For centrally managing your configuration of open-appsec integrated with NPM first follow the instructions below to sign-up and login to the WebUI available at :

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

juiceshop : This will deploy an additional, vulnerable juiceshop-backend container that can be used for demo and testing purposes. In the .env file you also find a download link for the proxy-specific configuration allowing you to access the juiceshop backend via the proxy. More info on the OWASP juiceshop project:

You will see output similar to the below. (The example screenshot below is for an NGINX deployment.) Note that the amount of container will vary based between deployments with and without connection to central WebUI.

To learn how to use NGINX Proxy Manager (NPM) see project documentation: (NPM usage and configuration will not be explained here).

Once you created a new Proxy Host within NGINX Proxy Manager WebUI you can now configure open-appsec protection for it in the open-appsec WebUI ().

Sign-Up and Login to Portal
Create a Profile
https://my.openappsec.io
Sign-Up and Login to Portal
Create a Profile
https://my.openappsec.io
https://owasp.org/www-project-juice-shop/
Using the Advanced Machine Learning Model
https://nginxproxymanager.com
https://my.openappsec.io
Protect Additional Assets
docker ps example output with all containers up
NGINX Proxy Manager Dashboard