You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The goal of this quickstart is to set up the [AppSec Component](/appsec/intro.md#introduction) to safeguard web applications running on [Nginx](https://nginx.com) or [OpenResty](https://openresty.org/en/).
17
-
18
-
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).
19
-
20
-
Additionally, we'll show how to monitor these alerts through the [Console](https://app.crowdsec.net/).
21
-
22
-
## Prerequisites
23
-
24
-
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.
25
-
26
-
2. It's assumed that you have already installed:
27
-
-**CrowdSec [Security Engine](/intro.mdx)**: for installation, refer to the [QuickStart guide](/u/getting_started/installation/linux). The AppSec Component, which analyzes HTTP requests, is included within the security engine as a [Acquisition](/log_processor/data_sources/appsec.md).
28
-
- One of the supported web servers for this guide:
29
-
- Nginx **[Remediation Component](/u/bouncers/intro)**: installation instructions are available in the [QuickStart guide](/u/bouncers/nginx).
30
-
- OpenResty **[Remediation Component](/u/bouncers/intro)**: installation instructions are available in the [QuickStart guide](/u/bouncers/openresty).
31
-
32
-
This component intercepts HTTP requests at the webserver or reverse-proxy level and forwards them to the AppSec Component for analysis and action.
33
-
34
-
:::info
35
-
The reason we provide Nginx and OpenResty in a single guide is that OpenResty is a web server based on Nginx just the configuration paths are different
36
-
:::
37
-
38
-
:::tip Already did the base setup?
39
-
If you already completed the [General Setup](general.mdx) (collections + acquisition), skip to [Remediation Component Setup](#remediation-component-setup).
40
-
:::
41
-
42
-
## AppSec Component Setup
43
-
44
-
### Collection installation
45
-
46
-
To begin setting up the AppSec Component, the initial step is to install a relevant set of rules.
47
-
48
-
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.
49
-
50
-
This <UnderlineTooltiptooltip="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.
51
-
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 protection in cases where specific scenarios for vulnerabilities do not exist yet.
52
-
53
-
On the machine where the Security Engine is installed, just execute the following command:
54
-
55
-
:::info
56
-
You can always view the content of a [collection on the Hub](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-virtual-patching).
Executing this command will install the following items:
64
-
65
-
- The [*AppSec Rules*](/appsec/rules_syntax.md) contain the definition of malicious requests to be matched and stopped
66
-
- The [*AppSec Configuration*](/appsec/configuration.md#appsec-configuration-files) links together a set of rules to provide a coherent set
67
-
- The <UnderlineTooltiptooltip="YAML files that extract relevant data from logs, such as IP addresses, timestamps, or request paths.">CrowdSec Parser</UnderlineTooltip> and <UnderlineTooltiptooltip="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> bans for a longer duration repeating offenders
68
-
69
-
### Setup the Acquisition
70
-
71
-
Having installed the required components, it's time to configure the CrowdSec acquisition datasource for the AppSec Component ([AppSec datasource](/log_processor/data_sources/appsec.md)). This configuration allows Nginx/OpenResty to forward requests to the AppSec Component for evaluation and decision-making.
72
-
73
-
Steps:
74
-
75
-
1. Create the acquisition directory (if it doesn't exist on your machine):
The two important directives in this configuration file are:
91
8
92
-
- `appsec_configs` is the list of [*AppSec Configurations*](/appsec/configuration.md#appsec-configuration-files) that was included in the <UnderlineTooltip tooltip="Collections are bundle of parsers, scenarios, postoverflows that form a coherent package.">Collection</UnderlineTooltip> we just installed.
93
-
- the `listen_addr` is the IP and port the AppSec Component will listen to.
9
+
# CrowdSec WAF QuickStart for Nginx / OpenResty
94
10
95
-
:::warning
96
-
We do not recommend exposing the AppSec Component to the internet. It should only be accessible from the web server or reverse proxy.
97
-
:::
11
+
Protect an [Nginx](https://nginx.com) or [OpenResty](https://openresty.org/en/) server with CrowdSec's [AppSec (WAF) Component](/appsec/intro.md#introduction). After the prerequisites below, every step is a single copy-paste command — pick your engine once in the tabs and the page will remember the choice.
98
12
99
13
:::info
100
-
You can find more about the [supported options for the acquisition here](/log_processor/data_sources/appsec.md)
14
+
Nginx and OpenResty share a single guide because OpenResty is Nginx with Lua built in — only the bouncer package and a few paths differ.
101
15
:::
102
16
103
-
You can now restart CrowdSec:
104
-
105
-
```bash
106
-
sudo systemctl restart crowdsec
107
-
```
17
+
## Prerequisites
108
18
109
-
#### Testing the AppSec Component
19
+
Make sure the following are already done on the machine running your web server (all are single-page install guides):
110
20
111
-
##### Verify the AppSec Component is listening
21
+
1.**CrowdSec Security Engine** installed and running — see the [Linux quickstart](/u/getting_started/installation/linux).
22
+
2.**Nginx or OpenResty bouncer** installed and registered against the CrowdSec LAPI:
The output may look different depending on the command you used. As long as you see port 7422 and the `crowdsec` process, the AppSec Component is running.
146
-
:::
51
+
This pulls the [`appsec-virtual-patching`](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-virtual-patching) collection (rules for known CVEs, auto-updated daily) and the [`appsec-generic-rules`](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-generic-rules) collection (common attack patterns), plus the default AppSec configuration.
147
52
148
-
</details>
53
+
## 2. Turn on the AppSec Component
149
54
150
-
##### (Optional) Manually testing the AppSec Component with `curl`
151
-
152
-
<details>
153
-
<summary>Expand for short guide</summary>
154
-
155
-
Before we proceed with configuring the Remediation Component, let's verify that all our current setups are functioning correctly.
156
-
157
-
1. Create a Remediation Component (Bouncer) API Key:
Create the acquisition file, then restart CrowdSec:
175
56
176
57
```bash
177
-
HTTP/1.1 200 OK
178
-
Date: Tue, 30 Jan 2024 15:43:50 GMT
179
-
Content-Length: 36
180
-
Content-Type: text/plain; charset=utf-8
181
-
182
-
{"action":"allow","http_status":200}
58
+
sudo mkdir -p /etc/crowdsec/acquis.d
59
+
sudo tee /etc/crowdsec/acquis.d/appsec.yaml > /dev/null <<'EOF'
60
+
appsec_configs:
61
+
- crowdsecurity/appsec-default
62
+
labels:
63
+
type: appsec
64
+
listen_addr: 127.0.0.1:7422
65
+
source: appsec
66
+
EOF
67
+
sudo systemctl restart crowdsec
183
68
```
184
69
185
-
3. Emit a malevolent request to the Appsec Component:
186
-
187
-
:::info
188
-
We're trying to access a `.env` file, a [common way to retrieve credentials left by mistake](https://app.crowdsec.net/hub/author/crowdsecurity/appsec-rules/vpatch-env-access).
70
+
:::warning
71
+
Keep `listen_addr` on `127.0.0.1` — the AppSec Component must not be reachable from the internet. It should only be queried by your local web server / reverse proxy.
Since our AppSec Component is active and listening, we can now configure the Remediation Component to forward requests to it.
100
+
The default bouncer config already contains an empty `APPSEC_URL=` line, so `sed -i` replaces it in place — the command is idempotent and safe to re-run.
218
101
219
-
To setup forwarding of requests in the remediation component, we'll modify its configuration file and append the following line:
This instructs the remediation component to communicate with the AppSec Component at `http://127.0.0.1:7422`.
229
-
230
-
Once configured, all incoming HTTP requests will be sent there for analysis. The snippet above assumes that the AppSec Component is running on the same machine.
111
+
We're hitting a `.env` file, a [common way to retrieve credentials left by mistake](https://app.crowdsec.net/hub/author/crowdsecurity/appsec-rules/vpatch-env-access) — the AppSec Component detects and blocks it.
231
112
232
-
We can now restart the service:
113
+
Check that CrowdSec recorded the block:
233
114
234
115
```bash
235
-
sudo systemctl restart nginx
116
+
sudo cscli metrics show appsec
236
117
```
237
118
238
-
## Testing the AppSec Component + Remediation Component
239
-
240
-
:::note
241
-
We're assuming the web server is installed on the same machine and is listening on port 80. Please adjust your testing accordingly if this is not the case.
242
-
You can also look at the [General WAF Testing](/docs/appsec/quickstart/general.mdx#testing-waf-component)
243
-
:::
244
-
245
-
246
-
247
-
if you try to access `http://localhost/.env` from a browser, your request will be blocked, resulting in the display of the following HTML page:
248
-
249
-
250
-
251
-
We can also look at the metrics from `cscli metrics show appsec` it will display:
252
-
- the number of requests processed by the AppSec Component
2. The bouncer forwarded the request to the AppSec Component on `127.0.0.1:7422`.
145
+
3. The request matched the [`vpatch-env-access`](https://app.crowdsec.net/hub/author/crowdsecurity/appsec-rules/vpatch-env-access) rule.
146
+
4. The AppSec Component answered `403`, the bouncer enforced it, and the web server returned the CrowdSec ban page.
279
147
280
-
1. We did a request (`localhost/.env`) to our local webserver
281
-
2. Thanks to the Remediation Component configuration, forwarded the request to `http://127.0.0.1:7422`
282
-
3. Our AppSec Component, listening on `http://127.0.0.1:7422` analyzed the request
283
-
4. The request matches the [AppSec rule to detect .env access](https://app.crowdsec.net/hub/author/crowdsecurity/appsec-rules/vpatch-env-access)
284
-
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
285
-
6. The web server then presented us with the default "request blocked" page.
148
+
</details>
286
149
287
-
## Integration with the Console
150
+
If you'd rather see the block in a browser, visit `http://<your-host>/.env` — you'll get the CrowdSec ban page:
288
151
289
-
If you haven't yet, follow the guide about [how to enroll your Security Engine in the Console](/u/getting_started/post_installation/console).
152
+
290
153
291
-
Once done, all your alerts, including the ones generated by the AppSec Component, appear in the Console:
154
+
## Monitor in the Console
292
155
293
-
156
+
If you haven't enrolled the Security Engine yet, follow [how to enroll in the Console](/u/getting_started/post_installation/console). Once enrolled, AppSec alerts show up alongside the rest of your alerts:
294
157
158
+
295
159
296
160
## Next steps
297
161
298
-
You are now running the AppSec Component on your CrowdSec Security Engine.
299
-
300
-
As the next steps, you can:
301
-
- Monitor WAF alerts with `sudo cscli alerts list` and in the [CrowdSec Console](https://app.crowdsec.net).
162
+
- Monitor WAF alerts with `sudo cscli alerts list` or in the [CrowdSec Console](https://app.crowdsec.net).
302
163
- Review the [AppSec troubleshooting guide](/appsec/troubleshooting.md) if you need to investigate or refine the deployment.
303
164
- Explore [WAF deployment strategies](/appsec/advanced_deployments.mdx), [rules syntax](/appsec/rules_syntax.md), [rule creation](/appsec/create_rules.md), and [benchmarks](/appsec/benchmark.md) to go further.
0 commit comments