Syntax

AppSec Configuration Files

AppSec configuration files define which rules are loaded, how they run, and how the WAF responds.

They are loaded by the AppSec acquisition datasource via appsec_configs (see the AppSec datasource).

Below is a minimal example followed by the full key reference.

name: custom/my-appsec-config
inband_rules:
  - crowdsecurity/base-config
default_remediation: ban

Each AppSec configuration file controls how rules are loaded and processed. You can create custom configuration files in /etc/crowdsec/appsec-configs/.

Configuration File Format

Configuration files share a common structure:

• a name (required)
• optional rule lists such as inband_rules and outofband_rules
• optional behavior keys like default_remediation and default_pass_action
• HTTP response codes (for example, blocked_http_code)
• optional performance settings (inband_options, outofband_options)
• optional hooks (on_load, pre_eval, post_eval, on_match)
• optional logging (log_level)

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

Configuration Structure

name

string

Unique identifier for the AppSec configuration, used for logging and referencing.

name: custom/my-appsec-config

inband_rules

array of strings

List of rule patterns to load as in-band rules. See in-band rule processing.

inband_rules:
  - crowdsecurity/base-config
  - crowdsecurity/vpatch-*

outofband_rules

array of strings

List of rule patterns to load as out-of-band rules. See out-of-band rule processing.

outofband_rules:
  - crowdsecurity/crs
  - custom/detection-rules

default_remediation

string

Default action for in-band rules that match. The special value allow disables blocking.

Common values include ban (block) and captcha (challenge), depending on what your remediation component supports.

When using multiple AppSec configs, the last declared one takes precedence for this property.

default_remediation: ban

default_pass_action

string

Action for requests that do not match any rules, or match rules with pass actions.

When using multiple AppSec configs, the last declared one takes precedence for this property.

default_pass_action: allow

blocked_http_code

integer

HTTP status code returned to the remediation component when a request is blocked.

blocked_http_code: 403

passed_http_code

integer

HTTP status code returned to the remediation component when a request is allowed.

passed_http_code: 200

user_blocked_http_code

integer

HTTP status code returned to the end user when a request is blocked.

user_blocked_http_code: 403

user_passed_http_code

integer

HTTP status code returned to the end user when a request is allowed.

user_passed_http_code: 200

inband_options

object

Performance tuning options for in-band rule processing.

• disable_body_inspection (bool): Skip HTTP body inspection.
• request_body_in_memory_limit (integer): Max body size in memory (bytes, default: 1048576).

inband_options:
  disable_body_inspection: false
  request_body_in_memory_limit: 1048576

outofband_options

object

Performance tuning options for out-of-band rule processing.

• disable_body_inspection (bool): Skip HTTP body inspection.
• request_body_in_memory_limit (integer): Max body size in memory (bytes, default: 1048576).

outofband_options:
  disable_body_inspection: false
  request_body_in_memory_limit: 1048576

log_level

string

Logging verbosity for this configuration. Available levels: debug, info, warn, error.

log_level: info

on_load

array

Executed when the configuration is loaded. Typically used for global rule changes.

on_load:
  - apply:
      - RemoveInBandRuleByName("problematic-rule")

pre_eval

array

Executed before rule evaluation for each request. Supports conditional logic.

pre_eval:
  - filter: IsInBand && req.RemoteAddr == "192.168.1.100"
    apply:
      - RemoveInBandRuleByName("strict-rule")

post_eval

array

Executed after rule evaluation. Useful for debugging and analysis.

post_eval:
  - filter: IsInBand
    apply:
      - DumpRequest().WithBody().ToJSON()

on_match

array

Executed when rules match. Used to adjust remediation or generate custom alerts.

on_match:
  - filter: req.Host == "staging.example.com"
    apply:
      - SetRemediation("allow")
      - CancelAlert()

For complete hook documentation, see AppSec Hooks.