Skip to content

Commit 35577cc

Browse files
AlteredCoderAlteredCoder
committed
Merge remote-tracking branch 'origin' into update_cti_format_documentation
2 parents 3729654 + 114c498 commit 35577cc

Some content is hidden

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

45 files changed

+1453
-384
lines changed

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
id: benchmark
3-
title: Benchmark
3+
title: CrowdSec WAF / AppSec Component Benchmark
44
sidebar_position: 80
55
---
66

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
id: configuration
3-
title: Configuration Files
3+
title: AppSec Component Configuration Files
44
sidebar_position: 6
55
---
66

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
id: create_rules
3-
title: Create Rules
3+
title: Create AppSec Rules
44
sidebar_position: 3
55
---
66

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
id: hooks
3-
title: Hooks
3+
title: AppSec Component Hooks
44
sidebar_position: 4
55
---
66

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
id: installation
3-
title: Installation
3+
title: AppSec Component Installation
44
sidebar_position: 3
55
---
66

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
---
22
id: intro
3-
title: Introduction
3+
title: AppSec Component - CrowdSec WAF
44
sidebar_position: 1
55
---
66

77
## Introduction
88

99
<!-- xx : fix crowdsec version -->
1010

11-
Meet the Crowdsec **Application Security Component** (AKA : **AppSec Component**), a new capability for advanced application security:
11+
Meet the Crowdsec **Application Security Component** (AKA : **AppSec Component**), a new capability for advanced application security turning your CrowdSec install into a full fledged **WAF**.
1212

1313
The **AppSec Component** offers:
1414

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
id: protocol
3-
title: Protocol
3+
title: AppSec Component Communication Protocol
44
sidebar_position: 5
55
---
66

‎crowdsec-docs/docs/appsec/quickstart.md‎ renamed to ‎crowdsec-docs/docs/appsec/quickstart/nginxopenresty.mdx‎

