Skip to content

Commit 63e2d7a

Browse files
buixorbuixor
authored
Merge pull request #1070 from crowdsecurity/simplify_waf_setup
simplify waf setup for nginx/openresty
2 parents 866f738 + 2d165f6 commit 63e2d7a

7 files changed

Lines changed: 269 additions & 872 deletions

File tree

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

Lines changed: 50 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -3,77 +3,52 @@ id: haproxy_spoa
33
title: QuickStart - HAProxy (SPOA)
44
---
55

6-
import UnderlineTooltip from '@site/src/components/underline-tooltip';
7-
86
# CrowdSec WAF QuickStart for HAProxy (SPOA)
97

10-
## Objectives
11-
12-
Set up the [AppSec Component](/appsec/intro.md#introduction) to protect web applications running behind [HAProxy](https://www.haproxy.org/) using the **HAProxy SPOA remediation component**.
13-
14-
You will:
15-
- Enable CrowdSec AppSec (WAF) in the Security Engine.
16-
- Install and configure `crowdsec-haproxy-spoa-bouncer` so HAProxy can forward HTTP requests to AppSec.
17-
- Validate everything by triggering a test detection.
8+
Protect web applications running behind [HAProxy](https://www.haproxy.org/) with CrowdSec's [AppSec (WAF) Component](/appsec/intro.md#introduction), using the HAProxy SPOA remediation component to forward HTTP requests.
189

1910
## Prerequisites
2011

21-
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).
22-
2. It's assumed that you have already installed:
23-
- **CrowdSec [Security Engine](/intro.mdx)**: for installation, refer to the [QuickStart guide](/u/getting_started/installation/linux).
24-
- **HAProxy**: already running and proxying your application(s).
25-
- **HAProxy SPOA [Remediation Component](/u/bouncers/intro)**: `crowdsec-haproxy-spoa-bouncer`.
26-
27-
:::tip Already did the base setup?
28-
If you already completed the [General Setup](general.mdx) (collections + acquisition), skip to [Remediation Component Setup](#remediation-component-setup).
29-
:::
30-
31-
## AppSec Component Setup
12+
Make sure the following are already done on the machine running HAProxy (each is a single-page install guide):
3213

33-
### Collection installation
14+
1. **CrowdSec Security Engine** installed and running — see the [Linux quickstart](/u/getting_started/installation/linux).
15+
2. **HAProxy** already running and proxying your application(s).
16+
3. **HAProxy SPOA bouncer** (`crowdsec-haproxy-spoa-bouncer`) installed and registered against the CrowdSec LAPI — see the [SPOA bouncer guide](/u/bouncers/haproxy_spoa).
3417

35-
Install the main AppSec rule collections:
18+
## 1. Install the AppSec rule collections
3619

3720
```bash
38-
sudo cscli collections install crowdsecurity/appsec-virtual-patching crowdsecurity/appsec-generic-rules
21+
sudo cscli collections install \
22+
crowdsecurity/appsec-virtual-patching \
23+
crowdsecurity/appsec-generic-rules
3924
```
4025

41-
These <UnderlineTooltip tooltip="Collections are bundles of parsers, scenarios, and AppSec rules/configuration items.">collections</UnderlineTooltip> provide virtual patching (CVE rules), generic WAF detections, and the default AppSec configuration.
26+
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.
4227

43-
### Setup the acquisition
28+
## 2. Turn on the AppSec Component
4429

45-
Create `/etc/crowdsec/acquis.d/appsec.yaml` (see the [AppSec datasource](/log_processor/data_sources/appsec.md) for the full reference):
30+
Create the acquisition file, then restart CrowdSec:
4631

47-
```yaml title="/etc/crowdsec/acquis.d/appsec.yaml"
32+
```bash
33+
sudo mkdir -p /etc/crowdsec/acquis.d
34+
sudo tee /etc/crowdsec/acquis.d/appsec.yaml > /dev/null <<'EOF'
4835
appsec_configs:
4936
- crowdsecurity/appsec-default
5037
labels:
5138
type: appsec
5239
listen_addr: 127.0.0.1:7422
5340
source: appsec
54-
```
55-
56-
Restart CrowdSec:
57-
58-
```bash
41+
EOF
5942
sudo systemctl restart crowdsec
6043
```
6144

6245
:::warning
63-
Do not expose the AppSec Component to the internet. It should only be reachable from your reverse proxy.
46+
Keep `listen_addr` on `127.0.0.1` — the AppSec Component must only be reachable from your reverse proxy.
6447
:::
6548

66-
## Remediation Component Setup
67-
68-
### Install and configure the HAProxy SPOA bouncer
69-
70-
Read here how to install the SPOA remediation component: [HAProxy SPOA remediation component docs](/u/bouncers/haproxy_spoa).
71-
72-
Once the bouncer is installed and able to talk to CrowdSec LAPI, you only need to enable **AppSec forwarding**.
73-
74-
### Enable AppSec forwarding in the bouncer (YAML)
49+
## 3. Enable AppSec forwarding in the SPOA bouncer
7550

76-
In `/etc/crowdsec/bouncers/crowdsec-spoa-bouncer.yaml`, configure the AppSec endpoint the bouncer should query for WAF evaluation:
51+
Edit `/etc/crowdsec/bouncers/crowdsec-spoa-bouncer.yaml` and add the `appsec_url` plus the `appsec` block under your host(s):
7752

7853
```yaml title="/etc/crowdsec/bouncers/crowdsec-spoa-bouncer.yaml"
7954
# AppSec (WAF forwarding)
@@ -96,58 +71,51 @@ sudo systemctl restart crowdsec-spoa-bouncer
9671
If AppSec runs on a different host (or in containers), update `appsec_url` to the correct reachable address.
9772
:::
9873

99-
:::warning AppSec limitations with HAProxy SPOA (important)
100-
HAProxy SPOA forwarding is constrained by HAProxy/SPOE/SPOA mechanics:
101-
- Request bodies are only available if you enable buffering (`option http-buffer-request`) and they must fit within tight size limits (commonly capped at ~50KB in examples).
102-
- When the body is too large (uploads, large JSON, etc.), you typically fall back to a “no-body” SPOE group, which means **body-dependent WAF rules cannot match**.
103-
- You are not doing full “streaming” inspection: SPOA works with what HAProxy can capture and send to the agent within buffer/frame limits.
74+
## 4. Verify
10475

105-
CrowdSec AppSec is still a single “source of truth” for rules/config: you can point multiple WAF-capable integrations to the same AppSec endpoint so rule updates stay in sync across your infrastructure.
106-
107-
Recommended layered approach:
108-
- Use HAProxy SPOA for **edge enforcement** (IP/range/country decisions, ban/captcha) and lightweight WAF evaluation when the request fits within the configured limits.
109-
- Put a full-featured L7 proxy/WAF-capable integration **downstream** (or protect the app directly) when you need deeper inspection of large bodies, file uploads, or application-specific request parsing. Examples of WAF-capable integrations include:
110-
- [Nginx/OpenResty](nginxopenresty.mdx)
111-
- [Traefik](traefik.mdx)
112-
- [WordPress](wordpress.mdx)
113-
:::
114-
115-
## Testing the AppSec Component + Remediation Component
116-
117-
:::note
118-
Adjust the URL below to match your HAProxy frontend (HTTP/HTTPS, port, hostname).
119-
:::
120-
121-
If you try to access `http(s)://<your-haproxy-url>/.env`, your request should be blocked:
76+
Hit an endpoint that should trip an AppSec rule (adjust the URL to match your HAProxy frontend):
12277

12378
```bash
124-
curl -i http://<your-haproxy-url>/.env
79+
curl -I http://<your-haproxy-url>/.env
12580
```
12681

127-
![appsec-denied](/img/appsec_denied.png)
82+
You should get an `HTTP/1.1 403 Forbidden` response.
12883

129-
You can also check AppSec metrics:
84+
Check that CrowdSec recorded the block:
13085

13186
```bash
13287
sudo cscli metrics show appsec
13388
```
13489

135-
### Explanation
90+
<details>
91+
<summary>What just happened?</summary>
13692

137-
What happened in the test above is:
93+
1. `curl` hit HAProxy at `/.env`.
94+
2. HAProxy forwarded the request to the SPOA remediation component.
95+
3. The bouncer queried the AppSec Component at `appsec_url`.
96+
4. The request matched the [`vpatch-env-access`](https://app.crowdsec.net/hub/author/crowdsecurity/appsec-rules/vpatch-env-access) rule.
97+
5. AppSec answered `403`; HAProxy blocked the request.
13898

139-
1. You requested `/.env` through HAProxy.
140-
2. HAProxy forwarded the request to the SPOA remediation component (SPOE/SPOA).
141-
3. The remediation component queried the AppSec Component at `appsec_url`.
142-
4. The request matched the [AppSec rule to detect `.env` access](https://app.crowdsec.net/hub/author/crowdsecurity/appsec-rules/vpatch-env-access).
143-
5. AppSec returned a blocking action (HTTP 403) to the remediation component.
144-
6. HAProxy blocked the request.
99+
</details>
145100

146-
## Next steps
101+
## AppSec limitations with HAProxy SPOA
147102

148-
You are now running the AppSec Component on your CrowdSec Security Engine with HAProxy SPOA.
103+
HAProxy SPOA forwarding is constrained by HAProxy/SPOE/SPOA mechanics:
104+
- Request bodies are only available if you enable buffering (`option http-buffer-request`) and must fit within tight size limits (commonly capped at ~50 KB).
105+
- When the body is too large (uploads, large JSON, etc.), you typically fall back to a "no-body" SPOE group, which means **body-dependent WAF rules cannot match**.
106+
- This is not full streaming inspection: SPOA works with what HAProxy can capture within buffer/frame limits.
107+
108+
CrowdSec AppSec is a single source of truth for rules — you can point multiple WAF-capable integrations at the same AppSec endpoint so rule updates stay in sync.
109+
110+
Recommended layered approach:
111+
- Use HAProxy SPOA for **edge enforcement** (IP/range/country decisions, ban/captcha) and lightweight WAF evaluation when the request fits within the configured limits.
112+
- Put a full-featured L7 proxy/WAF-capable integration **downstream** (or protect the app directly) when you need deeper inspection of large bodies, file uploads, or application-specific request parsing. Examples:
113+
- [Nginx/OpenResty](nginxopenresty.mdx)
114+
- [Traefik](traefik.mdx)
115+
- [WordPress](wordpress.mdx)
116+
117+
## Next steps
149118

150-
As the next steps, you can:
151-
- Monitor WAF alerts with `sudo cscli alerts list` and in the [CrowdSec Console](https://app.crowdsec.net).
152-
- Review the [AppSec troubleshooting guide](/appsec/troubleshooting.md) and the [HAProxy SPOA remediation component docs](/u/bouncers/haproxy_spoa) if you need to investigate or refine the deployment.
119+
- Monitor WAF alerts with `sudo cscli alerts list` or in the [CrowdSec Console](https://app.crowdsec.net).
120+
- Review the [AppSec troubleshooting guide](/appsec/troubleshooting.md) and the [HAProxy SPOA bouncer docs](/u/bouncers/haproxy_spoa) if you need to investigate or refine the deployment.
153121
- Explore [WAF deployment strategies](/appsec/advanced_deployments.mdx) if you want to expand beyond this initial setup.

0 commit comments

Comments
 (0)