Skip to main content
Version: Next

CrowdSec WAF QuickStart for NPMplus

Objectives​

The goal of this quickstart is to set up the AppSec Component to safeguard web applications running on NPMplus, an enhanced version of Nginx Proxy Manager.

We'll deploy a set of rules designed to block well-known attacks and currently exploited vulnerabilities.

Additionally, we'll show how to monitor these alerts through the console.

Pre-requisites​

  1. If you're new to the AppSec Component or Web Application Firewalls, start with the Introduction for a better understanding.

  2. It's assumed that you have:

    • Docker and Docker Compose installed and ready
    • Ports available: 80/TCP, 443/TCP, 443/UDP (exposed to internet), 81/TCP (admin interface, can be internal)
    • A text editor (e.g., nano, vim) and a way to download files (e.g., curl)

NPMplus is an enhanced version of Nginx Proxy Manager that provides additional security, performance optimizations, and advanced features for reverse proxy and web server management. It includes built-in support for CrowdSec integration.

AppSec Component Setup​

Collection installation​

To begin setting up the AppSec Component, the initial step is to install a relevant set of rules.

We will utilize the crowdsecurity/appsec-virtual-patching collection, which offers a wide range of rules aimed at identifying and preventing the exploitation of known vulnerabilities.

This collection is regularly updated to include protection against newly discovered vulnerabilities. Upon installation, it receives automatic daily updates to ensure your protection is always current.

Furthermore we also install the crowdsecurity/appsec-generic-rules collection. This collection contains detection scenarios for generic attack vectors. It provides some protection in cases where specific scenarios for vulnerabilities do not exist (yet).

You can always view the content of a collection on the hub

Setup the Acquisition​

NPMplus provides a Docker Compose file that includes both NPMplus and CrowdSec services. We need to configure the acquisition for AppSec and NPMplus log parsing.

Steps:

  1. Download the compose.yaml file:
curl -L https://raw.githubusercontent.com/ZoeyVid/NPMplus/refs/heads/develop/compose.yaml -o compose.yaml

  1. Edit the compose.yaml file with your preferred text editor:

    • For the NPMplus service: Set the environment variables:

      • TZ: Your timezone (e.g., TZ=Europe/Berlin)
      • ACME_EMAIL: Your email address for Let's Encrypt (e.g., ACME_EMAIL=admin@example.org)
      • LOGROTATE: Set to true (uncomment this line). This is required for CrowdSec to parse NPMplus logs.

    • For the CrowdSec service: Uncomment the crowdsec service block. Make sure to keep the openappsec line commented (note: appsec and openappsec are different things).

  2. Create the acquisition directory and configuration file:

    The exact path depends on how volumes are mounted in your compose.yaml. Typically, you'll need to create the file in the location where CrowdSec's configuration is persisted. If the compose file mounts /opt/crowdsec or /etc/crowdsec from the host, create the directory and file there:

# Adjust the path based on your Docker volume mounts
mkdir -p /opt/crowdsec/conf/acquis.d

Alternatively, if you're using a different volume mount path, adjust accordingly. You can also create the file directly inside the container:

docker exec -it crowdsec mkdir -p /etc/crowdsec/acquis.d
  1. Create the acquisition configuration file /opt/crowdsec/conf/acquis.d/npmplus.yaml (or /etc/crowdsec/acquis.d/npmplus.yaml if using the container path) with the following content:
