Skip to main content
Version: Next

Hooks

The Application Security Component allows you to hook at different stages to change its behavior at runtime.

The three phases are:

  • on_load: Called just after the rules have been loaded into the engine.
  • pre_eval: Called after a request has been received but before the rules are evaluated.
  • post_eval: Called after the rules have been evaluated.
  • on_match: Called after a successful match of a rule. If multiple rules, this hook will be called only once.

Using hooks

Hooks are configured in your appsec-config file.

Except for the on_load hook, all hooks support a filter parameter and an apply parameter (on_load only has apply).

Both filter and apply of the same phase have access to the same helpers.

Except for on_load, hooks can be called twice per request: once for in-band processing and once for out-of-band processing, thus it is recommended to use the IsInBand and IsOutBand variables to filter the hook.

on_load

This hook is intended to be used to disable rules at loading (eg, to temporarily disable a rule that is causing false positives).

Available helpers

Helper NameTypeDescription
RemoveInBandRuleByNamefunc(tag str)Disable the named in-band rule
RemoveInBandRuleByTagfunc(tag str)Disable the in-band rule identified by the tag (multiple rules can have the same tag)
RemoveInBandRuleByIDfunc(id int)Disable the in-band rule identified by the ID
RemoveOutBandRuleByNamefunc(tag str)Disable the named out-of-band rule
RemoveOutBandRuleByTagfunc(tag str)Disable the out-of-band rule identified by the tag (multiple rules can have the same tag)
RemoveOutBandRuleByIDfunc(id int)Disable the out-of-band rule identified by the ID
SetRemediationByTagfunc(tag str, remediation string)Change the remediation of the in-band rule identified by the tag (multiple rules can have the same tag)
SetRemediationByIDfunc(id int, remediation string)Change the remediation of the in-band rule identified by the ID
SetRemediationByNamefunc(name str, remediation string)Change the remediation of the in-band rule identified by the name
Example
name: crowdsecurity/my-appsec-config
default_remediation: ban
inband_rules:
- crowdsecurity/base-config
- crowdsecurity/vpatch-*
on_load:
- apply:
- RemoveInBandRuleByName("my_rule")
- SetRemediationByTag("my_tag", "captcha")

pre_eval

This hook is intended to be used to disable rules only for this particular request (eg, to disable a rule for a specific IP).

Available helpers

Helper NameTypeDescription
RemoveInBandRuleByNamefunc(tag str)Disable the named in-band rule
RemoveInBandRuleByTagfunc(tag str)Disable the in-band rule identified by the tag (multiple rules can have the same tag)
RemoveInBandRuleByIDfunc(id int)Disable the in-band rule identified by the ID
RemoveOutBandRuleByNamefunc(tag str)Disable the named out-of-band rule
RemoveOutBandRuleByTagfunc(tag str)Disable the out-of-band rule identified by the tag (multiple rules can have the same tag)
RemoveOutBandRuleByIDfunc(id int)Disable the out-of-band rule identified by the ID
IsInBandbooltrue if the request is in the in-band processing phase
IsOutBandbooltrue if the request is in the out-of-band processing phase
SetRemediationByTagfunc(tag str, remediation string)Change the remediation of the in-band rule identified by the tag (multiple rules can have the same tag)
SetRemediationByIDfunc(id int, remediation string)Change the remediation of the in-band rule identified by the ID
SetRemediationByNamefunc(name str, remediation string)Change the remediation of the in-band rule identified by the name
reqhttp.RequestOriginal HTTP request received by the remediation component

Example

name: crowdsecurity/my-appsec-config
default_remediation: ban
inband_rules:
- crowdsecurity/base-config
- crowdsecurity/vpatch-*
pre_eval:
- filter: IsInBand == true && req.RemoteAddr == "42.42.42.42"
apply:
- RemoveInBandRuleByName("my_rule")

post_eval

This hook is mostly intended for debugging or threat-hunting purposes.

Available helpers

Helper NameTypeDescription
IsInBandbooltrue if the request is in the in-band processing phase
IsOutBandbooltrue if the request is in the out-of-band processing phase
DumpRequestfunc()Dump the request to a file
reqhttp.RequestOriginal HTTP request received by the remediation component

DumpRequest

In order to make DumpRequest write your request to a file, you have to call DumpRequest().ToJSON(), which will create a file in the OS temporary directory (eg, /tmp on Linux) with the following format: crowdsec_req_dump_<RANDOM_PART>.json.

You can configure what is dumped with the following options:

  • DumpRequest().NoFilters(): Clear any previous filters (ie. dump everything)
  • DumpRequest().WithEmptyHeadersFilters(): Clear the headers filters, ie. dump all the headers
  • DumpRequest().WithHeadersContentFilter(regexp string): Add a filter on the content of the headers, ie. dump only the headers that do not match the provided regular expression
  • DumpRequest().WithHeadersNameFilter(regexp string): Add a filter on the name of the headers, ie. dump only the headers that do not match the provided regular expression
  • DumpRequest().WithNoHeaders(): Do not dump the request headers
  • DumpRequest().WithHeaders(): Dump all the request headers (override any previous filter)
  • DumpRequest().WithBody(): Dump the request body
  • DumpRequest().WithNoBody(): Do not dump the request body
  • DumpRequest().WithEmptyArgsFilters(): Clear the query parameters filters, ie. dump all the query parameters
  • DumpRequest().WithArgsContentFilter(regexp string): Add a filter on the content of the query parameters, ie. dump only the query parameters that do not match the provided regular expression
  • DumpRequest().WithArgsNameFilter(regexp string): Add a filter on the name of the query parameters, ie. dump only the query parameters that do not match the provided regular expression

By default, everything is dumped. All regexps are case-insensitive.

You can chain the options, for example:

DumpRequest().WithNoBody().WithArgsNameFilter("var1").WithArgsNameFilter("var2").ToJSON()

This will discard the body of the request, remove the query parameters var1 and var2 from the dump, and dump everything else.

Example

name: crowdsecurity/my-appsec-config
default_remediation: ban
inband_rules:
- crowdsecurity/base-config
- crowdsecurity/vpatch-*
post_eval:
- filter: IsInBand == true
apply:
- DumpRequest().NoFilters().WithBody().ToJSON()

on_match

This hook is intended to be used to change the behavior of the engine after a match (eg, to change the remediation that will be used dynamically).

Available helpers

Helper NameTypeDescription
SetRemediationfunc(remediation string)Change the remediation that will be returned to the remediation component
SetReturnCodefunc(code int)Change the HTTP code that will be returned to the remediation component
CancelAlertfunc()Prevent the Application Security Component to create a crowdsec alert
SendAlertfunc()Force the Application Security Component to create a crowdsec alert
CancelEventfunc()Prevent the Application Security Component to create a crowdsec event
SendEventfunc()Force the Application Security Component to create a crowdsec event
DumpRequestfunc()Dump the request to a file (see previous section for detailed usage)
IsInBandbooltrue if the request is in the in-band processing phase
IsOutBandbooltrue if the request is in the out-of-band processing phase
evttypes.EventThe event that has been generated by the Application Security Component
reqhttp.RequestOriginal HTTP request received by the remediation component

Example

name: crowdsecurity/my-appsec-config
default_remediation: ban
inband_rules:
- crowdsecurity/base-config
- crowdsecurity/vpatch-*
post_eval:
- filter: IsInBand == true && req.RemoteAddr == "42.42.42.42"
apply:
- CancelAlert()
- CancelEvent()