- -
-
- 
-
-
- 
-
-
+Website: https://www.openappsec.io
+Github: https://github.com/openappsec
+Docs: https://docs.openappsec.io
+### Integration of open-appsec WAF with NGINX Proxy Manager:
-## Features
+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.
-- Beautiful and Secure Admin Interface based on [Tabler](https://tabler.github.io/)
-- Easily create forwarding domains, redirections, streams and 404 hosts without knowing anything about Nginx
-- Free SSL using Let's Encrypt or provide your own custom SSL certificates
-- Access Lists and basic HTTP Authentication for your hosts
-- Advanced Nginx configuration available for super users
-- User management, permissions and audit log
+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
-## Hosting your home network
+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.
-I won't go in to too much detail here but here are the basics for someone new to this self-hosted world.
+The resulting architecture with the open-appsec Agent container and the NGINX Proxy Manager container then looks like this:
-1. Your home router will have a Port Forwarding section somewhere. Log in and find it
-2. Add port forwarding for port 80 and 443 to the server hosting this project
-3. Configure your domain name details to point to your home, either with a static ip or a service like DuckDNS or [Amazon Route53](https://github.com/jc21/route53-ddns)
-4. Use the Nginx Proxy Manager as your gateway to forward to your other web based services
+
-## Quick Setup
+Documentation: https://docs.openappsec.io/integrations/nginx-proxy-manager-integration
-1. Install Docker and Docker-Compose
+### Deployment Playgrounds (Virtual labs)
+You can experiment with the integration of NGINX Proxy Manager and open-appsec using [Playgrounds](https://www.openappsec.io/playground)
+
-- [Docker Install documentation](https://docs.docker.com/install/)
-- [Docker-Compose Install documentation](https://docs.docker.com/compose/install/)
-
-2. Create a docker-compose.yml file similar to this:
+# Deployment Step-by-Step:
+Before you start, make sure to have a Linux environment with Docker and Docker Compose suitable with version 3.3 available.
+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.
+This will be managed from the NPM WebUI.
+```
+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
+```
+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."
-```yml
-services:
- app:
- image: 'docker.io/jc21/nginx-proxy-manager:latest'
- restart: unless-stopped
- ports:
- - '80:80'
- - '81:81'
- - '443:443'
- volumes:
- - ./data:/data
- - ./letsencrypt:/etc/letsencrypt
+6. Run docker-compose up to start the deployment of all relevant containers:
+```
+docker-compose up -d
```
+6. Check if the nginx-proxy-manager-attachment and the appsec-agent containers are up and running:
+```
+docker ps
+```
+Congratulations, 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
+```
+
-This is the bare minimum configuration required. See the [documentation](https://nginxproxymanager.com/setup/) for more.
-3. Bring up your stack by running
+At first login please use the following default administrator user credentials:
-```bash
-docker-compose up -d
+E-mail address: admin@example.com
+Password: changeme
-# If using docker-compose-plugin
-docker compose up -d
+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:
-```
+
-4. Log in to the Admin UI
+# Configuration
+To learn how to use NGINX Proxy Manager (NPM) please see project documentation, as NPM usage and configuration will not be explained here:
+https://nginx-proxy-manager.com
-When your docker container is running, connect to it on port `81` for the admin interface.
-Sometimes this can take a little bit because of the entropy of keys.
+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”
-[http://127.0.0.1:81](http://127.0.0.1:81)
+
-Default Admin User:
-```
-Email: admin@example.com
-Password: changeme
-```
+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”.
-Immediately after logging in with this default user you will be asked to modify your details and change your password.
+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.
+This was just a very basic overview to get you started, there's many more things you can configure as part of the open-appsec NGINX Proxy Manager integration.
-## Contributing
+If you want to check out the open-appsec Security 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:
+
-All are welcome to create pull requests for this project, against the `develop` branch. Official releases are created from the `master` branch.
-CI is used in this project. All PR's must pass before being considered. After passing,
-docker builds for PR's are available on dockerhub for manual verifications.
+**You find the full documentation including FAQ here:
+https://docs.openappsec.io/integrations/nginx-proxy-manager-integration/**
+
+# Compilation Instructions
+
+**Important: In order to deploy and use the open-appsec NGINX Proxy Manager integration you do not have to compile the code yourself.**
+We offer a pre-compiled ready-to-use "open-appsec-npm" container (see above in the "Deployment" section).
+
+## Prerequisites
+- Linux Machine with Docker engine deployed
+
+## Additional prerequisites for compiling against other NGINX Proxy Manager version
+Precompiled libraries for open-appsec Attachment for the specific version of NGINX Proxy Manager you want to compile against.
+You find the detailed compilation instructions in this repo: https://github.com/openappsec/attachment
+
+Make sure to compile the attachment using a container with the exact same OS version as used in the NPM container version you want to build the integration upon and provide also the NGINX version information from that container.
+libngx_module.so libosrc_compression_utils.so libosrc_nginx_attachment_util.so libosrc_shmem_ipc.so
+
+## Preparations
+Clone this repository to your local Linux machine:
+```
+git clone https://github.com/openappsec/open-appsec-npm.git
+```
+
+Change into the open-appsec-npm directory:
+```
+cd open-appsec-npm
+```
+### If you are compiling against other NGINX proxy Manager version
+Replace the files in the ```docker/lib``` folder with the libraries you've precompiled.
+
+Compilation - Build the Frontend:
+---
+```
+cd scripts/ci
+bash frontend-build
+```
+
+Build the open-appsec-npm Container Image:
+--
+```
+cd ../..
+docker buildx build --load -t open-appsec-npm -f docker/Dockerfile .
+```
-Documentation within the `develop` branch is available for preview at
-[https://develop.nginxproxymanager.com](https://develop.nginxproxymanager.com)
+**Congratulations, you have successfully built your own open-appsec-npm container.**
+You can deploy it now by specifying it within the docker-compose.yaml file.
+You find the deployment instructions above in the "Deployment" section.
+If you also want to build your own open-appsec Agent container you find the instructions in this repo:
+https://github.com/openappsec/openappsec
+# Contributing
+We welcome everyone that wishes to share their knowledge and expertise to enhance and expand this project.
-### Contributors
+Please see the [Contributing Guidelines](https://github.com/openappsec/openappsec-npm/blob/main/CONTRIBUTING.md).
-Special thanks to [all of our contributors](https://github.com/NginxProxyManager/nginx-proxy-manager/graphs/contributors).
+# Final notes
+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!
-## Getting Support
+If you have any questions, feedback or need assistance with some issue you can
+- contact us at info@openappsec.io
+- contact us using the chat on our project website https://www.openappsec.io
+- open an issue in the GitHub project
-1. [Found a bug?](https://github.com/NginxProxyManager/nginx-proxy-manager/issues)
-2. [Discussions](https://github.com/NginxProxyManager/nginx-proxy-manager/discussions)
-3. [Reddit](https://reddit.com/r/nginxproxymanager)
diff --git a/backend/internal/nginx-openappsec.js b/backend/internal/nginx-openappsec.js
new file mode 100755
index 000000000..78e170592
--- /dev/null
+++ b/backend/internal/nginx-openappsec.js
@@ -0,0 +1,318 @@
+const util = require('util');
+const execPromise = util.promisify(require('child_process').exec);
+const { exec } = require('child_process');
+const _ = require('lodash');
+const fs = require('fs');
+const logger = require('../logger').nginx;
+const config = require('../lib/config');
+const yaml = require('js-yaml');
+const path = require('path');
+const constants = require('../lib/constants');
+
+const internalNginxOpenappsec = {
+
+ // module constants
+ CONFIG_TEMPLATE_FILE_NAME: 'local-policy-open-appsec-enabled-for-proxy-host.yaml',
+ CONFIG_TEMPLATE_DIR: '/app/templates',
+
+ // module variables
+ config: null,
+ configTemplate: null,
+
+ /**
+ * Generate an open-appsec config file for a proxy host.
+ *
+ * @param {Object} access
+ * @param {Object} row
+ * @param {Object} data
+ * @returns {Promise}
+ */
+ generateConfig: (access, row, d) => {
+ return access.can('settings:update', row.id)
+ .then(() => {
+ if (config.debug()) {
+ logger.info('Generating openappsec config:', JSON.stringify(data, null, 2));
+ }
+
+
+ const data = row ? { ...row, ...d } : d;
+ logger.debug('data', JSON.stringify(data));
+
+ const openappsecMode = data.use_openappsec == false ? 'inactive' : data.openappsec_mode;
+
+ const configTemplateFilePath = path.join(internalNginxOpenappsec.CONFIG_TEMPLATE_DIR, internalNginxOpenappsec.CONFIG_TEMPLATE_FILE_NAME)
+ const configFilePath = path.join(constants.APPSEC_EXT_DIR, constants.APPSEC_CONFIG_FILE_NAME);
+
+ let openappsecConfig = yaml.load(fs.readFileSync(configFilePath, 'utf8'));
+ let openappsecConfigTemplate = yaml.load(fs.readFileSync(configTemplateFilePath, 'utf8'));
+
+ internalNginxOpenappsec.config = openappsecConfig;
+ internalNginxOpenappsec.configTemplate = openappsecConfigTemplate;
+
+ const specificRuleName = 'npm-managed-specific-rule-proxyhost-' + row.id;
+ const logTriggerName = 'npm-managed-log-trigger-proxyhost-' + row.id;
+ const practiceName = 'npm-managed-practice-proxyhost-' + row.id;
+
+ _.remove(openappsecConfig.policies['specific-rules'], rule => rule.name === specificRuleName || rule.name.startsWith(`${specificRuleName}.`));
+
+ data.domain_names.forEach((domain, index) => {
+ let ruleName = index > 0 ? `${specificRuleName}.${index}` : specificRuleName;
+ let specificRuleNode = {
+ host: domain,
+ name: ruleName,
+ triggers: [logTriggerName],
+ mode: openappsecMode,
+ practices: [practiceName]
+ };
+ internalNginxOpenappsec.updateNode('policies', 'specific-rules', specificRuleNode, openappsecMode);
+ });
+
+ internalNginxOpenappsec.updateNode('', 'practices', { name: practiceName, 'web-attacks.override-mode': openappsecMode, 'web-attacks.minimum-confidence': data.minimum_confidence }, openappsecMode);
+ internalNginxOpenappsec.updateNode('', 'log-triggers', { name: logTriggerName }, openappsecMode);
+
+ // remove all openappsec managed location config nodes for a proxy host.
+ let pattern = new RegExp(`^npm-managed.*-${row.id}-.*`);
+ internalNginxOpenappsec.removeMatchingNodes(openappsecConfig, pattern);
+
+ // for each data.location, create location config nodes
+ data.locations.forEach((location, index) => {
+ let locationSpecificRuleName = 'npm-managed-specific-rule-proxyhost-' + row.id + '-' + index;
+ let locationLogTriggerName = 'npm-managed-log-trigger-proxyhost-' + row.id + '-' + index;
+ let locationPracticeName = 'npm-managed-practice-proxyhost-' + row.id + '-' + index;
+
+ let locationOpenappsecMode = location.use_openappsec == false ? 'inactive' : location.openappsec_mode;
+
+ _.remove(openappsecConfig.policies['specific-rules'], rule => rule.name === locationSpecificRuleName || rule.name.startsWith(`${locationSpecificRuleName}.`));
+
+ data.domain_names.forEach((domain, index) => {
+ let locationUrl = domain + location.path;
+ let ruleName = index > 0 ? `${locationSpecificRuleName}.${index}` : locationSpecificRuleName;
+
+ let domainSpecificRuleNode = {
+ host: locationUrl,
+ name: ruleName,
+ triggers: [locationLogTriggerName],
+ mode: locationOpenappsecMode,
+ practices: [locationPracticeName]
+ };
+ internalNginxOpenappsec.updateNode('policies', 'specific-rules', domainSpecificRuleNode, locationOpenappsecMode, 'location', openappsecMode);
+ });
+
+ internalNginxOpenappsec.updateNode('', 'practices', { name: locationPracticeName, 'web-attacks.override-mode': locationOpenappsecMode, 'web-attacks.minimum-confidence': location.minimum_confidence }, locationOpenappsecMode, 'location', openappsecMode);
+ internalNginxOpenappsec.updateNode('', 'log-triggers', { name: locationLogTriggerName }, locationOpenappsecMode, 'location', openappsecMode);
+ });
+
+ fs.writeFileSync(configFilePath, yaml.dump(openappsecConfig));
+ },
+ (err) => {
+ logger.error('Error generating openappsec config:', err);
+ return Promise.reject(err);
+ })
+ .then(() => {
+ // Return the notifyPolicyUpdate promise chain
+ // notify openappsec to apply the policy
+ return internalNginxOpenappsec.notifyPolicyUpdate().catch((errorMessage) => {
+ // console.error('Error:', errorMessage);
+ const errorMessageForUI = `Error: Policy couldn’t be applied, open-appsec-agent container is not responding.
+ Check if open-appec-agent container is running, then apply open-appsec Configuration
+ again by clicking here:
+