Skip to main content
Version: v1.3.0

Helpers

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

KeyExists(key string, map map[string]interface{}) bool#

Return true if the key exist in the map.

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.

Alert.GetSources() []string#

Return the list of IP addresses in the alert sources.

Alert.GetEventsCount() int32#

Return the number of events in the bucket.

Event specific helpers#

Event.GetType() string#

Returns the type of an Event : overflow or log.

Event.GetMeta(key string) string#

Return the value of the Meta[key] in the Event object (Meta are filled only for events of type overflow).

Source specific helpers#

Source.GetValue() string#

Return the Source.Value field value of a Source.

Source.GetScope() string#

Return the Source.Scope field value of Source (ip, range ...)