You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Configuring the AppSec Component usually requires the use of multiple files:
9
+
This section covers the detailed configuration options for the CrowdSec AppSec Component.
10
10
11
-
-[AppSec rules](/appsec/rules_syntax.md) allow you to write a signature to detect and/or block malevolent requests. [You can find more information about the syntax here](/appsec/rules_syntax.md)
12
-
-[Acquisition configuration](/log_processor/data_sources/appsec.md) indicates which port is the AppSec Component listening on, and which AppSec configuration it will use.
13
-
- AppSec configuration tells which rules are loaded in in-band (blocking) and out-of-band (non-blocking)
14
-
phases. [it as well allows you to tweak the behavior of the component via the powerful expr bindings](/appsec/rules_syntax.md)
11
+
**Prerequisites**:
12
+
- Familiarity with [AppSec concepts](/appsec/intro.md)
13
+
- Basic AppSec setup completed (see Getting Started guides)
15
14
16
-
## Acquisition configuration
15
+
The AppSec Component configuration consists of three main parts:
17
16
18
-
## Default configuration
17
+
-**[Acquisition configuration](/log_processor/data_sources/appsec.md)**: Defines which port the AppSec Component listens on and which AppSec configurations to load <!-- Fix linked page to ie. speak about appsec_configs-->
18
+
-**AppSec configurations**: Define which rules are loaded and how they behave, along with [hooks](/appsec/hooks.md) for runtime customization
19
+
-**[AppSec rules](/appsec/rules_syntax.md)**: The actual detection signatures that identify and block malicious requests
19
20
20
-
The Acquisition configuration is usually present directly within `/etc/crowdsec/acquis.d/` or `/etc/crowdsec/acquis.yaml`:
21
+
##Acquisition Configuration
21
22
22
-
> The default AppSec acquisition configuration
23
-
```yaml
24
-
appsec_config: crowdsecurity/appsec-default
23
+
### Multiple AppSec Configurations
24
+
25
+
Use `appsec_configs` to load multiple configurations that work together:
- crowdsecurity/crs # Out-of-band detection based on ModSec CRS - from crowdsecurity/appsec-crs collection
25
31
labels:
26
32
type: appsec
27
33
listen_addr: 127.0.0.1:7422
28
34
source: appsec
29
35
```
30
36
31
-
## Creating custom configuration
37
+
:::info
38
+
Do not forget to `sudo cscli collections install crowdsecurity/appsec-crs`.
39
+
This collection installs OWASP CRS in out-of-band and adds a scenario to ban IPs triggering multiple rules.
40
+
:::
32
41
42
+
### Creating Custom Configurations
33
43
34
-
If you want to add some custom rules or hooks, it is suggested to add a custom `appsec_config`.
35
-
Modifying existing `appsec_config` will make it *tainted* and will interfere with future updates.
44
+
Create new configuration files instead of modifying existing hub configurations. Modifying hub configurations will make them *tainted* and prevent automatic updates.
When loading several app sec configs, _hooks_ and _appsec rules_ are appended, and for conflicting options (e.g., `default_remediation`), the last one takes precedence.
When loading multiple AppSec configs, _hooks_ and _appsec rules_ are appended, and for conflicting options (e.g., `default_remediation`), the last one takes precedence.
68
+
:::
69
+
70
+
## Configuration Processing Order
71
+
72
+
When multiple AppSec configurations are loaded, they are processed in the order specified in the `appsec_configs` list. For details on how in-band and out-of-band rules work, see the [AppSec Introduction](/appsec/intro.md#inband-rules-and-out-of-band-rules).
73
+
74
+
### Multi-Config Rule Evaluation
75
+
76
+
1. All `inband_rules` from all configurations are combined and evaluated together
77
+
2. All `outofband_rules` from all configurations are combined and evaluated together
78
+
3. Hooks from all configurations are executed in the order the configurations are listed
79
+
4. For conflicting configuration options (like `default_remediation`), the last configuration's value takes precedence
80
+
81
+
## AppSec Configuration Reference
82
+
83
+
Each AppSec configuration file defines how rules are loaded and processed. Here's the complete reference of available directives:
84
+
85
+
### Core Configuration Directives
86
+
87
+
#### `name` (required)
88
+
Unique identifier for the AppSec configuration, used for logging and referencing.
89
+
90
+
```yaml
91
+
name: custom/my-appsec-config
92
+
```
93
+
94
+
#### `inband_rules` (optional)
95
+
List of rule patterns to load as in-band rules. See [in-band rule processing](/appsec/intro.md#inband-rule-processing) for details.
96
+
97
+
```yaml
98
+
inband_rules:
99
+
- crowdsecurity/base-config
100
+
- crowdsecurity/vpatch-*
101
+
- custom/critical-patches
102
+
```
103
+
104
+
#### `outofband_rules` (optional)
105
+
List of rule patterns to load as out-of-band rules. See [out-of-band rule processing](/appsec/intro.md#out-of-band-rules-processing) for details.
Executed after rule evaluation. Useful for debugging and analysis.
200
+
201
+
```yaml
202
+
post_eval:
203
+
- filter: IsInBand
204
+
apply:
205
+
- DumpRequest().WithBody().ToJSON()
206
+
```
207
+
208
+
#### `on_match`
209
+
Executed when rules match. Used to modify remediation or generate custom alerts.
210
+
211
+
```yaml
212
+
on_match:
213
+
- filter: req.URL.Host == "staging.example.com"
214
+
apply:
215
+
- SetRemediation("allow")
216
+
- CancelAlert()
217
+
```
218
+
219
+
For complete hook documentation, see [AppSec Hooks](/appsec/hooks.md).
220
+
221
+
## Rule Management
62
222
63
-
Even though we try to provide rules without false positives, sometimes a virtual patching rule can block legitimate requests on a website.
223
+
### Disabling Rules at Runtime
64
224
65
225
You can disable rules at runtime, either globally (for all requests) or based on specific conditions (source IP, URI, ...).
66
226
67
-
You can can disable rules by:
68
-
- Name with `RemoveInBandRuleByName`: Intended for disabling rules provided by crowdsec (the name is the name of the appsec-rule as seen in `cscli appsec-rules list`).
69
-
- ID with `RemoveInBandRuleByID`: Intended for disabling seclang rules
70
-
- Tag with `RemoveInBandRuleByTag`: Intended for disabling seclang rules
227
+
You can disable rules by:
228
+
- Name with `RemoveInBandRuleByName`: For CrowdSec rules (name as seen in `cscli appsec-rules list`)
229
+
- ID with `RemoveInBandRuleByID`: For seclang/ModSecurity rules by numeric ID
230
+
- Tag with `RemoveInBandRuleByTag`: For seclang/ModSecurity rules by tag
71
231
72
-
The same functions exist for out-of-band rules, prefixed with `RemovedOutBandRuleBy...`
232
+
The same functions exist for out-of-band rules, prefixed with `RemoveOutBandRuleBy...`
73
233
74
-
To disable a rule, we'll first create a new `appsec-config` to avoid tainting the configuration from the hub (if you are already using a custom configuration, you can update this one instead).
234
+
To disable a rule, create a new AppSec config to avoid tainting the configuration from the hub (or update your existing custom configuration).
We are using the [hooks](/docs/appsec/hooks.md) provided by the appsec to modify the configuration in 2 places:
88
-
- `on_load`: Expressions here will be applied when crowdsec loads the configuration, effectively disabling the rule `crowdsecurity/vpatch-env-access` globally.
247
+
This example uses [hooks](/docs/appsec/hooks.md) to modify the configuration in 2 places:
248
+
- `on_load`: Expressions here will be applied when CrowdSec loads the configuration, effectively disabling the rule `crowdsecurity/vpatch-env-access` globally.
89
249
- `pre_eval`: Expressions here will be applied only if the provided filter matches. In this example, we are disabling the rule `crowdsecurity/generic-wordpress-uploads-php` only if the request URI starts with `/blog/` and if we are currently processing in-band rules.
90
250
91
251
You can also disable native (seclang) rules by providing their ID with the `RemoveInBandRuleByID` helper. See the [hooks](appsec/hooks.md) documentation for a list of available helpers.
92
252
93
253
Also note that we are not loading any rules in our custom config: the rules are loaded by the `crowdsecurity/appsec-default` config, and we are just modifying the runtime behavior with this config.
94
254
95
-
Finally, we need to tell crowdsec to load our new config:
255
+
Finally, add your new config to the acquisition configuration:
If your reverse-proxy forwards all requests to crowdsec, regardless of the FQDN, you can disable the appsec for specific domain with a custom appsec-config (ie, the request will be always allowed):
289
+
If your reverse-proxy forwards all requests to CrowdSec regardless of the FQDN, you can disable AppSec for specific domains with a custom AppSec config (the request will always be allowed):
0 commit comments