Skip to main content
Version: Next

Appsec rules syntax

CrowdSec AppSec rules​

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

There are 2 types of rules:

  • In-band rules are evaluated synchronously and will block the processing of the request until they are evaluated thus allowing a real-time remediation
  • Out-band rules Out-band rules are dealt with asynchronously and will not delay the processing of the request. They won't allow remediation at first sight but are very useful for handling expensive evaluations or as part of a more complex detection logic (eg, blocking an exploit that spans multiple requests).

In-band rules and out-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-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 will be generated from this out-band rule only, 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:

  • a name and description
  • a rules section describing the rule to match the HTTP request
  • a label section
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

The rules contain one or more conditions that can be linked together by an operator (or/and). Each condition contains:

Target​

info

The target allows to specify which part of the requests needs to be 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
    • 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
  • (optional) variables containing one or more variable names to restrict the matching operation to (only relevant for ARGS, BODY_ARGS and HEADERS)
#match only in 'foo' and 'bar' query string parameters
- zones:
    - ARGS
  variables:
    - foo
    - bar
---
#match in any args or part of the URI
- zones:
    - URI
    - ARGS
info

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

Match​

info

Match provides the pattern to match the target against, including optional transformations.

  • (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

  • (optional) transform section, containing one or more operations that will be applied on target before performing the match operation:

    • 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
# we want the query parameter foo to be equal to 'toto'
- zones:
    - ARGS
  variables:
    - foo
  match:
    type: equal
    value: toto
---
# we want URI to contain any variation of 'blah' (ie. blah BLah BlAH ...)
- zones:
    - URI
  tranform:
    - uppercase
  match:
    type: contains
    value: BLAH

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
warning

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

CrowdSec ConsoleCrowdSec Console