Lines changed: 117 additions & 54 deletions
Large diffs are not rendered by default.

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

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
---
2+
id: traefik
3+
title: Traefik
4+
---
5+
6+
import FormattedTabs from '@site/src/components/FormattedTabs';
7+
8+
# CrowdSec WAF QuickStart for Traefik
9+
10+
## Objectives
11+
12+
The goal of this quickstart is to set up the [AppSec Component](/appsec/intro.md#introduction) to safeguard web applications running on [Traefik](https://doc.traefik.io/traefik/) reverse proxy.
13+
14+
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).
15+
16+
Additionally, we'll show how to monitor these alerts through the [console](https://app.crowdsec.net/).
17+
18+
## Pre-requisites
19+
20+
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.
21+
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). The AppSec Component, which analyzes HTTP requests, is included within the security engine as a [Acquisition](data_sources/appsec.md).
24+
- Traefik Plugin **[Remediation Component](/u/bouncers/intro)**: Thanks to [maxlerebourg](https://github.com/maxlerebourg) and team they created a [Traefik Plugin](https://plugins.traefik.io/plugins/6335346ca4caa9ddeffda116/crowdsec-bouncer-traefik-plugin) that allows you to block requests directly from Traefik.
25+
26+
:::info
27+
Prior to starting the guide ensure you are using the [Traefik Plugin](https://plugins.traefik.io/plugins/6335346ca4caa9ddeffda116/crowdsec-bouncer-traefik-plugin) and **NOT** the older [traefik-crowdsec-bouncer](https://app.crowdsec.net/hub/author/fbonalair/remediation-components/traefik-crowdsec-bouncer) as it hasnt recieved updates to use the new AppSec Component.
28+
:::
29+
30+
:::warning
31+
This guide will assume you already have a working Traefik setup using the Traefik Plugin. If you need help setting up Traefik, refer to the [official documentation](https://doc.traefik.io/traefik/) and the [Traefik Plugin](https://plugins.traefik.io/plugins/6335346ca4caa9ddeffda116/crowdsec-bouncer-traefik-plugin) documentation.
32+
:::
33+
34+
## AppSec Component Setup
35+
36+
### Collection installation
37+
38+
To begin setting up the AppSec Component, the initial step is to install a relevant set of rules.
39+
40+
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.
41+
42+
This [collection](/concepts.md#collections) is regularly updated to include protection against newly discovered vulnerabilities. Upon installation, it receives automatic daily updates to ensure your protection is always current.
43+
44+
Furthermore 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 some protection in cases where specific scenarios for vulnerabilities do not exist (yet).
45+
46+
On the machine where the Security Engine is installed, just execute the following command:
47+
48+
:::info
49+
You can always view the content of a [collection on the hub](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-virtual-patching)
50+
:::
51+
52+
<FormattedTabs
53+
docker={`## This command should be used when you are persisting /etc/crowdsec/ on the host
54+
docker exec -it crowdsec cscli collections install crowdsecurity/appsec-virtual-patching crowdsecurity/appsec-generic-rules`}
55+
dockerCompose={`services:
56+
crowdsec:
57+
environment
58+
## Please note the spaces between the collections names (hence why the quotes are needed)
59+
- 'COLLECTIONS=crowdsecurity/appsec-virtual-patching crowdsecurity/appsec-generic-rules'`}
60+
/>
61+
62+
Executing this command or updating the compose will install the following items:
63+
64+
- The [*AppSec Rules*](/appsec/rules_syntax.md) contain the definition of malevolent requests to be matched and stopped.
65+
- The [*AppSec Configuration*](/appsec/configuration.md#appsec-configuration) links together a set of rules to provide a coherent set.
66+
- The [*CrowdSec Parser*](/concepts.md#parsers) and [*CrowdSec Scenario(s)*](/concepts.md#scenarios) are used to detect and remediate persistent attacks.
67+
68+
Once you have updated your compose or installed via the command line, will we need to restart the container. However, before we do that, we need to setup the acquisition for the AppSec Component.
69+
70+
### Setup the Acquisition
71+
72+
Depending on how you are running the CrowdSec Security Engine, you will need to configure the acquisition for the AppSec Component.
73+
74+
If you have a folder in which you are persisting the configuration files, you can create a `appsec.yaml` and mount it into the container.
75+
76+
There steps will change depending on how you are running the Security Engine. If you are running via `docker run` then you should launch the container within the same directory as the `appsec.yaml` file. If you are using `docker-compose` you can use a relative file mount to mount the `appsec.yaml` file.
77+
78+
Steps:
79+
1. Change to the location where you exectued the `docker run` or `docker compose` command.
80+
2. Create a `appsec.yaml` file at the base of the directory.
81+
3. Add the following content to the `appsec.yaml` file.
82+
83+
```yaml title="appsec.yaml"
84+
appsec_config: crowdsecurity/appsec-default
85+
labels:
86+
type: appsec
87+
listen_addr: 0.0.0.0:7422
88+
source: appsec
89+
```
90+
:::note
91+
Since CrowdSec is running inside a container you must set the `listen_addr` to `0.0.0.0` instead of the typical `127.0.0.1` as the container is running in a separate network.
92+
:::
93+
94+
4. Edit the `docker run` or `docker-compose` command to include the `appsec.yaml` file.
95+
96+
<FormattedTabs
97+
docker={`# Note if you have a docker run already running you will need to stop it before running this command
98+
docker run -d --name crowdsec -v /path/to/orginal:/etc/crowdsec -v ./appsec.yaml:/etc/crowdsec/acquis.d/appsec.yaml crowdsecurity/crowdsec`}
99+
dockerCompose={`services:
100+
crowdsec:
101+
volumes:
102+
- /path/to/orginal:/etc/crowdsec ## or named volumes
103+
- ./appsec.yaml:/etc/crowdsec/acquis.d/appsec.yaml`}
104+
/>
105+
106+
Once you have created the `appsec.yaml` file and mounted it into the container, you can recreate the container.
107+
108+
:::note
109+
If you are using `docker run` you can skip to the [Remediation Component Setup](#remediation-component-setup) section.
110+
:::
111+
112+
Once you have updated the compose file to include the volume mount and the updated environment variable, you can restart the container.
113+
114+
```bash
115+
docker compose down crowdsec
116+
docker compose rm crowdsec
117+
docker compose up -d crowdsec
118+
```
119+
120+
:::note
121+
The previous compose commands presume the container is named `crowdsec`. If you have named the container something else, you will need to replace `crowdsec` with the name of your container.
122+
:::
123+
124+
## Remediation Component Setup
125+
126+
As stated previously this guide already presumes you have the Traefik Plugin installed. If you do not have the Traefik Plugin installed, please refer to the [official documentation](https://plugins.traefik.io/plugins/6335346ca4caa9ddeffda116/crowdsec-bouncer-traefik-plugin) for installation instructions.
127+
128+
### Configuration
129+
130+
Depending on how you configured the Traefik Plugin, you will need to update the configuration to include the AppSec configuration.
131+
132+
:::warning
133+
Currently AppSec does not support mTLS authentication for the AppSec Component. If you have mTLS enabled, and wish to use the AppSec Component, you can define seperate middlewares for the AppSec Component.
134+
:::
135+
136+
If you have defined a dynamic configuration file for Traefik, you can add the following configuration to the file.
137+
138+
```yaml title="traefik_dynamic.yaml"
139+
# Dynamic configuration
140+
http:
141+
routers:
142+
my-router:
143+
rule: host(`whoami.localhost`)
144+
service: service-foo
145+
entryPoints:
146+
- web
147+
middlewares:
148+
- crowdsec
149+
150+
services:
151+
service-foo:
152+
loadBalancer:
153+
servers:
154+
- url: http://127.0.0.1:5000
155+
156+
middlewares:
157+
crowdsec:
158+
plugin:
159+
bouncer:
160+
crowdsecAppsecEnabled: true
161+
crowdsecAppsecHost: crowdsec:7422
162+
crowdsecAppsecFailureBlock: true
163+
crowdsecAppsecUnreachableBlock: true
164+
crowdsecLapiKey: privateKey-foo
165+
```
166+
167+
Instead if you define the configuration using labels on the containers you can add the following labels to the Traefik Plugin container.
168+
169+
```yaml
170+
labels:
171+
- "traefik.http.middlewares.crowdsec-bar.plugin.bouncer.crowdsecAppsecEnabled=true"
172+
- "traefik.http.middlewares.crowdsec-bar.plugin.bouncer.crowdsecAppsecHost=crowdsec:7422"
173+
- "traefik.http.middlewares.crowdsec-bar.plugin.bouncer.crowdsecLapiKey=privateKey-foo"
174+
```
175+
176+
For more comprehensive documentation on the Traefik Plugin configuration, please refer to the [official documentation](https://plugins.traefik.io/plugins/6335346ca4caa9ddeffda116/crowdsec-bouncer-traefik-plugin).
177+
178+
We can't cover all the possible configurations for Traefik in this guide, so please refer to the [official documentation](https://doc.traefik.io/traefik/) for more information.
179+
180+
### Directives
181+
182+
The following directives are available for the Traefik Plugin:
183+
184+
#### `crowdsecAppsecEnabled`
185+
> `bool`
186+
187+
Enable or disable the AppSec Component.
188+
189+
#### `crowdsecAppsecHost`
190+
> `string`
191+
192+
The host and port where the AppSec Component is running.
193+
194+
#### `crowdsecAppsecFailureBlock`
195+
> `bool`
196+
197+
If the AppSec Component returns `500` status code should the request be blocked.
198+
199+
#### `crowdsecAppsecUnreachableBlock`
200+
> `bool`
201+
202+
If the AppSec Component is unreachable should the request be blocked.
203+
204+
## Testing the AppSec Component + Remediation Component
205+
206+
:::note
207+
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.
208+
:::
209+
210+
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:
211+
212+
![appsec-denied](/img/appsec_denied.png)
213+
214+
We can also look at the metrics from `cscli metrics show appsec` it will display:
215+
- the number of requests processed by the AppSec Component
216+
- Individual rule matches
217+
218+
<details>
219+
<summary>Example Output</summary>
220+
221+
```bash title="sudo cscli metrics show appsec"
222+
Appsec Metrics:
223+
╭─────────────────┬───────────┬─────────╮
224+
│ Appsec Engine │ Processed │ Blocked │
225+
├─────────────────┼───────────┼─────────┤
226+
│ 127.0.0.1:7422/ │ 2 │ 1 │
227+
╰─────────────────┴───────────┴─────────╯
228+
229+
Appsec '127.0.0.1:7422/' Rules Metrics:
230+
╭─────────────────────────────────┬───────────╮
231+
│ Rule ID │ Triggered │
232+
├─────────────────────────────────┼───────────┤
233+
│ crowdsecurity/vpatch-env-access │ 1 │
234+
╰─────────────────────────────────┴───────────╯
235+
```
236+
237+
</details>
238+
239+
### Explanation
240+
241+
What happened in the test that we just did is:
242+
243+
1. We did a request (`localhost/.env`) to our local webserver
244+
2. Thanks to the Remediation Component configuration, forwarded the request to `http://127.0.0.1:7422`
245+
3. Our AppSec Component, listening on `http://127.0.0.1:7422` analyzed the request
246+
4. The request matches the [AppSec rule to detect .env access](https://app.crowdsec.net/hub/author/crowdsecurity/appsec-rules/vpatch-env-access)
247+
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
248+
6. The web server then presented us with the default "request blocked" page.
249+
250+
## Integration with the console
251+
252+
If you haven't yet, follow the guide about [how to enroll your Security Engine in the console](/u/getting_started/post_installation/console).
253+
254+
Once done, all your alerts, including the ones generated by the AppSec Component, are going to appear in the console:
255+
256+
![appsec-console](/img/appsec_console.png)
257+
258+
## Next steps
259+
260+
You are now running the AppSec Component on your Crowdsec Security Engine, congrats!
261+
262+
As the next steps, you can:
263+
- [Explore the hub](https://hub.crowdsec.net) to find more rules for your use case
264+
- Look at the [Rules syntax](/appsec/rules_syntax.md) and [creation process](/appsec/create_rules.md) to create your own and contribute
265+
- Take a look at [the benchmarks](/appsec/benchmark.md)

0 commit comments

Comments
 (0)