Skip to content

Commit c4a7195

Browse files
buixorbuixor
authored
Merge pull request #877 from crowdsecurity/improved_crs_doc
Improved crs doc
2 parents 0f50f8f + ff17aaa commit c4a7195

File tree

5 files changed

+268
-326
lines changed

5 files changed

+268
-326
lines changed

‎crowdsec-docs/docs/appsec/advanced_deployments.mdx‎

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
---
2+
id: advanced_deployments
3+
title: Advanced WAF Deployments
4+
sidebar_position: 6
5+
---
6+
7+
# Advanced WAF Deployments
8+
9+
This guide covers advanced CrowdSec WAF deployment strategies for organizations looking to gradually enhance their web application security posture. Learn how to progressively improve your WAF configuration from basic virtual patching to comprehensive multi-layer protection.
10+
11+
:::info Prerequisites
12+
This guide assumes you have completed the [General Setup](/appsec/quickstart/general.mdx) and have a functional basic WAF deployment.
13+
:::
14+
15+
## About OWASP Core Rule Set (CRS)
16+
17+
The **OWASP Core Rule Set (CRS)** is a set of generic attack detection rules for use with ModSec-compatible web application firewalls. CRS aims to protect web applications from a wide range of attacks, including the OWASP Top Ten, with minimal false positives.
18+
19+
**Key features of OWASP CRS:**
20+
- **Comprehensive Coverage**: Protects against SQL injection, XSS, command injection, path traversal, and many other attack types
21+
- **Generic Detection**: Uses pattern-based rules that detect attack techniques rather than specific exploits
22+
- **Mature Ruleset**: Actively maintained by the OWASP community with regular updates
23+
- **Configurable Sensitivity**: Supports paranoia levels to balance security vs false positives
24+
- **Wide Compatibility**: Works with various WAF engines including CrowdSec's AppSec component
25+
26+
**CRS vs Virtual Patching:**
27+
- **Virtual Patching**: Targets specific known vulnerabilities (CVEs) with minimal false positives
28+
- **CRS**: Provides broad attack pattern detection with comprehensive coverage but may require tuning
29+
30+
In CrowdSec, CRS rules can be deployed in two modes:
31+
- **Out-of-band**: Analyzes traffic without blocking, triggers bans after multiple violations
32+
- **In-band**: Blocks malicious requests immediately at detection time
33+
34+
## Security Enhancement Path
35+
36+
CrowdSec WAF supports multiple deployment strategies that can be implemented progressively:
37+
38+
### 1. Basic Virtual Patching (Quickstart)
39+
**Current State**: Blocking protection against known CVEs
40+
- Collections: [`crowdsecurity/appsec-virtual-patching`](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-virtual-patching)
41+
- Mode: In-band (blocking)
42+
- Coverage: Known vulnerabilities only
43+
- False Positives: Minimal
44+
45+
### 2. Enhanced Detection (Out-of-band CRS)
46+
**Next Step**: Add comprehensive attack detection without performance impact
47+
- Add: [`crowdsecurity/appsec-crs-inband`](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-crs-inband) (out-of-band) alongside existing virtual patching
48+
- Mode: Non-blocking analysis + behavioral banning
49+
- Coverage: OWASP Top 10 + comprehensive attack patterns + specific CVE protection
50+
- Performance: No latency impact ⚡
51+
- Security: Layered approach - virtual patching + generic attack detection
52+
53+
### 3. Maximum Protection (In-band CRS)
54+
**Advanced**: Full blocking protection with comprehensive coverage
55+
- Modify: Use [`crowdsecurity/appsec-crs-inband`](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-crs-inband) for blocking CRS while keeping virtual patching
56+
- Mode: Immediate blocking of all detected attacks (both generic and CVE-specific)
57+
- Coverage: Maximum protection with instant response 🛡️
58+
- Security: Dual-layer blocking - virtual patching handles specific vulnerabilities, CRS covers generic attack patterns
59+
- Consideration: Might require tuning to minimize false positives
60+
61+
## Implementation Guide
62+
63+
### Step 2: Adding Out-of-band CRS
64+
65+
Enhance your existing virtual patching deployment by adding comprehensive attack detection as an additional security layer:
66+
67+
```bash title="Install CRS collection"
68+
sudo cscli collections install crowdsecurity/appsec-crs
69+
```
70+
71+
The [`crowdsecurity/appsec-crs`](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-crs) collection includes:
72+
- **crowdsecurity/crs**: AppSec config that loads CRS rules in out-of-band mode
73+
- **crowdsecurity/crowdsec-appsec-outofband**: Scenario that bans IPs after 5+ out-of-band rule violations
74+
75+
Update your WAF acquisition configuration to include both rule sets:
76+
77+
```yaml title="/etc/crowdsec/acquis.d/appsec.yaml"
78+
appsec_configs:
79+
- crowdsecurity/appsec-default # Virtual patching rules (in-band blocking)
80+
- crowdsecurity/crs # OWASP CRS rules (out-of-band detection)
81+
labels:
82+
type: appsec
83+
listen_addr: 127.0.0.1:7422
84+
source: appsec
85+
name: myAppSecComponent
86+
```
87+
88+
```bash title="Restart CrowdSec"
89+
sudo systemctl restart crowdsec
90+
```
91+
92+
**Benefits of this layered configuration:**
93+
- **Layer 1**: Immediate protection against known vulnerabilities (virtual patching)
94+
- **Layer 2**: Comprehensive attack pattern detection (CRS out-of-band)
95+
- **Complementary Coverage**: Virtual patching rules catch specific CVEs that CRS generic rules might miss
96+
- Behavioral analysis and repeat offender banning
97+
- No performance impact on legitimate traffic
98+
99+
#### How to Test Step 2: Out-of-band CRS Detection
100+
101+
After implementing the layered configuration, verify both protection layers are working correctly:
102+
103+
**Test 1: Virtual Patching Layer (Immediate Blocking)**
104+
105+
Test that virtual patching rules block requests immediately by trying to access sensitive files:
106+
107+
```bash
108+
# Test .env file access (common vulnerability)
109+
curl -v "http://your-app.com/.env"
110+
curl -v "http://your-app.com/api/../.env"
111+
```
112+
113+
Expected result: These requests should be immediately blocked with HTTP 403 Forbidden.
114+
115+
**Test 2: CRS Out-of-band Detection Layer**
116+
117+
The `crowdsecurity/crs` collection brings general detection for OWASP top10 attacks, which can be tested:
118+
119+
```bash
120+
# Replace with your application URL
121+
TARGET="http://your-app.com"
122+
123+
# SQL injection attempts (trigger multiple CRS rules)
124+
curl "$TARGET/?id=1'+OR+'1'='1"
125+
```
126+
127+
Expected results:
128+
129+
- Detailed Alert is created (see `cscli alerts list`)
130+
131+
<details>
132+
<summary>`cscli alerts list` output</summary>
133+
134+
```yaml
135+
+-------+--------------------+--------------------------------------------------------------+---------+------------------------------+-----------+----------------------+
136+
| ID | value | reason | country | as | decisions | created_at |
137+
+-------+--------------------+--------------------------------------------------------------+---------+------------------------------+-----------+----------------------+
138+
| 62419 | Ip:xxx.xx.xx.xx | anomaly score out-of-band: sql_injection: 10, anomaly: 10, | FR | 5410 Bouygues Telecom SA | | 2025-09-09T14:41:07Z |
139+
...
140+
```
141+
</details>
142+
143+
144+
- Detailed Alert is visible in console
145+
146+
<details>
147+
<summary>Alert Console view</summary>
148+
![timeline](/img/console-appsec-oob.png)
149+
</details>
150+
151+
**Test 3: Verify Scenario Behavior**
152+
153+
The `crowdsecurity/crowdsec-appsec-outofband` scenario will ban IPs triggering the CRS on more than 5 distinct requests on a short period, which can be tested:
154+
155+
```bash
156+
for i in {1..6}; do curl "$TARGET/?id=1'+OR+'1'='1"; done
157+
```
158+
159+
160+
Expected results:
161+
162+
- Alerts are created for each request
163+
- Decision is created by the 6th request
164+
165+
<details>
166+
<summary>`cscli alerts list` output</summary>
167+
168+
```yaml
169+
───────┬────────────────────┬──────────────────────────────────────────────────────────────┬─────────┬──────────────────────────────┬───────────┬──────────────────────╮
170+
│ ID │ value │ reason │ country │ as │ decisions │ created_at │
171+
├───────┼────────────────────┼──────────────────────────────────────────────────────────────┼─────────┼──────────────────────────────┼───────────┼──────────────────────┤
172+
│ 62427 │ Ip:xxx.xx.xx.xx │ crowdsecurity/crowdsec-appsec-outofband │ FR │ 5410 Bouygues Telecom SA │ ban:1 │ 2025-09-09T14:51:11Z │
173+
│ 62426 │ Ip:xxx.xx.xx.xx │ anomaly score out-of-band: sql_injection: 10, anomaly: 10, │ FR │ 5410 Bouygues Telecom SA │ │ 2025-09-09T14:51:12Z │
174+
│ 62425 │ Ip:xxx.xx.xx.xx │ anomaly score out-of-band: sql_injection: 10, anomaly: 10, │ FR │ 5410 Bouygues Telecom SA │ │ 2025-09-09T14:51:11Z │
175+
│ 62424 │ Ip:xxx.xx.xx.xx │ anomaly score out-of-band: sql_injection: 10, anomaly: 10, │ FR │ 5410 Bouygues Telecom SA │ │ 2025-09-09T14:51:11Z │
176+
│ 62423 │ Ip:xxx.xx.xx.xx │ anomaly score out-of-band: sql_injection: 10, anomaly: 10, │ FR │ 5410 Bouygues Telecom SA │ │ 2025-09-09T14:51:11Z │
177+
│ 62422 │ Ip:xxx.xx.xx.xx │ anomaly score out-of-band: sql_injection: 10, anomaly: 10, │ FR │ 5410 Bouygues Telecom SA │ │ 2025-09-09T14:51:11Z │
178+
│ 62421 │ Ip:xxx.xx.xx.xx │ anomaly score out-of-band: sql_injection: 10, anomaly: 10, │ FR │ 5410 Bouygues Telecom SA │ │ 2025-09-09T14:51:11Z │
179+
180+
```
181+
</details>
182+
183+
### Step 3: CRS In-band (Blocking Mode)
184+
185+
For organizations requiring maximum protection, configure CRS rules to block requests immediately by installing the in-band CRS collection:
186+
187+
```bash title="Install CRS in-band collection"
188+
sudo cscli collections install crowdsecurity/appsec-crs-inband
189+
```
190+
191+
#### Update Acquisition Configuration
192+
193+
Modify your acquisition to use the in-band CRS configuration:
194+
195+
```yaml title="/etc/crowdsec/acquis.d/appsec.yaml"
196+
appsec_configs:
197+
- crowdsecurity/appsec-default # Virtual patching rules (in-band blocking)
198+
- crowdsecurity/crs-inband # OWASP CRS rules (in-band blocking)
199+
labels:
200+
type: appsec
201+
listen_addr: 127.0.0.1:7422
202+
source: appsec
203+
name: myAppSecComponent
204+
```
205+
206+
```bash title="Restart CrowdSec"
207+
sudo systemctl restart crowdsec
208+
```
209+
210+
#### How to Test Step 3: CRS In-band Blocking
211+
212+
After configuring CRS for in-band (blocking) mode, test that both virtual patching and CRS rules provide immediate blocking:
213+
214+
**Test 1: Virtual Patching Layer (Still Blocking)**
215+
216+
Verify virtual patching continues to work:
217+
218+
```bash
219+
# These should still be immediately blocked
220+
curl -v "http://your-app.com/.env"
221+
```
222+
223+
Expected result: HTTP 403 Forbidden immediately.
224+
225+
**Test 2: CRS In-band Blocking**
226+
227+
Test that CRS rules now block requests immediately (no more out-of-band delay):
228+
229+
```bash
230+
TARGET="http://your-app.com"
231+
232+
# SQL injection - should be blocked immediately
233+
curl -v "$TARGET/?id=1' OR '1'='1"
234+
235+
# XSS - should be blocked immediately
236+
curl -v "$TARGET/?q=<script>alert('xss')</script>"
237+
238+
# Command injection - should be blocked immediately
239+
curl -v "$TARGET/?cmd=; cat /etc/passwd"
240+
241+
# Path traversal - should be blocked immediately
242+
curl -v "$TARGET/?file=../../../etc/passwd"
243+
```
244+
245+
**Expected behavior:**
246+
- **All requests above**: Immediately blocked with HTTP 403 Forbidden
247+
- **No delay**: Unlike out-of-band mode, blocking is instant
248+
- **Dual protection**: Both virtual patching AND CRS rules provide immediate blocking
249+
250+
:::warning Important Considerations
251+
In-band CRS blocking provides maximum protection but requires:
252+
- **Thorough testing** in a staging environment
253+
- **Gradual rollout** to production traffic
254+
- **Monitoring and tuning** to prevent blocking legitimate requests
255+
- **Whitelisting capabilities** for false positives
256+
:::
257+
258+
## Next Steps
259+
260+
Once you've implemented advanced deployments:
261+
262+
- Configure [Custom Rules](/appsec/create_rules.md) for application-specific protection
263+
- Set up [Hooks](/appsec/hooks.md) for custom response actions
264+
- Explore [Configuration Options](/appsec/configuration.md) for fine-tuning
265+
- Review [Troubleshooting Guide](/appsec/troubleshooting.md) for operational issues

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,8 @@ Configure CrowdSec to expose the AppSec Component by creating an acquisition fil
5454
2. Create the AppSec acquisition configuration:
5555
```bash
5656
sudo cat > /etc/crowdsec/acquis.d/appsec.yaml << EOF
57-
appsec_config: crowdsecurity/appsec-default
57+
appsec_configs:
58+
- crowdsecurity/appsec-default
5859
labels:
5960
type: appsec
6061
listen_addr: 127.0.0.1:7422

0 commit comments

Comments
 (0)