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 page explains the interraction between various files involved in AppSec configuration and the details about the processing pipeline AppSec request processing.
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 files 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
+
## AppSec Acquisition
21
22
22
-
> The default AppSec acquisition configuration
23
-
```yaml
24
-
appsec_config: crowdsecurity/appsec-default
23
+
The goals of the acquisition file are:
24
+
- To specify the **address** and **port** where the AppSec-enabled Remediation Component(s) will forward the requests to.
25
+
- And specify one or more [AppSec configuration files](#appsec-configuration) to use as definition of what rules to apply and how.
26
+
27
+
Details can be found in the [AppSec Datasource page](/log_processor/data_sources/apps).
28
+
29
+
### Defining Multiple AppSec Configurations
30
+
31
+
Often you will want to activate multiple AppSec configuration defining groups of rules that will be handled the same way.
32
+
33
+
Use the `appsec_configs`*(with an S)* parameter to load multiple configurations that work together.
34
+
35
+
In the following example we have two configurations:
36
+
- One with [CrowdSec default AppSec rules ↗️](https://app.crowdsec.net/hub/author/crowdsecurity/appsec-configurations/appsec-default) running in inband mode
37
+
- The other for the [CRS rules ↗️](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-crs) that by default run in out of band mode.
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.
AppSec configuration files declare **which rules to load** in the **in-band** *(blocking)* and/or **out-of-band** *(non-blocking)*, define how matches are handled (e.g., default remediation), and let you tweak processing via hooks like `on_load`, `pre_eval`, `post_eval`, and `on_match`.
86
+
87
+
For details, jump to the [Configuration properties list](#appendix-appsec-configuration-properties)
88
+
89
+
:::info
90
+
When loading multiple AppSec configs, _hooks_ and _appsec rules_ are appended, and for conflicting options (e.g., `default_remediation`), the last one takes precedence.
91
+
:::
92
+
93
+
### Configuration Processing Order
94
+
95
+
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).
96
+
97
+
### Multi-Config Rule Evaluation
98
+
99
+
1. All `inband_rules` from all configurations are combined and evaluated together
100
+
2. All `outofband_rules` from all configurations are combined and evaluated together
101
+
3. Hooks from all configurations are executed in the order the configurations are listed
102
+
4. For conflicting configuration options (like `default_remediation`), the last configuration's value takes precedence
103
+
104
+
## AppSec Configuration Reference
105
+
106
+
Each AppSec configuration file defines how rules are loaded and processed.
107
+
You can create custom configuration files in the following folder: `/etc/crowdsec/appsec-configs/`
108
+
109
+
Here's the complete reference of available directives:
110
+
111
+
### Core Configuration Directives
112
+
113
+
#### `name` (required)
114
+
Unique identifier for the AppSec configuration, used for logging and referencing.
115
+
116
+
```yaml
117
+
name: custom/my-appsec-config
118
+
```
119
+
120
+
#### `inband_rules` (optional)
121
+
List of rule patterns to load as in-band rules. See [in-band rule processing](/appsec/intro.md#inband-rule-processing) for details.
122
+
123
+
```yaml
124
+
inband_rules:
125
+
- crowdsecurity/base-config
126
+
- crowdsecurity/vpatch-*
127
+
- custom/critical-patches
128
+
```
129
+
130
+
#### `outofband_rules` (optional)
131
+
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.
234
+
235
+
```yaml
236
+
post_eval:
237
+
- filter: IsInBand
238
+
apply:
239
+
- DumpRequest().WithBody().ToJSON()
59
240
```
60
241
61
-
## Disabling rules at runtime
242
+
#### `on_match`
243
+
Executed when rules match. Used to modify remediation or generate custom alerts.
244
+
245
+
```yaml
246
+
on_match:
247
+
- filter: req.URL.Host == "staging.example.com"
248
+
apply:
249
+
- SetRemediation("allow")
250
+
- CancelAlert()
251
+
```
252
+
253
+
For complete hook documentation, see [AppSec Hooks](/appsec/hooks.md).
254
+
255
+
## Rule Management
62
256
63
-
Even though we try to provide rules without false positives, sometimes a virtual patching rule can block legitimate requests on a website.
257
+
### Disabling Rules at Runtime
64
258
65
259
You can disable rules at runtime, either globally (for all requests) or based on specific conditions (source IP, URI, ...).
66
260
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
261
+
You can disable rules by:
262
+
- Name with `RemoveInBandRuleByName`: For CrowdSec rules (name as seen in `cscli appsec-rules list`)
263
+
- ID with `RemoveInBandRuleByID`: For seclang/ModSecurity rules by numeric ID
264
+
- Tag with `RemoveInBandRuleByTag`: For seclang/ModSecurity rules by tag
71
265
72
-
The same functions exist for out-of-band rules, prefixed with `RemovedOutBandRuleBy...`
266
+
The same functions exist for out-of-band rules, prefixed with `RemoveOutBandRuleBy...`
73
267
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).
268
+
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.
281
+
This example uses [hooks](/docs/appsec/hooks.md) to modify the configuration in 2 places:
282
+
- `on_load`: Expressions here will be applied when CrowdSec loads the configuration, effectively disabling the rule `crowdsecurity/vpatch-env-access` globally.
89
283
- `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
284
91
285
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
286
93
287
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
288
95
-
Finally, we need to tell crowdsec to load our new config:
289
+
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):
323
+
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):
With this config, the rules will still be evaluated, but if a rule matches no alert or event will be generated, and the remediation will be set to `allow`(ie, instruct the bouncer to let the request through).
142
336
143
-
## Appsec configuration
337
+
## Appendix: Appsec configuration properties
144
338
145
339
The AppSec configuration is referenced by the acquisition configuration (`appsec_config`, `appsec_configs` or `appsec_config_path`):
146
340
@@ -172,10 +366,18 @@ An optional list of rules to be loaded in in-band phase. In band rules are block
172
366
173
367
An optional remediation for in-band rules, defaults to `ban`. If set to `allow`, remediation component won't block the request (even if it matched rules). Any other value (including `captcha`) is passed as-is back to the remediation component.
174
368
369
+
:::info
370
+
When using multiple AppSec configs the last declared one takes precedence for this property
371
+
:::
372
+
175
373
### `default_pass_action`
176
374
177
375
An optional remediation for requests that didn't match any rules (or rules with a pass action). Defaults to `allow`. Any other value will be passed as-is to the remediation component.
178
376
377
+
:::info
378
+
When using multiple AppSec configs the last declared one takes precedence for this property
379
+
:::
380
+
179
381
### `blocked_http_code`
180
382
181
383
The HTTP code to return to the remediation component when a request should be blocked. Defaults to `403`
0 commit comments