Skip to content

Commit 55a5bc5

Browse files
buixorbuixor
committed
up
1 parent 0f50f8f commit 55a5bc5

File tree

3 files changed

+287
-2
lines changed

3 files changed

+287
-2
lines changed

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

Lines changed: 284 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,284 @@
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`
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` (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: Configure CRS for in-band (blocking) mode 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` 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/virtual-patching # 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/crowdsec-appsec-outofband` scenario monitors for multiple attack attempts and bans IPs after 5+ out-of-band rule violations within the configured timeframe. Test with various attack patterns:
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+
curl "$TARGET/?id=1+UNION+SELECT+*+FROM+users"
126+
curl "$TARGET/?search='+OR+1=1--"
127+
curl "$TARGET/?filter=admin'/**/OR/**/'1'='1"
128+
129+
# XSS attempts
130+
curl "$TARGET/?q=<script>alert('xss')</script>"
131+
curl "$TARGET/?comment=<img src=x onerror=alert(1)>"
132+
133+
# Command injection attempts
134+
curl "$TARGET/?cmd=; cat /etc/passwd"
135+
curl "$TARGET/?exec=|whoami"
136+
137+
# Additional malicious patterns to reach the 5+ threshold
138+
curl "$TARGET/?test=../../../etc/passwd"
139+
curl "$TARGET/?file=....//....//etc/hosts"
140+
141+
# Wait 10-15 seconds for the scenario to process and ban the IP
142+
sleep 15
143+
144+
# Test if IP is now banned
145+
curl "$TARGET/" # This should now be blocked
146+
```
147+
148+
**Expected behavior:**
149+
1. **First 1-4 requests**: Pass through to your application (out-of-band mode)
150+
2. **After 5+ violations**: CrowdSec processes the violations (may take up to 10 seconds)
151+
3. **After ~10 seconds**: IP gets banned by the `crowdsec-appsec-outofband` scenario
152+
4. **Subsequent requests**: Blocked at CrowdSec level before reaching your application
153+
154+
:::info Processing Delay
155+
The out-of-band scenario processes violations asynchronously, so there's typically a 5-10 second delay between reaching the violation threshold and the IP ban taking effect. This is normal behavior for out-of-band detection.
156+
:::
157+
158+
**Test 3: Verify Out-of-band Alerts (Optional)**
159+
160+
To see individual out-of-band rule triggers (not just the ban), add a dedicated appsec config:
161+
162+
```yaml title="Add to /etc/crowdsec/acquis.d/appsec.yaml for detailed alerts"
163+
appsec_configs:
164+
- crowdsecurity/virtual-patching # Virtual patching rules (in-band blocking)
165+
- crowdsecurity/crs # OWASP CRS rules (out-of-band detection)
166+
- crowdsecurity/crs-alert # Generate alert for each CRS rule triggered
167+
```
168+
169+
This will create individual alerts for each out-of-band rule violation, providing better visibility into attack patterns.
170+
171+
**Verification Commands:**
172+
173+
```bash
174+
# Check for active bans
175+
sudo cscli decisions list
176+
177+
# Review recent alerts (including out-of-band detections)
178+
sudo cscli alerts list --limit 10
179+
180+
# Monitor real-time activity
181+
sudo tail -f /var/log/crowdsec.log
182+
```
183+
184+
<!-- ![Screenshot placeholder: CrowdSec Console showing out-of-band detection alerts and IP bans](placeholder-outofband-alerts.png) -->
185+
186+
### Step 3: CRS In-band (Blocking Mode)
187+
188+
For organizations requiring maximum protection, configure CRS rules to block requests immediately by installing the in-band CRS collection:
189+
190+
```bash title="Install CRS in-band collection"
191+
sudo cscli collections install crowdsecurity/appsec-crs-inband
192+
```
193+
194+
#### Update Acquisition Configuration
195+
196+
Modify your acquisition to use the in-band CRS configuration:
197+
198+
```yaml title="/etc/crowdsec/acquis.d/appsec.yaml"
199+
appsec_configs:
200+
- crowdsecurity/virtual-patching # Virtual patching rules (in-band blocking)
201+
- crowdsecurity/crs-inband # OWASP CRS rules (in-band blocking)
202+
labels:
203+
type: appsec
204+
listen_addr: 127.0.0.1:7422
205+
source: appsec
206+
name: myAppSecComponent
207+
```
208+
209+
```bash title="Restart CrowdSec"
210+
sudo systemctl restart crowdsec
211+
```
212+
213+
#### How to Test Step 3: CRS In-band Blocking
214+
215+
After configuring CRS for in-band (blocking) mode, test that both virtual patching and CRS rules provide immediate blocking:
216+
217+
**Test 1: Virtual Patching Layer (Still Blocking)**
218+
219+
Verify virtual patching continues to work:
220+
221+
```bash
222+
# These should still be immediately blocked
223+
curl -v "http://your-app.com/.env"
224+
curl -v "http://your-app.com/.git/config"
225+
```
226+
227+
Expected result: HTTP 403 Forbidden immediately.
228+
229+
**Test 2: CRS In-band Blocking**
230+
231+
Test that CRS rules now block requests immediately (no more out-of-band delay):
232+
233+
```bash
234+
TARGET="http://your-app.com"
235+
236+
# SQL injection - should be blocked immediately
237+
curl -v "$TARGET/?id=1' OR '1'='1"
238+
239+
# XSS - should be blocked immediately
240+
curl -v "$TARGET/?q=<script>alert('xss')</script>"
241+
242+
# Command injection - should be blocked immediately
243+
curl -v "$TARGET/?cmd=; cat /etc/passwd"
244+
245+
# Path traversal - should be blocked immediately
246+
curl -v "$TARGET/?file=../../../etc/passwd"
247+
```
248+
249+
**Expected behavior:**
250+
- **All requests above**: Immediately blocked with HTTP 403 Forbidden
251+
- **No delay**: Unlike out-of-band mode, blocking is instant
252+
- **Dual protection**: Both virtual patching AND CRS rules provide immediate blocking
253+
254+
**Verification Commands:**
255+
256+
```bash
257+
# Check for immediate decisions (should see blocks right after requests)
258+
sudo cscli decisions list
259+
260+
# Review alerts (should see both virtual patching and CRS alerts)
261+
sudo cscli alerts list --limit 5
262+
263+
# Monitor real-time blocking
264+
sudo tail -f /var/log/crowdsec.log
265+
```
266+
267+
<!-- ![Screenshot placeholder: CrowdSec Console showing immediate in-band CRS blocks](placeholder-inband-blocks.png) -->
268+
269+
:::warning Important Considerations
270+
In-band CRS blocking provides maximum protection but requires:
271+
- **Thorough testing** in a staging environment
272+
- **Gradual rollout** to production traffic
273+
- **Monitoring and tuning** to prevent blocking legitimate requests
274+
- **Whitelisting capabilities** for false positives
275+
:::
276+
277+
## Next Steps
278+
279+
Once you've implemented advanced deployments:
280+
281+
- Configure [Custom Rules](/appsec/create_rules.md) for application-specific protection
282+
- Set up [Hooks](/appsec/hooks.md) for custom response actions
283+
- Explore [Configuration Options](/appsec/configuration.md) for fine-tuning
284+
- 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

‎crowdsec-docs/sidebars.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -728,7 +728,7 @@ const sidebarsConfig: SidebarConfig = {
728728
label: "Configuration",
729729
items: [
730730
{ type: "doc", id: "appsec/configuration" },
731-
{ type: "doc", id: "appsec/vpatch_and_crs" },
731+
{ type: "doc", id: "appsec/advanced_deployments" },
732732
{ type: "doc", id: "appsec/alerts_and_scenarios" },
733733
],
734734
},

0 commit comments

Comments
 (0)