/opt/crowdsec/conf/acquis.d/npmplus.yaml
filenames:
  - /opt/npmplus/nginx/*.log
labels:
  type: npmplus
---
filenames:
  - /opt/npmplus/nginx/*.log
labels:
  type: modsecurity
---
listen_addr: 0.0.0.0:7422
appsec_config: crowdsecurity/appsec-default
name: appsec
source: appsec
labels:
  type: appsec

You can find the newest version of the npmplus.yaml acquisition file here.

Configuration explained:

  • The first two sections configure log parsing for NPMplus logs
  • The third section configures the AppSec Component:
    • listen_addr: 0.0.0.0:7422: The AppSec Component listens on all interfaces on port 7422 (needed for Docker networking)
    • appsec_config: Uses the default configuration from the installed collections
    • source: appsec: Identifies this as an AppSec data source

Running NPMplus and CrowdSec​

Start the services using Docker Compose:

docker compose up -d

Install AppSec Collections​

After the containers have started, install the required AppSec collections inside the CrowdSec container:

docker exec crowdsec cscli collections install crowdsecurity/appsec-virtual-patching crowdsecurity/appsec-generic-rules

This command installs the following items:

  • The AppSec Rules contain the definition of malevolent requests to be matched and stopped
  • The AppSec Configuration links together a set of rules to provide a coherent set
  • The CrowdSec Parser and CrowdSec Scenario(s) are used to detect and remediate persistent attacks

After installing the collections, restart the CrowdSec container to load the new configuration:

docker restart crowdsec

After starting NPMplus, wait about a minute, then check the logs to retrieve the initial admin password:

docker logs npmplus

Save this password - you'll need it to log into the NPMplus admin interface.

Remediation Component Setup​

Now we need to configure NPMplus to function as a Remediation Component for the Security Engine and enable the AppSec Component.

Generate API Key​

Generate an API key for NPMplus:

docker exec crowdsec cscli bouncers add npmplus -o raw

Copy the output API key - you'll need it in the next step.

Configure NPMplus​

Edit the NPMplus CrowdSec configuration file:

# The file location may vary depending on your Docker setup
# Typically it's at: /opt/npmplus/crowdsec/crowdsec.conf

In this file, you need to:

  1. Set ENABLED=true to enable the CrowdSec integration
  2. Set API_KEY to the key you generated in the previous step

The configuration file should look similar to:

ENABLED=true
API_KEY=your-api-key-here

Restart NPMplus​

Restart the NPMplus container to apply the changes:

docker restart npmplus

Verify Connection​

Check the Docker logs to confirm NPMplus is connected to CrowdSec:

docker logs npmplus

You should see lines mentioning that NPMplus is connected to CrowdSec.

Testing the AppSec Component + Remediation Component​

We're assuming the web server is accessible. Please adjust your testing accordingly.

If you try to access http://localhost/.env (or your server's IP address) from a browser, your request will be blocked, resulting in the display of the following HTML page:

appsec-denied

We can also look at the metrics from cscli metrics show appsec - it will display:

  • the number of requests processed by the AppSec Component
  • Individual rule matches
Example Output
docker exec crowdsec cscli metrics show appsec
Appsec Metrics:
╭─────────────────┬───────────┬─────────╮
│  Appsec Engine  │ Processed │ Blocked │
├─────────────────┼───────────┼─────────┤
│ 0.0.0.0:7422/   │ 2         │ 1       │
╰─────────────────┴───────────┴─────────╯

Appsec '0.0.0.0:7422/' Rules Metrics:
╭─────────────────────────────────┬───────────╮
│             Rule ID             │ Triggered │
├─────────────────────────────────┼─────────┤
│ crowdsecurity/vpatch-env-access │ 1         │
╰─────────────────────────────────┴───────────╯

You can test and investigate further with Stack Health-Check and Appsec Troubleshooting guide

Explanation​

What happened in the test that we just did is:

  1. We did a request (localhost/.env) to our web server
  2. Thanks to the NPMplus Remediation Component configuration, the request was forwarded to http://crowdsec:7422 (or the appropriate Docker network address)
  3. Our AppSec Component, listening on 0.0.0.0:7422 analyzed the request
  4. The request matches the AppSec rule to detect .env access
  5. The AppSec Component thus answered with HTTP 403 to the Remediation Component, indicating that the request must be blocked
  6. The web server then presented us with the default "request blocked" page.

Integration with the console​

If you haven't yet, follow the guide about how to enroll your Security Engine in the console.

Once done, all your alerts, including the ones generated by the AppSec Component, are going to appear in the console:

appsec-console

Next steps​

You are now running the AppSec Component on your CrowdSec Security Engine with NPMplus, congrats!

You can now log into the NPMplus admin interface at https://<ip-of-the-server>:81 using the email address you configured (ACME_EMAIL) and the password you saved earlier. You should be prompted to change these credentials on first login.

As the next steps, you can: