Skip to content

Commit 709d7b4

Browse files
LaurenceJJonesLaurenceJJones
authored
Add NPMplus AppSec quickstart guide (#946)
- Created new getting started guide for NPMplus with AppSec Component - Added guide to AppSec sidebar under Installation section - Follows same structure as other AppSec quickstart guides - Includes Docker Compose setup, collection installation, and remediation component configuration
1 parent b072916 commit 709d7b4

File tree

2 files changed

+279
-0
lines changed

2 files changed

+279
-0
lines changed

‎crowdsec-docs/docs/appsec/quickstart/npmplus.mdx‎

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,278 @@
1+
---
2+
id: npmplus
3+
title: QuickStart - NPMplus
4+
---
5+
6+
import Tabs from '@theme/Tabs';
7+
import TabItem from '@theme/TabItem';
8+
import CodeBlock from '@theme/CodeBlock';
9+
import UnderlineTooltip from '@site/src/components/underline-tooltip';
10+
11+
# CrowdSec WAF QuickStart for NPMplus
12+
13+
## Objectives
14+
15+
The goal of this quickstart is to set up the [AppSec Component](/appsec/intro.md#introduction) to safeguard web applications running on [NPMplus](https://github.com/ZoeyVid/NPMplus), an enhanced version of Nginx Proxy Manager.
16+
17+
We'll deploy a [set of rules](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-virtual-patching) designed to block [well-known attacks](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-generic-rules) and [currently exploited vulnerabilities](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-virtual-patching).
18+
19+
Additionally, we'll show how to monitor these alerts through the [console](https://app.crowdsec.net/).
20+
21+
## Pre-requisites
22+
23+
1. If you're new to the [AppSec Component](/appsec/intro.md#introduction) or **W**eb **A**pplication **F**irewalls, start with the [Introduction](/appsec/intro.md#introduction) for a better understanding.
24+
25+
2. It's assumed that you have:
26+
- **Docker and Docker Compose** installed and ready
27+
- **Ports available**: 80/TCP, 443/TCP, 443/UDP (exposed to internet), 81/TCP (admin interface, can be internal)
28+
- A text editor (e.g., nano, vim) and a way to download files (e.g., curl)
29+
30+
:::info
31+
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.
32+
:::
33+
34+
## AppSec Component Setup
35+
36+
### Collection installation
37+
38+
To begin setting up the AppSec Component, the initial step is to install a relevant set of rules.
39+
40+
We will utilize the [`crowdsecurity/appsec-virtual-patching`](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-virtual-patching) collection, which offers a wide range of rules aimed at identifying and preventing the exploitation of known vulnerabilities.
41+
42+
This <UnderlineTooltip tooltip="Collections are bundle of parsers, scenarios, postoverflows that form a coherent package.">collection</UnderlineTooltip> is regularly updated to include protection against newly discovered vulnerabilities. Upon installation, it receives automatic daily updates to ensure your protection is always current.
43+
44+
Furthermore we also install the [`crowdsecurity/appsec-generic-rules`](https://app.crowdsec.net/hub/author/crowdsecurity/collections/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).
45+
46+
:::info
47+
You can always view the content of a [collection on the hub](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-virtual-patching)
48+
:::
49+
50+
### Setup the Acquisition
51+
52+
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.
53+
54+
**Steps:**
55+
56+
1. Download the compose.yaml file:
57+
58+
```bash
59+
curl -L https://raw.githubusercontent.com/ZoeyVid/NPMplus/refs/heads/develop/compose.yaml -o compose.yaml
60+
```
61+
62+
2. Edit the `compose.yaml` file with your preferred text editor:
63+
64+
- **For the NPMplus service**: Set the environment variables:
65+
- `TZ`: Your timezone (e.g., `TZ=Europe/Berlin`)
66+
- `ACME_EMAIL`: Your email address for Let's Encrypt (e.g., `ACME_EMAIL=admin@example.org`)
67+
- `LOGROTATE`: Set to `true` (uncomment this line). This is required for CrowdSec to parse NPMplus logs.
68+
69+
- **For the CrowdSec service**: Uncomment the `crowdsec` service block. Make sure to keep the `openappsec` line commented (note: `appsec` and `openappsec` are different things).
70+
71+
3. Create the acquisition directory and configuration file:
72+
73+
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:
74+
75+
```bash
76+
# Adjust the path based on your Docker volume mounts
77+
mkdir -p /opt/crowdsec/conf/acquis.d
78+
```
79+
80+
Alternatively, if you're using a different volume mount path, adjust accordingly. You can also create the file directly inside the container:
81+
82+
```bash
83+
docker exec -it crowdsec mkdir -p /etc/crowdsec/acquis.d
84+
```
85+
86+
4. 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:
87+
88+
```yaml title="/opt/crowdsec/conf/acquis.d/npmplus.yaml"
89+
filenames:
90+
- /opt/npmplus/nginx/*.log
91+
labels:
92+
type: npmplus
93+
---
94+
filenames:
95+
- /opt/npmplus/nginx/*.log
96+
labels:
97+
type: modsecurity
98+
---
99+
listen_addr: 0.0.0.0:7422
100+
appsec_config: crowdsecurity/appsec-default
101+
name: appsec
102+
source: appsec
103+
labels:
104+
type: appsec
105+
```
106+
107+
:::info
108+
You can find the newest version of the `npmplus.yaml` acquisition file [here](https://github.com/ZoeyVid/NPMplus).
109+
:::
110+
111+
**Configuration explained:**
112+
113+
- The first two sections configure log parsing for NPMplus logs
114+
- The third section configures the AppSec Component:
115+
- `listen_addr: 0.0.0.0:7422`: The AppSec Component listens on all interfaces on port 7422 (needed for Docker networking)
116+
- `appsec_config`: Uses the default configuration from the installed collections
117+
- `source: appsec`: Identifies this as an AppSec data source
118+
119+
### Running NPMplus and CrowdSec
120+
121+
Start the services using Docker Compose:
122+
123+
```bash
124+
docker compose up -d
125+
```
126+
127+
### Install AppSec Collections
128+
129+
After the containers have started, install the required AppSec collections inside the CrowdSec container:
130+
131+
```bash
132+
docker exec crowdsec cscli collections install crowdsecurity/appsec-virtual-patching crowdsecurity/appsec-generic-rules
133+
```
134+
135+
This command installs the following items:
136+
- The [*AppSec Rules*](/appsec/rules_syntax.md) contain the definition of malevolent requests to be matched and stopped
137+
- The [*AppSec Configuration*](/appsec/configuration.md#appsec-configuration-files) links together a set of rules to provide a coherent set
138+
- The <UnderlineTooltip tooltip="YAML files that extract relevant data from logs, such as IP addresses, timestamps, or request paths.">CrowdSec Parser</UnderlineTooltip> and <UnderlineTooltip tooltip="Behavioral rules written in a domain-specific language that define what malicious activity looks like, such as multiple failed logins in a short time.">CrowdSec Scenario(s)</UnderlineTooltip> are used to detect and remediate persistent attacks
139+
140+
After installing the collections, restart the CrowdSec container to load the new configuration:
141+
142+
```bash
143+
docker restart crowdsec
144+
```
145+
146+
:::warning Important
147+
After starting NPMplus, wait about a minute, then check the logs to retrieve the initial admin password:
148+
149+
```bash
150+
docker logs npmplus
151+
```
152+
153+
**Save this password** - you'll need it to log into the NPMplus admin interface.
154+
:::
155+
156+
## Remediation Component Setup
157+
158+
Now we need to configure NPMplus to function as a Remediation Component for the Security Engine and enable the AppSec Component.
159+
160+
### Generate API Key
161+
162+
Generate an API key for NPMplus:
163+
164+
```bash
165+
docker exec crowdsec cscli bouncers add npmplus -o raw
166+
```
167+
168+
Copy the output API key - you'll need it in the next step.
169+
170+
### Configure NPMplus
171+
172+
Edit the NPMplus CrowdSec configuration file:
173+
174+
```bash
175+
# The file location may vary depending on your Docker setup
176+
# Typically it's at: /opt/npmplus/crowdsec/crowdsec.conf
177+
```
178+
179+
In this file, you need to:
180+
181+
1. Set `ENABLED=true` to enable the CrowdSec integration
182+
2. Set `API_KEY` to the key you generated in the previous step
183+
184+
The configuration file should look similar to:
185+
186+
```ini
187+
ENABLED=true
188+
API_KEY=your-api-key-here
189+
```
190+
191+
### Restart NPMplus
192+
193+
Restart the NPMplus container to apply the changes:
194+
195+
```bash
196+
docker restart npmplus
197+
```
198+
199+
### Verify Connection
200+
201+
Check the Docker logs to confirm NPMplus is connected to CrowdSec:
202+
203+
```bash
204+
docker logs npmplus
205+
```
206+
207+
You should see lines mentioning that NPMplus is connected to CrowdSec.
208+
209+
## Testing the AppSec Component + Remediation Component
210+
211+
:::note
212+
We're assuming the web server is accessible. Please adjust your testing accordingly.
213+
:::
214+
215+
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:
216+
217+
![appsec-denied](/img/appsec_denied.png)
218+
219+
We can also look at the metrics from `cscli metrics show appsec` - it will display:
220+
- the number of requests processed by the AppSec Component
221+
- Individual rule matches
222+
223+
<details>
224+
<summary>Example Output</summary>
225+
226+
```bash title="docker exec crowdsec cscli metrics show appsec"
227+
Appsec Metrics:
228+
╭─────────────────┬───────────┬─────────╮
229+
│ Appsec Engine │ Processed │ Blocked │
230+
├─────────────────┼───────────┼─────────┤
231+
│ 0.0.0.0:7422/ │ 2 │ 1 │
232+
╰─────────────────┴───────────┴─────────╯
233+
234+
Appsec '0.0.0.0:7422/' Rules Metrics:
235+
╭─────────────────────────────────┬───────────╮
236+
│ Rule ID │ Triggered │
237+
├─────────────────────────────────┼─────────┤
238+
│ crowdsecurity/vpatch-env-access │ 1 │
239+
╰─────────────────────────────────┴───────────╯
240+
```
241+
242+
You can test and investigate further with [Stack Health-Check](/u/getting_started/health_check) and [Appsec Troubleshooting guide](/appsec/troubleshooting)
243+
244+
</details>
245+
246+
### Explanation
247+
248+
What happened in the test that we just did is:
249+
250+
1. We did a request (`localhost/.env`) to our web server
251+
2. Thanks to the NPMplus Remediation Component configuration, the request was forwarded to `http://crowdsec:7422` (or the appropriate Docker network address)
252+
3. Our AppSec Component, listening on `0.0.0.0:7422` analyzed the request
253+
4. The request matches the [AppSec rule to detect .env access](https://app.crowdsec.net/hub/author/crowdsecurity/appsec-rules/vpatch-env-access)
254+
5. The AppSec Component thus answered with [HTTP 403](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403) to the Remediation Component, indicating that the request must be blocked
255+
6. The web server then presented us with the default "request blocked" page.
256+
257+
## Integration with the console
258+
259+
If you haven't yet, follow the guide about [how to enroll your Security Engine in the console](/u/getting_started/post_installation/console).
260+
261+
Once done, all your alerts, including the ones generated by the AppSec Component, are going to appear in the console:
262+
263+
![appsec-console](/img/appsec_console.png)
264+
265+
## Next steps
266+
267+
You are now running the AppSec Component on your CrowdSec Security Engine with NPMplus, congrats!
268+
269+
:::info
270+
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.
271+
:::
272+
273+
As the next steps, you can:
274+
- [Explore the hub](https://hub.crowdsec.net) to find more rules for your use case
275+
- Look at the [Rules syntax](/appsec/rules_syntax.md) and [creation process](/appsec/create_rules.md) to create your own and contribute
276+
- Take a look at [the benchmarks](/appsec/benchmark.md)
277+
- Use the same steps to set up all your hosts if you want
278+

‎crowdsec-docs/sidebars.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -730,6 +730,7 @@ const sidebarsConfig: SidebarConfig = {
730730
{ type: "doc", id: "appsec/quickstart/general_setup" },
731731
{ type: "doc", id: "appsec/quickstart/nginx-ingress" },
732732
{ type: "doc", id: "appsec/quickstart/nginxopenresty" },
733+
{ type: "doc", id: "appsec/quickstart/npmplus" },
733734
{ type: "doc", id: "appsec/quickstart/traefik" },
734735
{ type: "doc", id: "appsec/quickstart/wordpress" },
735736
],

0 commit comments

Comments
 (0)