Sysdig Platform CLI - Falco Macros

This section explains concepts and notations in the set of the Falco Macros commands provided.

Usage

The Falco Macros section contains the following subcommands:

$ sdc-cli policy falco-macro     
Usage: sdc-cli policy falco-macro [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  add     Add a falco macro
  del     Delete falco macro
  get     Get falco macro
  list    List all falco macros
  update  Update falco macro

Listing all the existing Falco macros

There are a lot of Falco macros that come by default with Sysdig Secure (and cannot be removed nor modified). To list all the macros that you have available in your installation use:

$ sdc-cli policy falco-macro list
ids                 name                                                          
[235]               access_log_files                                              
[131]               access_repositories                                           
[146, 14614]        add_shell_writing_shells_tmp                                  
[122]               airflow_writing_state             
...

Here you will see some macros that have multiple IDs. That’s because another macro with the same name is appending a condition to the existing one called add_shell_writing_shells_tmp.

Retrieve more information of a macro

To see the actual contents of the macro, you can execute:

$ sdc-cli policy falco-macro get 146
id:                       146
name:                     add_shell_writing_shells_tmp
condition:
    {
      "condition": "(proc.name=add-shell and fd.name=/etc/shells.tmp)"
    }
filename:                 falco_rules.yaml

$ sdc-cli policy falco-macro get 14614
id:                       14614
name:                     add_shell_writing_shells_tmp
condition:
    {
      "condition": "and proc.name=foo"
    }
filename:                 falco_rules_local.yaml

The first macro contains (proc.name=add-shell and fd.name=/etc/shells.tmp) and the appending one and proc.name=foo, so the whole macro named add_shell_writing_shells_tmp will have (proc.name=add-shell and fd.name=/etc/shells.tmp) and proc.name=foo as condition. Appending macros to the existing ones gives the language more flexibility since a single macro can be used in multiple rules, and in other macros themselves.

Add a new macro

You can create new macros with:

$ sdc-cli policy falco-macro add --help
Usage: sdc-cli policy falco-macro add [OPTIONS] NAME CONDITION

  NAME: the name of the new falco macro.

  CONDITION: the full condition text exactly as represented in the yaml
  file.

Options:
  --help  Show this message and exit.

The condition can reference other macros or lists as well.

For example if you want to create a macro that’s able to detect that a shell was spawned in a container, you can create the following condition container and shell_procs, which will expand to (container.id != host) and proc.name in (shell_binaries), where shell_binaries is a list that contains ["ash", "bash", "csh", "ksh", "sh", "tcsh", "zsh", "dash"].

So the full condition of the macro will be evaluated as: (container.id != host) and proc.name in ("ash", "bash", "csh", "ksh", "sh", "tcsh", "zsh", "dash").

$ sdc-cli policy falco-macro add shell_in_container 'container and shell_procs'
id:                       14621
name:                     shell_in_container
condition:
    {
      "condition": "container and shell_procs",
      "components": []
    }
filename:                 falco_rules_local.yaml

Update a Falco macro

Falco macro can be updated by their ID. Currently there’s no way to specify the name itself, so the ID needs to be retrieved from a list command.

In the following example we will not evaluate the shell processes against allowed containers:

$ sdc-cli policy falco-macro update 14621 'container and not allowed_containers and shell_procs'
id:                       14621
name:                     shell_in_container
condition:
    {
      "condition": "container and not allowed_containers and shell_procs"
    }
filename:                 falco_rules_local.yaml

Now the rule will not be executed against allowed containers.

Remove a macro

Macros can be removed using the CLI if the following is true:

• The macro is not being used by another Macro or a Rule.
• The macro is not provided by Sysdig.

To remove the last macro created in the previous examples execute:

$ sdc-cli policy falco-macro del 14621                                                           
Success

Currently there’s no way to specifiy the name of the macro itself, and the ID is needed, so first, retrieve it with a list command.