diff --git a/crowdsec-docs/docs/appsec/advanced_deployments.mdx b/crowdsec-docs/docs/appsec/advanced_deployments.mdx index ba30b40f6..3090c0054 100644 --- a/crowdsec-docs/docs/appsec/advanced_deployments.mdx +++ b/crowdsec-docs/docs/appsec/advanced_deployments.mdx @@ -1,10 +1,10 @@ --- id: advanced_deployments -title: Advanced WAF Deployments +title: WAF Deployment Strategies sidebar_position: 6 --- -# Advanced WAF Deployments +# WAF Deployment Strategies 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. @@ -259,7 +259,7 @@ In-band CRS blocking provides maximum protection but requires: Once you've implemented advanced deployments: -- Configure [Custom Rules](/appsec/create_rules.md) for application-specific protection -- Set up [Hooks](/appsec/hooks.md) for custom response actions -- Explore [Configuration Options](/appsec/configuration.md) for fine-tuning -- Review [Troubleshooting Guide](/appsec/troubleshooting.md) for operational issues +- Configure [Custom Rules](create_rules.md) for application-specific protection +- Set up [Hooks](hooks.md) for custom response actions +- Explore [Configuration Options](configuration.md) for fine-tuning +- Review [Troubleshooting Guide](troubleshooting.md) for operational issues diff --git a/crowdsec-docs/docs/appsec/configuration.md b/crowdsec-docs/docs/appsec/configuration.md index 1f4c45f89..d26837fd3 100644 --- a/crowdsec-docs/docs/appsec/configuration.md +++ b/crowdsec-docs/docs/appsec/configuration.md @@ -1,217 +1,203 @@ --- id: configuration -title: Configuration Files -sidebar_position: 6 +title: Syntax +sidebar_position: 1 --- -## Overview +## AppSec Configuration Files -This page explains how AppSec configuration files work together and how the request processing pipeline behaves. +AppSec configuration files define which rules are loaded, how they run, and how the WAF responds. -**Prerequisites**: -- Familiarity with [AppSec concepts](/appsec/intro.md) -- Basic AppSec setup completed (see Getting Started guides) +They are loaded by the AppSec acquisition datasource via `appsec_configs` (see the [AppSec datasource](/log_processor/data_sources/appsec.md)). -The AppSec Component configuration consists of three main parts: +Below is a minimal example followed by the full key reference. -- **[Acquisition configuration](/log_processor/data_sources/appsec.md)**: Defines which port the AppSec Component listens on and which AppSec configuration files to load -- **AppSec configurations**: Define which rules are loaded and how they behave, along with [hooks](/appsec/hooks.md) for runtime customization - - **[AppSec rules](/appsec/rules_syntax.md)**: The actual detection signatures that identify and block malicious requests +```yaml +name: custom/my-appsec-config +inband_rules: + - crowdsecurity/base-config +default_remediation: ban +``` -## AppSec Acquisition +Each AppSec configuration file controls how rules are loaded and processed. +You can create custom configuration files in `/etc/crowdsec/appsec-configs/`. -The acquisition file is used to: -- Specify the **address** and **port** where AppSec-enabled remediation components forward requests. -- Specify one or more [AppSec configuration files](#appsec-configuration-files) that define which rules to apply and how. +## Configuration File Format -Details can be found in the [AppSec Datasource page](/log_processor/data_sources/appsec.md). +Configuration files share a common structure: -### Defining Multiple AppSec Configurations +- a [`name`](#name) (required) +- optional rule lists such as [`inband_rules`](#inband_rules) and [`outofband_rules`](#outofband_rules) +- optional behavior keys like [`default_remediation`](#default_remediation) and [`default_pass_action`](#default_pass_action) +- HTTP response codes (for example, [`blocked_http_code`](#blocked_http_code)) +- optional performance settings ([`inband_options`](#inband_options), [`outofband_options`](#outofband_options)) +- optional hooks ([`on_load`](#on_load), [`pre_eval`](#pre_eval), [`post_eval`](#post_eval), [`on_match`](#on_match)) +- optional logging ([`log_level`](#log_level)) -Often you will want multiple AppSec configurations to define groups of rules that are handled the same way. +```yaml +name: custom/my-appsec-config +inband_rules: + - crowdsecurity/base-config +outofband_rules: + - crowdsecurity/crs +default_remediation: ban +default_pass_action: allow +blocked_http_code: 403 +passed_http_code: 200 +log_level: info +``` -Use the `appsec_configs` *(with an S)* parameter to load multiple configurations that work together. +## Configuration Structure -In the following example we have two configurations: -- One with [CrowdSec default AppSec rules ↗️](https://app.crowdsec.net/hub/author/crowdsecurity/appsec-configurations/appsec-default) running in in-band mode -- The other for the [CRS rules ↗️](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-crs) that run in out-of-band mode by default. +### name -```yaml title="/etc/crowdsec/acquis.d/appsec.yaml" -appsec_configs: - - crowdsecurity/appsec-default # In-band virtual patching - - crowdsecurity/crs # Out-of-band detection based on ModSec CRS - from crowdsecurity/appsec-crs collection -labels: - type: appsec -listen_addr: 127.0.0.1:7422 -source: appsec -``` +> string -:::info -CrowdSec AppSec collections are available on [CrowdSec Hub ↗️](https://app.crowdsec.net/hub/collections?filters=search%3Dappsec) and kept up to date. +Unique identifier for the AppSec configuration, used for logging and referencing. -For example the CRS collection: `sudo cscli collections install crowdsecurity/appsec-crs`. -This collection installs OWASP CRS in out-of-band and adds a scenario to ban IPs triggering multiple rules. -::: +```yaml +name: custom/my-appsec-config +``` -### Using Custom Configurations +### inband_rules -If you want to alter default configuration files, create a new configuration file instead of modifying hub configurations. -Modifying hub configurations will make them *tainted* and prevent automatic updates. +> array of strings -For example, if you want to change the default vpatch rules config, create your own and use it instead in the acquisition file. +List of rule patterns to load as in-band rules. See [in-band rule processing](intro.md#in-band-rule-processing). -```yaml title="/etc/crowdsec/acquis.d/appsec.yaml" -appsec_configs: - - crowdsecurity/appsec-default - - custom/my_vpatch_rules -labels: - type: appsec -listen_addr: 127.0.0.1:7422 -source: appsec +```yaml +inband_rules: + - crowdsecurity/base-config + - crowdsecurity/vpatch-* ``` -A custom configuration file could look like this: +### outofband_rules -```yaml title="/etc/crowdsec/appsec-configs/my_vpatch_rules.yaml" -name: custom/my_vpatch_rules -default_remediation: ban -inband_rules: - - custom/custom-vpatch-* -# Add custom hooks as needed +> array of strings + +List of rule patterns to load as out-of-band rules. See [out-of-band rule processing](intro.md#out-of-band-rule-processing). + +```yaml +outofband_rules: + - crowdsecurity/crs + - custom/detection-rules ``` -## AppSec Configuration Files +### default_remediation + +> string -AppSec configuration files declare **which rules to load** in **in-band** *(blocking)* and/or **out-of-band** *(non-blocking)* mode, 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`. +Default action for in-band rules that match. The special value `allow` disables blocking. -For details, jump to the [Configuration properties list](#appendix-appsec-configuration-properties) +Common values include `ban` (block) and `captcha` (challenge), depending on what your remediation component supports. :::info -When loading multiple AppSec configs, _hooks_ and _appsec rules_ are appended, and for conflicting options (e.g., `default_remediation`), the last one takes precedence. +When using multiple AppSec configs, the last declared one takes precedence for this property. ::: -### Configuration Processing Order +```yaml +default_remediation: ban +``` -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). +### default_pass_action -### Multi-Config Rule Evaluation +> string -1. All `inband_rules` from all configurations are combined and evaluated together -2. All `outofband_rules` from all configurations are combined and evaluated together -3. Hooks from all configurations are executed in the order the configurations are listed -4. For conflicting configuration options (like `default_remediation`), the last configuration's value takes precedence +Action for requests that do not match any rules, or match rules with pass actions. -## AppSec Configuration Reference +:::info +When using multiple AppSec configs, the last declared one takes precedence for this property. +::: -Each AppSec configuration file defines how rules are loaded and processed. -You can create custom configuration files in the following folder: `/etc/crowdsec/appsec-configs/` +```yaml +default_pass_action: allow +``` -Here's the complete reference of available directives: +### blocked_http_code -### Core Configuration Directives +> integer -#### `name` (required) -Unique identifier for the AppSec configuration, used for logging and referencing. +HTTP status code returned to the remediation component when a request is blocked. ```yaml -name: custom/my-appsec-config +blocked_http_code: 403 ``` -#### `inband_rules` (optional) -List of rule patterns to load as in-band rules. See [in-band rule processing](/appsec/intro.md#inband-rule-processing) for details. +### passed_http_code -```yaml -inband_rules: - - crowdsecurity/base-config - - crowdsecurity/vpatch-* - - custom/critical-patches -``` +> integer -#### `outofband_rules` (optional) -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. +HTTP status code returned to the remediation component when a request is allowed. ```yaml -outofband_rules: - - crowdsecurity/crs - - custom/detection-rules +passed_http_code: 200 ``` -### Remediation Configuration +### user_blocked_http_code + +> integer -#### `default_remediation` (optional, default: "ban") -Default action for in-band rules that match. Special value `allow` prevents blocking. +HTTP status code returned to the end user when a request is blocked. ```yaml -default_remediation: ban # or "allow", "captcha", etc. +user_blocked_http_code: 403 ``` -:::info -When using multiple AppSec configs, the last declared one takes precedence for this property. -::: +### user_passed_http_code + +> integer -#### `default_pass_action` (optional, default: "allow") -Action for requests that don't match any rules or match rules with pass action. +HTTP status code returned to the end user when a request is allowed. ```yaml -default_pass_action: allow # or any custom value +user_passed_http_code: 200 ``` -:::info -When using multiple AppSec configs, the last declared one takes precedence for this property. -::: - -### HTTP Response Codes +### inband_options -#### `blocked_http_code` (optional, default: 403) -HTTP status code returned to the remediation component for blocked requests. +> object -#### `passed_http_code` (optional, default: 200) -HTTP status code returned to the remediation component for allowed requests. +Performance tuning options for in-band rule processing. -#### `user_blocked_http_code` (optional, default: 403) -HTTP status code returned to the end user for blocked requests. - -#### `user_passed_http_code` (optional, default: 200) -HTTP status code returned to the end user for allowed requests. +- `disable_body_inspection` (bool): Skip HTTP body inspection. +- `request_body_in_memory_limit` (integer): Max body size in memory (bytes, default: 1048576). ```yaml -blocked_http_code: 403 -passed_http_code: 200 -user_blocked_http_code: 403 -user_passed_http_code: 200 +inband_options: + disable_body_inspection: false + request_body_in_memory_limit: 1048576 ``` -### Performance and Processing Options +### outofband_options + +> object + +Performance tuning options for out-of-band rule processing. -#### `inband_options` and `outofband_options` -Performance tuning options for rule processing: +- `disable_body_inspection` (bool): Skip HTTP body inspection. +- `request_body_in_memory_limit` (integer): Max body size in memory (bytes, default: 1048576). ```yaml -inband_options: - disable_body_inspection: false # Skip HTTP body inspection - request_body_in_memory_limit: 1048576 # Max body size in memory (bytes) - outofband_options: disable_body_inspection: false request_body_in_memory_limit: 1048576 ``` -**`disable_body_inspection`**: Set to `true` to skip HTTP body analysis for performance. -**`request_body_in_memory_limit`**: Maximum request body size to load into memory (default: 1MB). Larger bodies are processed differently. +### log_level + +> string -#### `log_level` (optional) Logging verbosity for this configuration. Available levels: `debug`, `info`, `warn`, `error`. ```yaml -log_level: info # Use "debug" for troubleshooting +log_level: info ``` -### Hook Configuration +### on_load -AppSec configurations support four types of hooks for custom behavior: +> array -#### `on_load` -Executed when the configuration is loaded. Typically used for global rule modifications. +Executed when the configuration is loaded. Typically used for global rule changes. ```yaml on_load: @@ -219,7 +205,10 @@ on_load: - RemoveInBandRuleByName("problematic-rule") ``` -#### `pre_eval` +### pre_eval + +> array + Executed before rule evaluation for each request. Supports conditional logic. ```yaml @@ -229,7 +218,10 @@ pre_eval: - RemoveInBandRuleByName("strict-rule") ``` -#### `post_eval` +### post_eval + +> array + Executed after rule evaluation. Useful for debugging and analysis. ```yaml @@ -239,8 +231,11 @@ post_eval: - DumpRequest().WithBody().ToJSON() ``` -#### `on_match` -Executed when rules match. Used to modify remediation or generate custom alerts. +### on_match + +> array + +Executed when rules match. Used to adjust remediation or generate custom alerts. ```yaml on_match: @@ -250,168 +245,4 @@ on_match: - CancelAlert() ``` -For complete hook documentation, see [AppSec Hooks](/appsec/hooks.md). - -## Rule Management - -### Disabling Rules at Runtime - -You can disable rules at runtime, either globally (for all requests) or based on specific conditions (source IP, URI, ...). - -You can disable rules by: - - Name with `RemoveInBandRuleByName`: For CrowdSec rules (name as seen in `cscli appsec-rules list`) - - ID with `RemoveInBandRuleByID`: For seclang/ModSecurity rules by numeric ID - - Tag with `RemoveInBandRuleByTag`: For seclang/ModSecurity rules by tag - -The same functions exist for out-of-band rules, prefixed with `RemoveOutBandRuleBy...` - -To disable a rule, create a new AppSec config to avoid tainting the configuration from the hub (or update your existing custom configuration). - -```yaml title="/etc/crowdsec/appsec-configs/my_config.yaml" -name: custom/my_config -on_load: - - apply: - - RemoveInBandRuleByName("crowdsecurity/vpatch-env-access") -pre_eval: - - filter: IsInBand == true && req.URL.Path startsWith "/bar/" - apply: - - RemoveInBandRuleByName("crowdsecurity/generic-wordpress-uploads-php") -``` - -This example uses [hooks](/docs/appsec/hooks.md) to modify the configuration in 2 places: - - `on_load`: Expressions here will be applied when CrowdSec loads the configuration, effectively disabling the rule `crowdsecurity/vpatch-env-access` globally. - - `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. - -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. - -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. - -Finally, add your new config to the acquisition configuration: - -```yaml title="/etc/crowdsec/acquis.d/appsec.yaml" -appsec_configs: - - crowdsecurity/appsec-default - - custom/my_config -labels: - type: appsec -listen_addr: 127.0.0.1:7422 -source: appsec -``` - -## Allowlisting - -### Fully allow a specific IP or range - -If you want to ignore all rule matches for a specific IP or range, you can use a [centralized allowlist](local_api/allowlists.md). - -Rules will be processed as usual, but the request will not be blocked even if a rule matches. - -### Disable specific rules for a specific IP/range - -If you want to disable rule(s) for a specific IP (or range), you will need to use the `pre_eval` hook (refer to the section above for more details): - -```yaml title="/etc/crowdsec/appsec-configs/my_config.yaml" -name: custom/my_config -pre_eval: - - filter: req.RemoteAddr == "1.2.3.4" - apply: - - RemoveInBandRuleByName("crowdsecurity/generic-wordpress-uploads-php") -``` - -### Disable appsec for a specific FQDN - -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): - -```yaml title="/etc/crowdsec/appsec-configs/my_config.yaml" -name: custom/my_config -on_match: - - filter: req.Host == "foo.com" - apply: - - CancelEvent() - - CancelAlert() - - SetRemediation("allow") -``` - -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). - -## Appendix: Appsec configuration properties - -The AppSec configuration is referenced by the acquisition configuration (`appsec_config`, `appsec_configs` or `appsec_config_path`): - -> An example AppSec configuration -```yaml -name: crowdsecurity/virtual-patching -default_remediation: ban -#log_level: debug -inband_rules: - - crowdsecurity/base-config - - crowdsecurity/vpatch-* -# inband_options: -# disable_body_inspection: true -``` - -### `name` - -(required) the `name` of the AppSec configuration, used for both logging purposes and to reference the configuration from acquisition configuration. - -### `outofband_rules` - -A supplementary list of rules can be loaded during the out-of-band phase. These out-of-band rules are non-blocking and are assessed only after the AppSec Component has responded to the remediation component. This approach is beneficial for rules that may be costly to execute, have a higher likelihood of generating false positives, or are applicable in specific scenarios. - -### `inband_rules` - -An optional list of rules to be loaded in in-band phase. In band rules are blocking and evaluated before answering the remediation component. Useful for virtual patching, rules with no/low false positives. - -### `default_remediation` - -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. - -:::info -When using multiple AppSec configs the last declared one takes precedence for this property -::: - -### `default_pass_action` - -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. - -:::info -When using multiple AppSec configs the last declared one takes precedence for this property -::: - -### `blocked_http_code` - -The HTTP code to return to the remediation component when a request should be blocked. Defaults to `403` - -### `passed_http_code` - -The HTTP code to return to the remediation component when a request should not be blocked. Defaults to `200` - -### `user_blocked_http_code` - -The HTTP code to return to the final client when a request should be blocked. Defaults to `403` - -### `user_passed_http_code` - -The HTTP code to return to the final client when a request should not be blocked. Defaults to `200` - -### `on_load` - -See the [dedicated doc](/docs/appsec/hooks.md#on_load) - -### `pre_eval` - -See the [dedicated doc](/docs/appsec/hooks.md#pre_eval) - -### `post_eval` - -See the [dedicated doc](/docs/appsec/hooks.md#post_eval) - -### `on_match` - -See the [dedicated doc](/docs/appsec/hooks.md#on_match) - -### `inband_options` and `outofband_options` - -Subset of options that can be applied to the in-band/out-of-band rules: - - `disable_body_inspection` : boolean, allows to disable HTTP body inspection - - `request_body_in_memory_limit` : a number of byes indicating the maximum body size to be loaded in memory +For complete hook documentation, see [AppSec Hooks](hooks.md). diff --git a/crowdsec-docs/docs/appsec/configuration_creation_testing.md b/crowdsec-docs/docs/appsec/configuration_creation_testing.md new file mode 100644 index 000000000..a3566e242 --- /dev/null +++ b/crowdsec-docs/docs/appsec/configuration_creation_testing.md @@ -0,0 +1,98 @@ +--- +id: configuration_creation_testing +title: Creation & Testing +sidebar_position: 3 +--- + +## AppSec Acquisition + +The acquisition file is used to: +- Specify the **address** and **port** where AppSec-enabled remediation components forward requests. +- Specify one or more AppSec configuration files that define which rules to apply and how. + +Details can be found in the [AppSec Datasource page](/log_processor/data_sources/appsec.md). + +### Defining Multiple AppSec Configurations + +Often you will want multiple AppSec configurations to define groups of rules that are handled the same way. + +Use the `appsec_configs` parameter to load multiple configurations that work together. + +In the following example we have two configurations: +- One with [CrowdSec default AppSec rules ↗️](https://app.crowdsec.net/hub/author/crowdsecurity/appsec-configurations/appsec-default) running in in-band mode +- The other for the [CRS rules ↗️](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-crs) that run in out-of-band mode by default + +```yaml title="/etc/crowdsec/acquis.d/appsec.yaml" +appsec_configs: + - crowdsecurity/appsec-default # In-band virtual patching + - crowdsecurity/crs # Out-of-band detection based on ModSec CRS - from crowdsecurity/appsec-crs collection +labels: + type: appsec +listen_addr: 127.0.0.1:7422 +source: appsec +``` + +:::info +CrowdSec AppSec collections are available on [CrowdSec Hub ↗️](https://app.crowdsec.net/hub/collections?filters=search%3Dappsec) and kept up to date. + +For example the CRS collection: `sudo cscli collections install crowdsecurity/appsec-crs`. +This collection installs OWASP CRS in out-of-band and adds a scenario to ban IPs triggering multiple rules. +::: + +### Using Custom Configurations + +If you want to alter default configuration files, create a new configuration file instead of modifying hub configurations. +Modifying hub configurations will make them *tainted* and prevent automatic updates. + +For example, if you want to change the default vpatch rules config, create your own and use it instead in the acquisition file. + +```yaml title="/etc/crowdsec/acquis.d/appsec.yaml" +appsec_configs: + - crowdsecurity/appsec-default + - custom/my_vpatch_rules +labels: + type: appsec +listen_addr: 127.0.0.1:7422 +source: appsec +``` + +A custom configuration file could look like this: + +```yaml title="/etc/crowdsec/appsec-configs/my_vpatch_rules.yaml" +name: custom/my_vpatch_rules +default_remediation: ban +inband_rules: + - custom/custom-vpatch-* +# Add custom hooks as needed +``` + +## AppSec Configuration Files + +AppSec configuration files declare **which rules to load** in **in-band** *(blocking)* and/or **out-of-band** *(non-blocking)* mode, define how matches are handled (for example, default remediation), and let you tweak processing via hooks like `on_load`, `pre_eval`, `post_eval`, and `on_match`. + +For the full list of keys, see [Configuration Syntax](configuration). + +:::info +When loading multiple AppSec configs, _hooks_ and _appsec rules_ are appended, and for conflicting options (for example, `default_remediation`), the last one takes precedence. +::: + +### Configuration Processing Order + +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](intro.md#inband-rules-and-out-of-band-rules). + +### Multi-Config Rule Evaluation + +1. All `inband_rules` from all configurations are combined and evaluated together +2. All `outofband_rules` from all configurations are combined and evaluated together +3. Hooks from all configurations are executed in the order the configurations are listed +4. For conflicting configuration options (like `default_remediation`), the last configuration's value takes precedence + +## Testing Changes + +After updating AppSec configuration files: + +1. Reload CrowdSec so it picks up the new configuration. +2. Validate behavior with your usual test traffic, or use the [generic AppSec test rule](https://app.crowdsec.net/hub/author/crowdsecurity/appsec-rules/appsec-generic-test). +3. Inspect results in logs or via `cscli metrics show appsec`. + +For more troubleshooting guidance, see [AppSec Troubleshooting](troubleshooting.md). diff --git a/crowdsec-docs/docs/appsec/configuration_rule_management.md b/crowdsec-docs/docs/appsec/configuration_rule_management.md new file mode 100644 index 000000000..08b9ca77e --- /dev/null +++ b/crowdsec-docs/docs/appsec/configuration_rule_management.md @@ -0,0 +1,85 @@ +--- +id: configuration_rule_management +title: Allowlisting and Rule Overrides +sidebar_position: 3 +--- + +## Disabling Rules at Runtime + +You can disable rules at runtime, either globally (for all requests) or based on specific conditions (source IP, URI, ...). + +You can disable rules by: + - Name with `RemoveInBandRuleByName`: For CrowdSec rules (name as seen in `cscli appsec-rules list`) + - ID with `RemoveInBandRuleByID`: For seclang/ModSecurity rules by numeric ID + - Tag with `RemoveInBandRuleByTag`: For seclang/ModSecurity rules by tag + +The same functions exist for out-of-band rules, prefixed with `RemoveOutBandRuleBy...` + +To disable a rule, create a new AppSec config to avoid tainting the configuration from the hub (or update your existing custom configuration). + +```yaml title="/etc/crowdsec/appsec-configs/my_config.yaml" +name: custom/my_config +on_load: + - apply: + - RemoveInBandRuleByName("crowdsecurity/vpatch-env-access") +pre_eval: + - filter: IsInBand == true && req.URL.Path startsWith "/bar/" + apply: + - RemoveInBandRuleByName("crowdsecurity/generic-wordpress-uploads-php") +``` + +This example uses [hooks](hooks.md) to modify the configuration in 2 places: + - `on_load`: Expressions here will be applied when CrowdSec loads the configuration, effectively disabling the rule `crowdsecurity/vpatch-env-access` globally. + - `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. + +You can also disable native (seclang) rules by providing their ID with the `RemoveInBandRuleByID` helper. See the [hooks](hooks.md) documentation for a list of available helpers. + +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. + +Finally, add your new config to the acquisition configuration: + +```yaml title="/etc/crowdsec/acquis.d/appsec.yaml" +appsec_configs: + - crowdsecurity/appsec-default + - custom/my_config +labels: + type: appsec +listen_addr: 127.0.0.1:7422 +source: appsec +``` + +## Allowlisting + +### Fully allow a specific IP or range + +If you want to ignore all rule matches for a specific IP or range, you can use a [centralized allowlist](/local_api/allowlists.md). + +Rules will be processed as usual, but the request will not be blocked even if a rule matches. + +### Disable specific rules for a specific IP/range + +If you want to disable rule(s) for a specific IP (or range), you will need to use the `pre_eval` hook (refer to the section above for more details): + +```yaml title="/etc/crowdsec/appsec-configs/my_config.yaml" +name: custom/my_config +pre_eval: + - filter: req.RemoteAddr == "1.2.3.4" + apply: + - RemoveInBandRuleByName("crowdsecurity/generic-wordpress-uploads-php") +``` + +### Disable appsec for a specific FQDN + +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): + +```yaml title="/etc/crowdsec/appsec-configs/my_config.yaml" +name: custom/my_config +on_match: + - filter: req.Host == "foo.com" + apply: + - CancelEvent() + - CancelAlert() + - SetRemediation("allow") +``` + +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` (i.e., instruct the bouncer to let the request through). diff --git a/crowdsec-docs/docs/appsec/create_rules.md b/crowdsec-docs/docs/appsec/create_rules.md index 8848f2ad6..7ca56440f 100644 --- a/crowdsec-docs/docs/appsec/create_rules.md +++ b/crowdsec-docs/docs/appsec/create_rules.md @@ -170,12 +170,12 @@ Let's get over the relevant parts: - `description` is how your scenario will appear in [the hub](https://hub.crowdsec.net) - `labels` section is used both in [the hub](https://hub.crowdsec.net) and [the console](https://app.crowdsec.net). [It must follow rules described here](/log_processor/scenarios/format.md#labels) - `rules` describe what we want to match: - - a [`METHOD`](/appsec/rules_syntax.md#target) [equal to `POST`](/appsec/rules_syntax.md#match) - - the presence of a header ([`HEADERS_NAME`](/appsec/rules_syntax.md#target)) with a name that once transformed to `lowercase`, is `x-foobar-bypass` + - a [`METHOD`](rules_syntax.md#zones) [equal to `POST`](rules_syntax.md#match) + - the presence of a header ([`HEADERS_NAME`](rules_syntax.md#zones)) with a name that once transformed to `lowercase`, is `x-foobar-bypass` - a post parameter (`BODY_ARGS`), `user_id` that contains something else than a-z A-Z or 0-9 or `_` :::info -You can [find detailed rules syntax here](/appsec/rules_syntax.md). +You can [find detailed rules syntax here](rules_syntax.md). ::: ## Testing diff --git a/crowdsec-docs/docs/appsec/intro.md b/crowdsec-docs/docs/appsec/intro.md index e68d9a16b..b2a4a573f 100644 --- a/crowdsec-docs/docs/appsec/intro.md +++ b/crowdsec-docs/docs/appsec/intro.md @@ -41,6 +41,12 @@ The component uses existing remediation hooks in web servers and reverse proxies 3. The engine evaluates the request against AppSec rules (in-band rules can block immediately). 4. Based on the result, the web server either blocks the request or processes it as usual. +:::tip Common gotchas +- Installing rules is not enough: you must also enable the AppSec acquisition datasource and restart CrowdSec. +- The remediation component must support AppSec forwarding, and must be configured to forward to the same `listen_addr` you set in the acquisition file. +- In-band rules return an action for the current request (for example `ban`/`captcha`); longer-term bans are driven by scenarios and decisions. +::: + ## Supported Web Servers & Reverse Proxies The AppSec Component works seamlessly with modern web servers and reverse proxies: @@ -127,8 +133,8 @@ You can follow our quick start guides depending on your web server: Or consider learning more about the AppSec capabilities: -- **Rules**: [How to read, write and debug rules](/appsec/rules_syntax.md) -- **Scenarios**: [How to create scenarios that leverage the AppSec Component events](/appsec/alerts_and_scenarios.md) -- **Hooks**: [To customise behavior of the AppSec at runtime](/appsec/hooks.md) -- **Troubleshoot**: [How to troubleshoot the behavior of the AppSec Component](/appsec/troubleshooting.md) -- **AppSec Technical Details**: [For developers integrating with the AppSec Component](/appsec/protocol.md) +- **Rules**: [How to read, write and debug rules](rules_syntax.md) +- **Scenarios**: [How to create scenarios that leverage the AppSec Component events](alerts_and_scenarios.md) +- **Hooks**: [To customise behavior of the AppSec at runtime](hooks.md) +- **Troubleshoot**: [How to troubleshoot the behavior of the AppSec Component](troubleshooting.md) +- **AppSec Technical Details**: [For developers integrating with the AppSec Component](protocol.md) diff --git a/crowdsec-docs/docs/appsec/quickstart/general.mdx b/crowdsec-docs/docs/appsec/quickstart/general.mdx index e54a07077..47ec255e4 100644 --- a/crowdsec-docs/docs/appsec/quickstart/general.mdx +++ b/crowdsec-docs/docs/appsec/quickstart/general.mdx @@ -24,7 +24,7 @@ This guide covers the core AppSec Component setup that applies to all web server AppSec setup has two steps: - Download rules and configuration collections. -- Configure AppSec as a new acquisition datasource. +- Configure AppSec as a new acquisition datasource ([AppSec datasource](/log_processor/data_sources/appsec.md)). The following sections will guide you through the default setup. @@ -41,12 +41,12 @@ sudo cscli collections install crowdsecurity/appsec-virtual-patching crowdsecuri These collections include: - **Virtual Patching Rules**: Protection against known vulnerabilities (CVEs) - **Generic Attack Detection**: Common web attack patterns -- **AppSec Configuration**: Default configuration linking rules together +- **AppSec Configuration**: Default [AppSec configuration file](/appsec/configuration.md) linking rules together - **CrowdSec Parsers & Scenarios**: For processing AppSec events and creating alerts ### Acquisition Configuration -Configure CrowdSec to expose the AppSec Component by creating an acquisition file. +Configure CrowdSec to expose the AppSec Component by creating an acquisition file ([AppSec datasource](/log_processor/data_sources/appsec.md)). 1. Create the acquisition directory (if it doesn't exist): ```bash @@ -56,18 +56,18 @@ Configure CrowdSec to expose the AppSec Component by creating an acquisition fil 2. Create the AppSec acquisition configuration: ```bash sudo cat > /etc/crowdsec/acquis.d/appsec.yaml << EOF - appsec_configs: - - crowdsecurity/appsec-default - labels: - type: appsec - listen_addr: 127.0.0.1:7422 - source: appsec - name: myAppSecComponent - EOF +appsec_configs: + - crowdsecurity/appsec-default +labels: + type: appsec +listen_addr: 127.0.0.1:7422 +source: appsec +name: myAppSecComponent +EOF ``` **Configuration explained:** -- `appsec_configs`: Uses the default configuration from the installed collections +- `appsec_configs`: Uses the [AppSec configuration(s)](/appsec/configuration.md) from the installed collections - `listen_addr`: IP and port where the AppSec Component listens (default: 127.0.0.1:7422) - `source`: Identifies this as an AppSec data source - `name`: A friendly name for your AppSec component @@ -138,13 +138,13 @@ INFO[...] Appsec Runner ready to process event Now that the AppSec Component is configured and running, you need to: 1. **Configure your remediation component** to forward requests to `http://127.0.0.1:7422` -2. **Test the setup** [by triggering a rule](/appsec/quickstart/general.mdx#testing-detection) +2. **Test the setup** [by triggering a rule](#testing-detection) 3. **Monitor alerts** with `sudo cscli alerts list` or in the [CrowdSec Console](https://app.crowdsec.net) For specific remediation component configuration, see: -- [Nginx/OpenResty Setup](/appsec/quickstart/nginxopenresty.mdx) -- [Traefik Setup](/appsec/quickstart/traefik.mdx) -- [WordPress Setup](/appsec/quickstart/wordpress.mdx) +- [Nginx/OpenResty Setup](nginxopenresty.mdx) +- [Traefik Setup](traefik.mdx) +- [WordPress Setup](wordpress.mdx) - [Check the hub for other remediation components supporting AppSec](https://app.crowdsec.net/hub/remediation-components) ### Testing Detection @@ -179,7 +179,7 @@ This scenario can only be triggered again after a 1-minute delay. ### Multiple AppSec Configurations -You can [load multiple AppSec configurations](/appsec/vpatch_and_crs) for different rule sets: +You can [load multiple AppSec configurations](/appsec/configuration_creation_testing.md#defining-multiple-appsec-configurations) for different rule sets: ```yaml # /etc/crowdsec/acquis.d/appsec.yaml diff --git a/crowdsec-docs/docs/appsec/quickstart/nginx-ingress.mdx b/crowdsec-docs/docs/appsec/quickstart/nginx-ingress.mdx index 9db7b9a17..b59efca91 100644 --- a/crowdsec-docs/docs/appsec/quickstart/nginx-ingress.mdx +++ b/crowdsec-docs/docs/appsec/quickstart/nginx-ingress.mdx @@ -26,7 +26,7 @@ will have: [Introduction](/appsec/intro.md#introduction) for a better understanding. 2. It's assumed that you have already installed **CrowdSec [Security -Engine](intro.mdx)**. For installation quickstart, refer to the [QuickStart +Engine](/intro.mdx)**. For installation quickstart, refer to the [QuickStart guide](/u/getting_started/installation/kubernetes). :::warning @@ -37,6 +37,10 @@ values below). Note that the standard upstream controller removed Lua support in version 1.12 and therefore is not suitable for use as a CrowdSec remediation component. ::: +:::tip Already have CrowdSec AppSec running? +If CrowdSec is already deployed with AppSec enabled in your cluster, skip to [Enable the CrowdSec Lua plugin on NGINX Ingress](#enable-the-crowdsec-lua-plugin-on-nginx-ingress). +::: + ## Deploy CrowdSec with AppSec enabled ### Helm repository @@ -46,7 +50,7 @@ Add or update the CrowdSec Helm repository: ```bash helm repo add crowdsec https://crowdsecurity.github.io/helm-charts helm repo update - ``` +``` :::note If CrowdSec is already deployed with Helm in this cluster, the repository entry is already present—you only need `helm repo update`. @@ -54,12 +58,13 @@ If CrowdSec is already deployed with Helm in this cluster, the repository entry ### Update CrowdSec configuration -Add this to the CrowdSec `values.yaml` with the AppSec configuration: +Add this to the CrowdSec `values.yaml` with the AppSec acquisition datasource (see the [AppSec datasource](/log_processor/data_sources/appsec.md)) and the default [AppSec configuration](/appsec/configuration.md): ```yaml title="values.yaml" -appsec +appsec: acquisitions: - - appsec_config: crowdsecurity/appsec-default + - appsec_configs: + - crowdsecurity/appsec-default labels: type: appsec listen_addr: 0.0.0.0:7422 @@ -73,6 +78,7 @@ appsec This YAML configuration snippet exposes the important configuration items: * `listen_addr: 0.0.0.0:7422` exposes the AppSec API inside the cluster. + * `appsec_configs` loads the [AppSec configuration(s)](/appsec/configuration.md) that define which rules are evaluated (in-band vs out-of-band). * The two collections provide virtual patching and generic rule coverage. * The chart bootstraps a bouncer named `nginx_ingress_waf` using the key you export locally. @@ -94,7 +100,7 @@ You should see `crowdsec-agent` pods, the `crowdsec-lapi` pod and the `crowdsec- To extend the ingress controller with the CrowdSec plugin and point it to the AppSec API, create the file named `ingress-values.yaml`. You can read the entire -file at `crowdsec-docs/crowdsec-docs/docs/appsec/quickstart/nginx-ingress.mdx`. +file in the snippet below. ```yaml title="ingress-values.yaml" controller: @@ -318,8 +324,8 @@ Appsec '127.0.0.1:7422/' Rules Metrics: You can test and investigate further with [Stack -Health-Check](/u/getting_started/health_check#trigger-crowdsecs-test-scenarios) and [Appsec Troubleshooting -guide](/docs/next/appsec/troubleshooting) +Health-Check](/u/getting_started/health_check#trigger-crowdsec-test-scenarios) and [Appsec Troubleshooting +guide](/appsec/troubleshooting.md) ## Integration with the Console diff --git a/crowdsec-docs/docs/appsec/quickstart/nginxopenresty.mdx b/crowdsec-docs/docs/appsec/quickstart/nginxopenresty.mdx index 0deba8135..daee3c12c 100644 --- a/crowdsec-docs/docs/appsec/quickstart/nginxopenresty.mdx +++ b/crowdsec-docs/docs/appsec/quickstart/nginxopenresty.mdx @@ -24,7 +24,7 @@ Additionally, we'll show how to monitor these alerts through the [Console](https 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. 2. It's assumed that you have already installed: - - **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](/log_processor/data_sources/appsec.md). + - **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](/log_processor/data_sources/appsec.md). - One of the supported web servers for this guide: - Nginx **[Remediation Component](/u/bouncers/intro)**: installation instructions are available in the [QuickStart guide](/u/bouncers/nginx). - OpenResty **[Remediation Component](/u/bouncers/intro)**: installation instructions are available in the [QuickStart guide](/u/bouncers/openresty). @@ -35,6 +35,10 @@ Additionally, we'll show how to monitor these alerts through the [Console](https The reason we provide Nginx and OpenResty in a single guide is that OpenResty is a web server based on Nginx just the configuration paths are different ::: +:::tip Already did the base setup? +If you already completed the [General Setup](general.mdx) (collections + acquisition), skip to [Remediation Component Setup](#remediation-component-setup). +::: + ## AppSec Component Setup ### Collection installation @@ -58,31 +62,34 @@ sudo cscli collections install crowdsecurity/appsec-virtual-patching crowdsecuri Executing this command will install the following items: -- The [*AppSec Rules*](/appsec/rules_syntax.md) contain the definition of malevolent requests to be matched and stopped +- The [*AppSec Rules*](/appsec/rules_syntax.md) contain the definition of malicious requests to be matched and stopped - The [*AppSec Configuration*](/appsec/configuration.md#appsec-configuration-files) links together a set of rules to provide a coherent set - The CrowdSec Parser and CrowdSec Scenario(s) bans for a longer duration repeating offenders ### Setup the Acquisition -Having installed the required components, it's time to configure the CrowdSec Acquisition to expose the Application Security Component to our web server. This configuration allows our Nginx/OpenResty server to send requests to the AppSec Component for evaluation and decision-making. +Having installed the required components, it's time to configure the CrowdSec acquisition datasource for the AppSec Component ([AppSec datasource](/log_processor/data_sources/appsec.md)). This configuration allows Nginx/OpenResty to forward requests to the AppSec Component for evaluation and decision-making. Steps: - 1. Create the `/etc/crowdsec/acquis.d/` directory (if it doesn't exist on your machine) - ``` - mkdir -p /etc/crowdsec/acquis.d/ - ``` - 2. Create a file `/etc/crowdsec/acquis.d/appsec.yaml` with the following content: - ```yaml title="/etc/crowdsec/acquis.d/appsec.yaml" - appsec_config: crowdsecurity/appsec-default - labels: - type: appsec - listen_addr: 127.0.0.1:7422 - source: appsec - ``` + +1. Create the acquisition directory (if it doesn't exist on your machine): + ```bash + sudo mkdir -p /etc/crowdsec/acquis.d/ + ``` + +2. Create `/etc/crowdsec/acquis.d/appsec.yaml`: + ```yaml title="/etc/crowdsec/acquis.d/appsec.yaml" + appsec_configs: + - crowdsecurity/appsec-default + labels: + type: appsec + listen_addr: 127.0.0.1:7422 + source: appsec + ``` The two important directives in this configuration file are: - - `appsec_config` is the name of the [*AppSec Configuration*](/appsec/configuration.md#appsec-configuration-files) that was included in the Collection we just installed. + - `appsec_configs` is the list of [*AppSec Configurations*](/appsec/configuration.md#appsec-configuration-files) that was included in the Collection we just installed. - the `listen_addr` is the IP and port the AppSec Component will listen to. :::warning diff --git a/crowdsec-docs/docs/appsec/quickstart/npmplus.mdx b/crowdsec-docs/docs/appsec/quickstart/npmplus.mdx index 7d257dcce..ebdc1f6fc 100644 --- a/crowdsec-docs/docs/appsec/quickstart/npmplus.mdx +++ b/crowdsec-docs/docs/appsec/quickstart/npmplus.mdx @@ -47,10 +47,16 @@ We also install the [`crowdsecurity/appsec-generic-rules`](https://app.crowdsec. You can always view the content of a [collection on the Hub](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-virtual-patching). ::: +:::note +In this guide, you'll install these collections inside the CrowdSec container after starting the stack. +::: + ### Setup the Acquisition NPMplus provides a Docker Compose file that includes both NPMplus and CrowdSec services. We need to configure the acquisition for AppSec and NPMplus log parsing. +The AppSec part of this file is the AppSec acquisition datasource (`source: appsec`). For the complete reference of available keys, see the [AppSec datasource](/log_processor/data_sources/appsec.md). + **Steps:** 1. Download the compose.yaml file: @@ -97,7 +103,8 @@ labels: type: modsecurity --- listen_addr: 0.0.0.0:7422 -appsec_config: crowdsecurity/appsec-default +appsec_configs: + - crowdsecurity/appsec-default name: appsec source: appsec labels: @@ -113,7 +120,7 @@ You can find the newest version of the `npmplus.yaml` acquisition file [here](ht - The first two sections configure log parsing for NPMplus logs - The third section configures the AppSec Component: - `listen_addr: 0.0.0.0:7422`: The AppSec Component listens on all interfaces on port 7422 (needed for Docker networking) - - `appsec_config`: Uses the default configuration from the installed collections + - `appsec_configs`: Uses the [AppSec configuration(s)](/appsec/configuration.md) from the installed collections - `source: appsec`: Identifies this as an AppSec data source ### Running NPMplus and CrowdSec @@ -239,7 +246,7 @@ Appsec '0.0.0.0:7422/' Rules Metrics: ╰─────────────────────────────────┴───────────╯ ``` -You can test and investigate further with [Stack Health-Check](/u/getting_started/health_check) and [Appsec Troubleshooting guide](/appsec/troubleshooting) +You can test and investigate further with [Stack Health-Check](/u/getting_started/health_check) and [Appsec Troubleshooting guide](/appsec/troubleshooting.md) diff --git a/crowdsec-docs/docs/appsec/quickstart/traefik.mdx b/crowdsec-docs/docs/appsec/quickstart/traefik.mdx index 2cc2f2719..d504e930e 100644 --- a/crowdsec-docs/docs/appsec/quickstart/traefik.mdx +++ b/crowdsec-docs/docs/appsec/quickstart/traefik.mdx @@ -29,7 +29,7 @@ Additionally, we'll show how to monitor these alerts through the [Introduction](/appsec/intro.md#introduction) for a better understanding. 2. It's assumed that you have already installed: - - **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. + - **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 enabled via the [AppSec acquisition datasource](/log_processor/data_sources/appsec.md). - Traefik Plugin **[Remediation Component](/u/bouncers/intro)**: Thanks to [maxlerebourg](https://github.com/maxlerebourg) and team, there is a [Traefik Plugin](https://plugins.traefik.io/plugins/6335346ca4caa9ddeffda116/crowdsec-bouncer-traefik-plugin) that blocks requests directly in Traefik. :::info @@ -48,6 +48,10 @@ Plugin](https://plugins.traefik.io/plugins/6335346ca4caa9ddeffda116/crowdsec-bou documentation. ::: +:::tip Already did the base setup? +If you already completed the [General Setup](general.mdx) (collections + acquisition), skip to [Remediation Component Setup](#remediation-component-setup). +::: + ## AppSec Component Setup ### Collection installation @@ -160,8 +164,7 @@ acquisition for the AppSec Component. ### Setup the Acquisition -You now need to set up the acquisition for AppSec. The steps depend on how you run CrowdSec. -depends on how you run CrowdSec. +You now need to set up the acquisition for AppSec. The steps depend on how you run CrowdSec. For the complete acquisition reference, see the [AppSec datasource](/log_processor/data_sources/appsec.md). diff --git a/crowdsec-docs/docs/appsec/quickstart/wordpress.mdx b/crowdsec-docs/docs/appsec/quickstart/wordpress.mdx index d4a7c66cd..545aee145 100644 --- a/crowdsec-docs/docs/appsec/quickstart/wordpress.mdx +++ b/crowdsec-docs/docs/appsec/quickstart/wordpress.mdx @@ -23,11 +23,14 @@ Additionally, we'll show how to monitor these alerts through the [Console](https 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. 2. It's assumed that you have already installed: - - **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](/log_processor/data_sources/appsec.md). + - **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](/log_processor/data_sources/appsec.md). - **WordPress [Remediation Component](/u/bouncers/intro)**: installation instructions are available in the [WordPress bouncer guide](/u/bouncers/wordpress). The CrowdSec WordPress plugin enables you to protect your WordPress site against malicious traffic using CrowdSec's advanced threat detection and blocklist capabilities. This component intercepts HTTP requests at the WordPress level and forwards them to the AppSec Component for analysis and action. +:::tip Already did the base setup? +If you already completed the [General Setup](general.mdx) (collections + acquisition), skip to [Remediation Component Setup](#remediation-component-setup). +::: ## AppSec Component Setup @@ -52,31 +55,34 @@ sudo cscli collections install crowdsecurity/appsec-virtual-patching crowdsecuri Executing this command will install the following items: -- The [*AppSec Rules*](/appsec/rules_syntax.md) contain the definition of malevolent requests to be matched and stopped +- The [*AppSec Rules*](/appsec/rules_syntax.md) contain the definition of malicious requests to be matched and stopped - The [*AppSec Configuration*](/appsec/configuration.md#appsec-configuration-files) links together a set of rules to provide a coherent set - The CrowdSec Parser and CrowdSec Scenario(s) bans for a longer duration repeating offenders ### Setup the Acquisition -Having installed the required components, it's time to configure the CrowdSec Acquisition to expose the Application Security Component to our WordPress site. This configuration allows our WordPress site to send requests to the AppSec Component for evaluation and decision-making. +Having installed the required components, it's time to configure the CrowdSec acquisition datasource for the AppSec Component ([AppSec datasource](/log_processor/data_sources/appsec.md)). This configuration allows WordPress to send requests to the AppSec Component for evaluation and decision-making. Steps: - 1. Create the `/etc/crowdsec/acquis.d/` directory (if it doesn't exist on your machine) - ```bash - mkdir -p /etc/crowdsec/acquis.d/ - ``` - 2. Create a file `/etc/crowdsec/acquis.d/appsec.yaml` with the following content: - ```yaml title="/etc/crowdsec/acquis.d/appsec.yaml" - appsec_config: crowdsecurity/appsec-default - labels: - type: appsec - listen_addr: 127.0.0.1:7422 - source: appsec - ``` + +1. Create the acquisition directory (if it doesn't exist on your machine): + ```bash + sudo mkdir -p /etc/crowdsec/acquis.d/ + ``` + +2. Create `/etc/crowdsec/acquis.d/appsec.yaml`: + ```yaml title="/etc/crowdsec/acquis.d/appsec.yaml" + appsec_configs: + - crowdsecurity/appsec-default + labels: + type: appsec + listen_addr: 127.0.0.1:7422 + source: appsec + ``` The two important directives in this configuration file are: - - `appsec_config` is the name of the [*AppSec Configuration*](/appsec/configuration.md#appsec-configuration-files) that was included in the Collection we just installed. + - `appsec_configs` is the list of [*AppSec Configurations*](/appsec/configuration.md#appsec-configuration-files) that was included in the Collection we just installed. - the `listen_addr` is the IP and port the AppSec Component will listen to. :::warning diff --git a/crowdsec-docs/docs/appsec/troubleshooting.md b/crowdsec-docs/docs/appsec/troubleshooting.md index bc467bab3..d18172abd 100644 --- a/crowdsec-docs/docs/appsec/troubleshooting.md +++ b/crowdsec-docs/docs/appsec/troubleshooting.md @@ -118,7 +118,8 @@ mkdir -p /etc/crowdsec/acquis.d/ cat > /etc/crowdsec/acquis.d/test_appsec.yaml <