Skip to main content
Version: v1.2

antonmedv/expr - Expression evaluation engine for Go: fast, non-Turing complete, dynamic typing, static typing

Several places of CrowdSec's configuration use expr, notably :

  • Filters that are used to determine events eligibility in parsers, scenarios and profiles
  • Statics use expr in the expression directive, to compute complex values
  • Whitelists rely on expression directive to allow more complex whitelists filters

To learn more about expr, check the github page of the project.

When CrowdSec relies on expr, a context is provided to let the expression access relevant objects :

  • evt. is the representation of the current event and is the most relevant object
  • in profiles, alert is accessible via the Alert object

If the debug is enabled (in the scenario or parser where expr is used), additional debug will be displayed regarding evaluated expressions.

Helpers

In order to makes its use in CrowdSec more efficient, we added a few helpers that are documented bellow.

Atof(string) float64

Parses a string representation of a float number to an actual float number (binding on strconv.ParseFloat)

Atof(evt.Parsed.tcp_port)

JsonExtract(JsonBlob, FieldName) string

Extract the FieldName from the JsonBlob and returns it as a string. (binding on jsonparser)

JsonExtract(evt.Parsed.some_json_blob, "foo.bar[0].one_item")

File(FileName) []string

Returns the content of FileName as an array of string, while providing cache mechanism.

evt.Parsed.some_field in File('some_patterns.txt')

any(File('rdns_seo_bots.txt'), { evt.Enriched.reverse_dns endsWith #})

RegexpInFile(StringToMatch, FileName) bool

Returns true if the StringToMatch is matched by one of the expressions contained in FileName (uses RE2 regexp engine).

RegexpInFile( evt.Enriched.reverse_dns, 'my_legit_seo_whitelists.txt')

Upper(string) string

Returns the uppercase version of the string

Upper("yop")

IpInRange(IPStr, RangeStr) bool

Returns true if the IP IPStr is contained in the IP range RangeStr (uses net.ParseCIDR)

IpInRange("1.2.3.4", "1.2.3.0/24")

TimeNow() string

Return RFC3339 formatted time

TimeNow()

ParseUri(string) map[string][]string

Parses an URI into a map of string list.

ParseURI("/foo?a=1&b=2") would return :

{
"a": []string{"1"},
"b": []string{"2"}
}

Alert specific helpers

Alert.Remediation bool

Is true if the alert asks for a remediation. Will be true for alerts from scenarios with remediation: true flag. Will be false for alerts from manual cscli decisions add commands (as they come with their own decision).

Alert.GetScenario() string

Returns the name of the scenario that triggered the alert.

Alert.GetScope() string

Returns the scope of an alert. Most common value is Ip. Country and As are generally used for more distributed attacks detection/remediation.

Event specific helpers

Event.GetType() string

Returns the type of an Event : overflow or log.