Skip to main content
Version: Next

Syntax

CrowdSec AppSec rules​

Rules are the core of the AppSec Component. They are used to detect and block attacks.

There are two types of rules:

  • In-band rules are evaluated synchronously and will block request processing until they are evaluated, allowing real-time remediation.
  • Out-of-band rules are evaluated asynchronously and do not delay request processing. They do not trigger immediate remediation, but they are useful for expensive evaluations or more complex detection logic (for example, blocking an exploit that spans multiple requests).

In-band rules and out-of-band rules differ slightly in their default behavior when a rule matches:

  • When an in-band rule matches:
    • an alert is created inside CrowdSec, allowing immediate and long-term remediation against the offending IP.
    • Note: No event will be generated by default.
  • When an out-of-band rule matches:
    • An event will be generated and sent through the normal parsers/scenarios pipeline, allowing the detection of more complex behaviors.
    • Note: No alert is generated by this out-of-band rule alone; the parsers/scenarios pipeline is responsible for raising alerts from processed events.

Rules File Format​

The rule files share some common directives with the scenarios:

name: crowdsecurity/example-rule
description: "Detect example pattern"
rules:
  - zones:
      - URI
    transform:
      - lowercase
    match:
      type: contains
      value: this-is-a-appsec-rule-test
labels:
  type: exploit
  service: http
  behavior: "http:exploit"
  confidence: 3
  spoofable: 0
  label: "A good description of the rule"
  classification:
    - cve.CVE-xxxx-xxxxx
    - attack.Txxxx

Rule Structure​

name​

string

Rule identifier (required at the file level). It should be unique and stable because it is used for logging and troubleshooting.

name: crowdsecurity/example-rule
description: "Detect example pattern"
rules: []

description​

string

Human-readable summary of what the rule is detecting (optional but recommended).

name: crowdsecurity/example-rule
description: "Detect example pattern"
rules: []

labels​

object

Extra metadata used by scenarios and the Hub (optional). The format follows the labels schema.

name: crowdsecurity/example-rule
description: "Detect example pattern"
rules: []
labels:
  type: exploit
  service: http
  behavior: "http:exploit"

rules​

array

List of rule conditions (required). Each condition inspects one or more zones and must include a match.

For a condition:

At minimum, a condition needs a zone list and a match:

- zones:
    - URI
  match:
    type: contains
    value: admin

Conditions can be grouped with boolean operators. Use and when all nested conditions must match, and or when any nested condition can match. If no operator is provided at the rule level, conditions are treated as or by default. Each nested item is a full condition with its own zones and match.

rules:
  - and:
      - zones:
          - METHOD
        match:
          type: regex
          value: (GET|HEAD)
      - zones:
          - URI
        match:
          type: equals
          value: /crowdsec-test-NtktlJHV4TfBSK3wvlhiOBnl

See the appsec-generic-test rule for a full example.

Rule condition fields​

The following fields apply to each rule condition inside rules.

zones​

array of strings

Zones specify which parts of the request are inspected. You can have more than one.

  • (mandatory) zones one or more of:
    • ARGS: Query string parameters
    • ARGS_NAMES: Name of the query string parameters
    • BODY_ARGS: Body args
    • BODY_ARGS_NAMES: Name of the body args
    • COOKIES: Cookies sent in the request
    • COOKIES_NAMES: Names of the cookies sent in the request
    • FILES: Uploaded files in the request
    • FILES_NAMES: Names of uploaded files in the request
    • HEADERS: HTTP headers sent in the request
    • HEADERS_NAMES: Name of the HTTP headers sent in the request
    • METHOD: HTTP method of the request
    • PROTOCOL: HTTP protocol used in the query (HTTP/1.0, HTTP/1.1, ...)
    • URI: The URI of the request
    • URI_FULL: The full URL of the request including the query string
    • RAW_BODY: The entire body of the request
    • FILENAMES: The name of the files sent in the request
    • FILES_TOTAL_SIZE: Total size of the uploaded files in the request,

Each zone entry is a single string from the list above. There are no per-zone required fields beyond choosing at least one zone for the condition.

name: crowdsecurity/example-rule
rules:
  - zones:
      - URI
    match:
      type: contains
      value: admin

variables​

array of strings

Optional list of variable names to restrict the match to specific keys (only relevant for ARGS, BODY_ARGS and HEADERS).

The default config crowdsecurity/base-config enables specific decoders when the following content-types are set:

  • application/x-www-form-urlencoded
  • multipart/form-data
  • application/xml
  • application/json : when used, all the variable names are prefixed with json.
  • text/xml
name: crowdsecurity/example-rule
rules:
  - zones:
      - ARGS
    variables:
      - foo
      - bar
    match:
      type: contains
      value: admin

match​

object

Match provides the pattern to match the target against. You can combine it with a transform.

  • (mandatory) match containing both:

    • (mandatory) type indicates the matching method, one of:

      • regex: matches target against value (value is a RE2 regexp)
      • equals: target is a string equal to value
      • startsWith: target starts with value
      • endsWith: target ends with value
      • contains: target contains value
      • libinjectionSQL: target is detected by lib injection SQL
      • libinjectionXSS: target is detected by lib injection XSS
      • gt: target is greater than value
      • lt: target is lower than value
      • gte: target is greater or equal to value
      • lte: target is lower or equal to value

    • (mandatory) value a string that is compared to the target

name: crowdsecurity/appsec-generic-test
description: "AppSec Generic Test: trigger on GET /crowdsec-test-NtktlJHV4TfBSK3wvlhiOBnl"
rules:
  - and:
      - zones:
          - METHOD
        match:
          type: regex
          value: (GET|HEAD)
      - zones:
          - URI
        match:
          type: equals
          value: /crowdsec-test-NtktlJHV4TfBSK3wvlhiOBnl
labels:
  service: http
  type: test

transform​

array of strings

Optional operations applied to the target before matching:

  • lowercase
  • uppercase
  • b64decode : base64 decode
  • length : transform target to a number representing the string's length
  • urldecode : URL decode
  • trim : remove leading and trailing spaces
  • normalizepath : normalize the path (remove double slashes, etc)
  • htmlEntitydecode : decode HTML entities
  • count : number of times the target appears
name: crowdsecurity/example-rule
rules:
  - zones:
      - URI
    transform:
      - lowercase
    match:
      type: contains
      value: admin

Seclang Support​

In order to support your existing/legacy rules set, CrowdSec's AppSec Component is also able to load rules in the seclang format (ModSecurity rules).

We recommend using this format only to use existing rules you may have.

ModSecurity syntax support is provided by coraza, and the reference documentation is available here.

There are 2 ways to provide crowdsec with seclang rules:

  • Provide rules directly by using the seclang_rules parameter in your rule file
  • Provide a file containing the rules by using the seclang_rules_file parameter in your rule file. The file must be located inside CrowdSec data directory

The default paths for the data directory per OS:

  • Linux: /var/lib/crowdsec/data
  • Freebsd: /var/db/crowdsec/data
  • Windows: C:\programdata\crowdsec\data

Example

name: example/secrules
seclang_rules:
  - SecRule ARGS:ip ";" "t:none,log,deny,msg:'semi colon test',id:2"
seclang_files_rules:
  - my-rule-file.conf

Your rule must have a non-empty msg field to properly trigger an Event/Alert