Updated Falco Rules (markdown)

Falco-Rules.md

@@ -66,7 +66,7 @@ The third type of item in a rules file is lists. A list is a node with the follo
 
 Here's an example:
 
-```
+```yaml
 - list: shell_binaries
   items: [bash, csh, ksh, sh, tcsh, zsh, dash]
 
@@ -82,13 +82,19 @@ Here's an example:
 
 Referring to a list inserts the list items in the macro, rule, or list. Note that lists can contain other lists.
 
-### Appending to Lists
-(This feature isn't in any official Falco release yet, but it was added to the dev version as of https://github.com/draios/falco/pull/264)
+## Appending to Lists, Rules, and Macros
 
-If you use multiple falco rules files, you might want to append new items to an existing list. To do that, define a list with the same name as an existing list, and add an `append: true` attribute to the list. Here's an example:
+If you use multiple falco rules files, you might want to append new items to an existing list, rule, or macro. To do that, define a item with the same name as an existing item and add an `append: true` attribute to the list. When appending lists, items are added to the end of the list. When appending rules/macros, the additional text is appended to the condition: field of the rule/macro.
 
-**falco_rules.yaml**
-```
+### Examples
+
+In all of the examples below, it's assumed one is running falco via `falco -r /etc/falco/falco_rules.yaml -r /etc/falco/falco_rules.local.yaml`, or has the default entries for `rules_file` in falco.yaml, which has `/etc/falco/falco.yaml` first and `/etc/falco/falco_rules.local.yaml` second.
+
+#### Appending to lists
+Here's an example of appending to lists:
+
+**/etc/falco/falco_rules.yaml**
+```yaml
 - list: my_programs
   items: [ls, cat, pwd]
 
@@ -99,14 +105,77 @@ If you use multiple falco rules files, you might want to append new items to an
   priority: INFO
 ```
 
-**falco_rules-additional.yaml**
-```
+**/etc/falco/falco_rules.local.yaml**
+```yaml
 - list: my_programs
   append: true
   items: [cp]
 ```
 
-If you ran falco via `falco -r falco_rules.yaml -r falco_rules-additional.yaml`, the rule `my_programs_opened_file` would trigger whenever any of `ls`, `cat`, `pwd`, or `cp` opened a file.
+The rule `my_programs_opened_file` would trigger whenever any of `ls`, `cat`, `pwd`, or `cp` opened a file.
+
+### Appending to Macros
+Here's an example of appending to macros:
+
+**/etc/falco/falco_rules.yaml**
+```yaml
+- macro: access_file
+  condition: evt.type=open
+
+- rule: program_accesses_file
+  desc: track whenever a set of programs opens a file
+  condition: proc.name in (cat, ls) and (access_file)
+  output: a tracked program opened a file (user=%user.name command=%proc.cmdline file=%fd.name)
+  priority: INFO
+```
+
+**/etc/falco/falco_rules.local.yaml**
+```yaml
+- macro: access_file
+  append: true
+  items: or evt.type=openat
+```
+
+The rule `program_accesses_file` would trigger when `ls`/`cat` either used `open`/`openat` on a file.
+
+### Appending to Rules
+Here's an example of appending to rules:
+
+**/etc/falco/falco_rules.yaml**
+```yaml
+- rule: program_accesses_file
+  desc: track whenever a set of programs opens a file
+  condition: proc.name in (cat, ls) and evt.type=open
+  output: a tracked program opened a file (user=%user.name command=%proc.cmdline file=%fd.name)
+  priority: INFO
+```
+
+**/etc/falco/falco_rules.local.yaml**
+```yaml
+- rule: program_accesses_file
+  append: true
+  items: and not user.name=root
+```
+The rule `program_accesses_file` would trigger when `ls`/`cat` either used `open` on a file, but not if the user was root.
+
+### Gotchas with rule/macro append and logical operators
+
+Remember that when appending rules and macros, the text of the second rule/macro is simply added to the condition of the first rule/macro. This can result in unintended results if the original rule/macro has potentially ambiguous logical operators. Here's an example:
+
+```yaml
+- rule: my_rule
+  desc: ...
+  condition: evt.type=open and proc.name=apache
+  output: ...
+
+- rule: my_rule
+  append: true
+  condition: or proc.name=nginx
+```
+
+Should `proc.name=nginx` be interpreted as relative to the `and proc.name=apache`, that is to allow either apache/nginx to open files, or relative to the `evt.type=open`, that is to allow apache to open files or to allow nginx to do anything?
+
+In cases like this, be sure to scope the logical operators of the original condition with parentheses when possible, or avoid appending conditions when not possible.
 
 ## Rule Priorities