Install NGINX Proxy Manager with open-appsec managed from NPM WebUI
Deployment:
Before you start, make sure to have a Linux environment with Docker and Docker Compose available.
To deploy NGINX Proxy Manager with open-appsec integration follow the steps below
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).
Download the initial declarative configuration file for open-appsec into that folder:
Create a docker-compose.yaml file with the content below, it can be downloaded as follows:
docker-compose.yaml content:
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
Start the deployment of all relevant containers using
docker-compose
:
Check if the appsec-npm and the appsec-agent containers are up and running:
Congratulations, you successfully deployed NGINX Proxy Manager with open-appsec integration!
Now you can login with your web browser to the WebUI of NGINX Proxy Manager with open-appsec integration as follows:
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
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):
Enable open-appsec by flipping the “open-appsec” switch to enabled.
Select the Enforcement Mode, it can be either “Prevent-Learn” or “Detect-Learn”
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.
Click “Save”
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.
Note that as the integration with NPM Web UI is built based on the v1beta1 local configuration schema of open-appsec, you must only use the v1beta1 version of open-appsec with this integration.
If you have requirement to manage open-appsec WAF declaratively with local configuration in v1beta2 schema version, you can instead use the container image nginx-proxy-manager-centrally-managed
which does not contain the integration with NPM Web UI but just the open-appsec attachment, this is compatible with both, v1beta1 and v1beta2 schema versions.
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 e.g. disabling open-appsec in a “Proxy Host” or “Custom Location” might also remove the corresponding configuration from the open-appsec Configuration File.
Last updated
Was this helpful?