From f5c3a4d5975913cb68369e3b9deb2deba5dfd80f Mon Sep 17 00:00:00 2001 From: Mark Stemm Date: Fri, 16 Sep 2016 09:25:52 -0700 Subject: [PATCH] Updated Falco Rules (markdown) --- Falco-Rules.md | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/Falco-Rules.md b/Falco-Rules.md index 595bd55..9ee5b47 100644 --- a/Falco-Rules.md +++ b/Falco-Rules.md @@ -2,10 +2,14 @@ _Call for contributions: If you come up with additional rules which you'd like to see in the core repository - PR welcome!_ -A falco rules file is a [YAML](http://www.yaml.org/start.html) file containing two kinds of elements: *rules* and *macros*. Rules consist of a *condition* under which an alert should be generated and a *output string* to send with the alert. +A falco rules file is a [YAML](http://www.yaml.org/start.html) file containing three kinds of elements: *rules*, *macros*, and *lists*. + +Rules consist of a *condition* under which an alert should be generated and a *output string* to send with the alert. Macros are simply rule condition snippets that can be re-used inside rules and other macros, providing a way to factor out and name common patterns. +Lists are (surprise!) lists of items that can be included in rules, macros, or other lists. Unlike rules/macros, they can not be parsed as sysdig filtering expressions. + ## Rules A Rule is a node containing the following keys: @@ -51,6 +55,31 @@ With this macro defined, we can then rewrite the above rule's condition as `in_c For many more examples of rules and macros, please take a look `rules/falco_rules.yaml`. +## Lists + +The third type of item in a rules file is lists. A list is a node with the following keys: + +* _list_: a name for the list +* _items_: a list of values + +Here's an example: + +``` +- list: shell_binaries + items: [bash, csh, ksh, sh, tcsh, zsh, dash] + +- list: userexec_binaries + items: [sudo, su] + +- list: known_binaries + items: [shell_binaries, userexec_binaries] + +- macro: safe_procs + condition: proc.name in (known_binaries) +``` + +Referring to a list inserts the list items in the macro, rule, or list. Note that lists can contain other lists. + ## Rule Condition Best Practices To allow for grouping of rules by event type, which improves performance, falco prefers rule conditions that have at least one `evt.type=` operator, at the beginning of the condition, before any negative operators (i.e. `not` or `!=`). If a condition does not have any `evt.type=` operator, falco will log a warning like: