AppSec Configuration 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.

YAML

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, scoped per phase (inband, outofband), plus on_load
• legacy top-level hooks (pre_eval, post_eval, on_match)
• optional logging (log_level)

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

Configuration Structure

name

string

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

YAML

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.

YAML

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.

YAML

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.

info

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

YAML

default_remediation: ban

default_pass_action

string

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

info

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

YAML

default_pass_action: allow

blocked_http_code

integer

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

YAML

blocked_http_code: 403

passed_http_code

integer

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

YAML

passed_http_code: 200

user_blocked_http_code

integer

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

YAML

user_blocked_http_code: 403

user_passed_http_code

integer

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

YAML

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).

YAML

inband_options:
  disable_body_inspection: false
  request_body_in_memory_limit: 1048576

note

request_body_in_memory_limit is a Coraza-level setting. It is distinct from the engine's overall maximum body size, which bounds how much of the body CrowdSec buffers before any rule runs (defaults to 10MB). See Request body size handling to tune it.

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).

YAML

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.

YAML

log_level: info

inband

object

Rules, hooks and options scoped to the in-band pass. Accepted keys:

• rules (array of strings): same as inband_rules; both lists are merged.
• pre_eval, post_eval, on_match (arrays): hooks that run only during the in-band pass. See AppSec Hooks.
• on_challenge, on_challenge_submit (arrays): challenge hooks, which only exist in-band. See Bot detection hooks.
• options (object): same as inband_options.
• variables_tracking (array of strings): tracked variables. They are global, so scoping them to a phase has no effect.

YAML

inband:
  rules:
    - crowdsecurity/base-config
  pre_eval:
    - filter: req.RemoteAddr == "192.168.1.100"
      apply:
        - RemoveInBandRuleByName("strict-rule")
  options:
    disable_body_inspection: false

outofband

object

Same keys as inband, applied to the out-of-band pass, except on_challenge and on_challenge_submit: challenges are in-band only.

on_load

array

Executed when the configuration is loaded. Typically used for global rule changes. Not phase-scoped: it runs once at startup, so it has no inband / outofband equivalent.

YAML

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

pre_eval

array

Executed before rule evaluation for each request. Declared at the top level, it runs in both passes, hence the IsInBand filter below. Use inband / outofband to target a single pass.

YAML

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. Runs in both passes, like pre_eval.

YAML

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

on_match

array

Executed when rules match. Used to adjust remediation or generate custom alerts. Runs in both passes, like pre_eval.

YAML

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

For complete hook documentation, see AppSec Hooks.

data

array

Declares datafiles the appsec-config needs. When the config is installed from the hub, cscli downloads each source_url into dest_file (relative to the data directory). The bot-detection exclude-configs use this to ship the known-bot definitions consulted by MatchKnownBot, with type: bots.

YAML

data:
  - source_url: https://hub-data.crowdsec.net/whitelists/benign_bots/legit_bots/gptbot.json
    dest_file: legit_bots/gptbot.json
    type: bots