Skip to content

Commit 98dd524

Browse files
blotusblotus
authored
add v1.7 to docs (#866)
1 parent 831c782 commit 98dd524

File tree

268 files changed

+28610
-1
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

268 files changed

+28610
-1
lines changed

‎crowdsec-docs/docusaurus.config.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -273,7 +273,7 @@ const config: Config = {
273273
editUrl: "https://github.com/crowdsecurity/crowdsec-docs/edit/main/crowdsec-docs/",
274274
lastVersion: "current",
275275
versions: {
276-
"v1.6": {
276+
"v1.7": {
277277
banner: "none",
278278
path: "/",
279279
},

‎crowdsec-docs/versioned_docs/version-v1.7/appsec/alerts_and_scenarios.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
id: alerts_and_scenarios
3+
title: Alerts & Scenarios
4+
sidebar_position: 5
5+
---
6+
7+
## Generated Events Layout
8+
9+
HTTP requests that trigger _In-Band_ or _Out-Of-Band_ AppSec/WAF rules generate events. These events can trigger scenarios that react by banning or alerting when rules are matched.
10+
11+
The [`crowdsecurity/appsec-logs` parser](https://app.crowdsec.net/hub/author/crowdsecurity/configurations/appsec-logs) is designed as a general-purpose tool to convert events into a format that is easier to process with scenarios.
12+
13+
14+
The generated event looks like this:
15+
16+
- `evt.Meta.service` is set to `appsec`
17+
- `evt.Meta.log_type`:
18+
- `appsec-block` for blocked requests (_In-Band_ rule matched, for example)
19+
- `appsec-info` for requests that triggered _Out-Of-Band_ rule (not blocked)
20+
- `evt.Meta.source_ip` is set to the source (client) IP
21+
- `evt.Meta.target_host` is set to the FQDN if present (`Host` header in the HTTP request)
22+
- `evt.Meta.target_uri` is set to the complete URI of the HTTP request
23+
- `evt.Meta.rule_name` is set to the name of the triggered rule
24+
- `evt.Meta.remediation_cmpt_ip` is set to the IP of the Remediation Component (Bouncer) that sent the HTTP request.
25+
26+
:::info
27+
The [`crowdsecurity/appsec-logs` parser](https://app.crowdsec.net/hub/author/crowdsecurity/configurations/appsec-logs) is already part of the generic AppSec/WAF collections and doesn't have to be manually installed.
28+
:::
29+
30+
31+
## Creating Scenario Based on AppSec/WAF Events
32+
33+
### Triggering on _In-Band_ Rules
34+
35+
A simple yexample is the [`crowdsecurity/appsec-vpatch` scenario](https://app.crowdsec.net/hub/author/crowdsecurity/configurations/appsec-vpatch) that will ban IPs triggering two distinct _In-Band_ rules:
36+
37+
```yaml title="/etc/crowdsec/scenarios/appsec-vpatch.yaml"
38+
type: leaky
39+
name: crowdsecurity/appsec-vpatch
40+
filter: "evt.Meta.log_type == 'appsec-block'"
41+
distinct: evt.Meta.rule_name
42+
leakspeed: "60s"
43+
capacity: 1
44+
groupby: evt.Meta.source_ip
45+
...
46+
```
47+
48+
:::info
49+
The [`crowdsecurity/appsec-vpatch` scenario](https://app.crowdsec.net/hub/author/crowdsecurity/configurations/appsec-vpatch) is already part of the generic AppSec/WAF collections, and doesn't have to be manually installed.
50+
:::
51+
52+
### Triggering on Out-Of-Band Rules
53+
54+
Let's try to solve an imaginary scenario:
55+
56+
> We aim to prevent users from enumerating certain URLs (specifically, those that begin with `/foobar/*`) when a particular HTTP header is present (`something: *test*`). However, we want to impose this restriction only on users attempting to access two or more distinct `/foobar/*` URLs while this header is set.
57+
58+
:::info
59+
Keep in mind that _Out-Of-Band_ rules will generate an event instead of blocking the HTTP Request.
60+
:::
61+
62+
#### The AppSec/WAF Rule
63+
64+
This is our AppSec/WAF rule:
65+
66+
```yaml title="/etc/crowdsec/appsec-rules/foobar-access.yaml"
67+
name: crowdsecurity/foobar-access
68+
description: "Detect access to foobar files with the something header set"
69+
rules:
70+
- zones:
71+
- URI
72+
transform:
73+
- lowercase
74+
match:
75+
type: startsWith
76+
value: /foobar/
77+
- zones:
78+
- HEADERS
79+
variables:
80+
- something
81+
transform:
82+
- lowercase
83+
match:
84+
type: contains
85+
value: test
86+
```
87+
88+
Let ensure it's loaded as an _Out-Of-Band_ rule, first by creating a new appsec-config:
89+
90+
```yaml title="/etc/crowdsec/appsec-configs/appsec-oob.yaml"
91+
name: crowdsecurity/appsec-oob
92+
default_remediation: ban
93+
#Let's add our rule as an out-of-band rule
94+
outofband_rules:
95+
- crowdsecurity/foobar-access
96+
```
97+
98+
And then make sure this appsec-config is loaded:
99+
100+
```yaml title="/etc/crowdsec/acquis.d/appsec.yaml"
101+
appsec_configs:
102+
- crowdsecurity/appsec-default
103+
- crowdsecurity/appsec-oob
104+
labels:
105+
type: appsec
106+
listen_addr: 127.0.0.1:7422
107+
source: appsec
108+
```
109+
110+
#### The Scenario
111+
112+
We can now create a scenario that will trigger when a single IPs triggers this rule on distinct URLs:
113+
114+
```yaml title="/etc/crowdsec/scenarios/foobar-enum.yaml"
115+
type: leaky
116+
format: 3.0
117+
name: crowdsecurity/foobar-enum
118+
description: "Ban IPs repeatedly triggering out of band rules"
119+
filter: "evt.Meta.log_type == 'appsec-info' && evt.Meta.rule_name == 'crowdsecurity/foobar-access'"
120+
distinct: evt.Meta.target_uri
121+
leakspeed: "60s"
122+
capacity: 1
123+
groupby: evt.Meta.source_ip
124+
blackhole: 1m
125+
labels:
126+
remediation: true
127+
```
128+
129+
:::info
130+
The `filter` ensures only _Out-Of-Band_ events generated by our scenario are picked up, while the `capacity: 1` and `distinct: evt.Meta.target_uri` will ensure that the IP has to trigger the rule on at least 2 distinct URLs to trigger the scenario.
131+
:::
132+
133+
#### Testing
134+
135+
Let's now test our setup:
136+
137+
```bash
138+
$ curl -I localhost/foobar/1 -H 'something: test'
139+
HTTP/1.1 404 Not Found
140+
141+
$ curl -I localhost/foobar/2 -H 'something: test'
142+
HTTP/1.1 404 Not Found
143+
144+
$ curl -I localhost/foobar/3 -H 'something: test'
145+
HTTP/1.1 403 Forbidden
146+
```
147+
148+
And CrowdSec logs will show:
149+
150+
```
151+
INFO[2024-12-02T15:28:16+01:00] Ip ::1 performed 'crowdsecurity/foobar-enum' (2 events over 4.780233613s) at 2024-12-02 14:28:16.858419797 +0000 UTC
152+
INFO[2024-12-02T15:28:17+01:00] (test/crowdsec) crowdsecurity/foobar-enum by ip ::1 (/0) : 4h ban on Ip ::1
153+
```
154+
155+
As expected, the first two requests were processed without being blocked. The second one triggered the scenario, resulting in the third request being blocked by the bouncer.

‎crowdsec-docs/versioned_docs/version-v1.7/appsec/benchmark.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
id: benchmark
3+
title: WAF Component Benchmark
4+
sidebar_position: 80
5+
---
6+
7+
<!--
8+
9+
- benchmark as previously done by KKA
10+
11+
- naked
12+
- with a few vpatch rules
13+
- with full CRS
14+
- ?!
15+
16+
-->
17+
18+
The Application Security Component benchmarks have been run on a AWS EC2 Instance `t2.medium` (2vCPU/4GiB RAM).
19+
20+
All the benchmarks have been run with only one `routine` configured for the Application Security Component.
21+
22+
The benchmarks cover the following tests:
23+
24+
- Basic GET request:
25+
- 5 concurrent connections / 1000 requests
26+
- 15 concurrent connections / 1000 requests
27+
28+
<!--- POST request (50Ko body):
29+
- 5 concurrent connections / 1000 requests
30+
- 15 concurrent connections / 1000 requests
31+
-->
32+
33+
Each test has been run with multiple cases:
34+
35+
- Application Security Component enabled but without any rules
36+
- Application Security Component enabled with 100 vpatch rules (in in-band)
37+
- Application Security Component enabled with all the CRS (in in-band)
38+
39+
On the system, we deployed:
40+
41+
- Openresty `1.21.4.3`
42+
- CrowdSec `v1.6.0`
43+
- cs-openresty-bouncer `v1.0.1`
44+
45+
## Basic GET request
46+
47+
### 5 concurrent connections / 1000 requests
48+
49+
![5 concurrent connections / 1000 requests](/img/appsec/bench/basic_get_appsec_one_routine_5_1000.png)
50+
51+
### 15 concurrent connections / 1000 requests
52+
53+
![15 concurrent connections / 1000 requests](/img/appsec/bench/basic_get_appsec_one_routine_15_1000.png)
54+
55+
<!--
56+
## POST request (50Ko body)
57+
58+
### 5 concurrent connections / 1000 requests
59+
60+
![5 concurrent connections / 1000 requests](/img/appsec/bench/big_post_appsec_one_routine_5_1000.png)
61+
62+
### 15 concurrent connections / 1000 requests
63+
64+
![15 concurrent connections / 1000 requests](/img/appsec/bench/big_post_appsec_one_routine_15_1000.png)
65+
-->

0 commit comments

Comments
 (0)