Skip to content

Latest commit

 

History

History
456 lines (312 loc) · 11.3 KB

REFERENCE.md

File metadata and controls

456 lines (312 loc) · 11.3 KB
Raw

Reference

Table of Contents

Classes

  • falco: Guides the basic setup and installation of Falco on your system.
  • falco::config: Controls the contents of falco.yaml and sets up log rotate, if needed
  • falco::install: Installs the falco package
  • falco::repo: Manages the repository falco is installed from
  • falco::service: Controls the state of the falco and falcoctl services

Classes

falco

When this class is declared with the default options, Puppet:

  • Installs the appropriate Falco software package and installs the falco-probe kernel module for your operating system.
  • Creates the required configuration file /etc/Falco/falco.yaml. By default only syslog output is enabled.
  • Starts the falco service.

Examples

Using defaults
include falco
Enabling file output
class { 'falco':
  file_output => {
    'enabled'    => 'true',
    'keep_alive' => 'false',
    'filename'   => '/var/log/falco-events.log',
  },
}
Enabling program output
class { 'falco':
  json_output => 'true',
  program_output => {
    'enabled'    => 'true',
    'keep_alive' => 'false',
    'program'    => 'curl http://some-webhook.com'
  },
}
Create local rule
class { 'falco':
  local_rules => [{
    'rule'      => 'The program "sudo" is run in a container',
    'desc'      => 'An event will trigger every time you run sudo in a container',
    'condition' => 'evt.type = execve and evt.dir=< and container.id != host and proc.name = sudo',
    'output'    => 'Sudo run in container (user=%user.name %container.info parent=%proc.pname cmdline=%proc.cmdline)',
    'priority'  => 'ERROR',
    'tags'      => ['users', 'container'],
  }],
}
Local rules, lists, and macro
class { 'falco':
  local_rules => [
    {
      'rule'      => 'The program "sudo" is run in a container',
      'desc'      => 'An event will trigger every time you run sudo in a container',
      'condition' => 'evt.type = execve and evt.dir=< and container.id != host and proc.name = sudo',
      'output'    => 'Sudo run in container (user=%user.name %container.info parent=%proc.pname cmdline=%proc.cmdline)',
      'priority'  => 'ERROR',
      'tags'      => ['users', 'container'],
    },
    {
      'rule'      => 'rule 2',
      'desc'      => 'describing rule 2',
      'condition' => 'evt.type = execve and evt.dir=< and container.id != host and proc.name = sudo',
      'output'    => 'Sudo run in container (user=%user.name %container.info parent=%proc.pname cmdline=%proc.cmdline)',
      'priority'  => 'ERROR',
      'tags'      => ['users'],
    },
    {
      '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)',
    }
  ],
}

Parameters

The following parameters are available in the falco class:

rules_file

Data type: Array

File(s) or Directories containing Falco rules, loaded at startup. The name "rules_file" is only for backwards compatibility. If the entry is a file, it will be read directly. If the entry is a directory, every file in that directory will be read, in alphabetical order.

falco_rules.yaml ships with the falco package and is overridden with every new software version. falco_rules.local.yaml is only created if it doesn't exist. If you want to customize the set of rules, add your customizations to falco_rules.local.yaml.

The files will be read in the order presented here, so make sure if you have overrides they appear in later files.

Default value:

[
    '/etc/falco/falco_rules.yaml',
    '/etc/falco/falco_rules.local.yaml',
    '/etc/falco/k8s_audit_rules.yaml',
    '/etc/falco/rules.d',
  ]
local_rules

Data type: Array[Hash]

An array of hashes of rules to be added to /etc/falco/falco_rules.local.yaml

Default value: []

watch_config_files

Data type: Boolean

Whether to do a hot reload upon modification of the config file or any loaded rule file

Default value: true

json_output

Data type: Boolean

Whether to output events in json or text

Default value: false

json_include_output_property

Data type: Boolean

When using json output, whether or not to include the "output" property itself (e.g. "File below a known binary directory opened for writing (user=root ....") in the json output.

Default value: true

log_stderr

Data type: Boolean

Send information logs to stderr Note these are not security notification logs! These are just Falco lifecycle (and possibly error) logs.

Default value: true

log_syslog

Data type: Boolean

Send information logs to stderr Note these are not security notification logs! These are just Falco lifecycle (and possibly error) logs.

Default value: true

log_level

Data type: Enum['alert', 'critical', 'error', 'warning', 'notice', 'info', 'debug']

Minimum log level to include in logs. Note: these levels are separate from the priority field of rules. This refers only to the log level of falco's internal logging. Can be one of "emergency", "alert", "critical", "error", "warning", "notice", "info", "debug".

Default value: 'info'

priority

Data type: Enum['emergency', 'alert', 'critical', 'error', 'warning', 'notice', 'informational', 'debug']

Minimum rule priority level to load and run. All rules having a priority more severe than this level will be loaded/run. Can be one of "emergency", "alert", "critical", "error", "warning", "notice", "informational", "debug".

Default value: 'debug'

buffered_outputs

Data type: Boolean

Whether or not output to any of the output channels below is buffered. Defaults to false

Default value: false

outputs_rate

Data type: Integer

The number of tokens (i.e. right to send a notification) gained per second.

Default value: 1

outputs_max_burst

Data type: Integer

The maximum number of tokens outstanding.

Default value: 1000

syslog_output

Data type: Hash

A hash to configure the syslog output. See the template for available keys.

Default value:

{
    'enabled' => true,
  }
file_output

Data type: Hash

A hash to configure the file output. See the template for available keys.

Default value:

{
    'enabled'    => false,
    'keep_alive' => false,
    'filename'   => '/var/log/falco-events.log',
  }
stdout_output

Data type: Hash

A hash to configure the stdout output. See the template for available keys.

Default value:

{
    'enabled' => true,
  }
webserver

Data type: Hash

A has to configure the webserver. See the template for available keys.

Default value:

{
    'enabled'              => false,
    'listen_port'          => 8765,
    'k8s_audit_endpoint'   => '/k8s-audit',
    'k8s_healthz_endpoint' => '/healthz',
    'ssl_enabled'          => false,
    'ssl_certificate'      => '/etc/falco/falco.pem',
  }
program_output

Data type: Hash

A hash to configure the program output. See the template for available keys.

Default value:

{
    'enabled'    => false,
    'keep_alive' => false,
    'program'    => '"jq \'{text: .output}\' | curl -d @- -X POST https://hooks.slack.com/services/XXX"',
  }
http_output

Data type: Hash

A hash to configure the http output. See the template for available keys.

Default value:

{
    'enabled'    => false,
    'url'        => 'http://some.url',
    'user_agent' => '"falcosecurity/falco"',
  }
driver

Data type: Enum['bpf', 'modern-bpf', 'kmod']

The desired Falco driver. Can be one of "bpf", "modern-bpf", "kmod". Defaults to "kmod"

Default value: 'kmod'

package_ensure

Data type: String[1]

A string to be passed to the package resource's ensure parameter

Default value: '>= 0.34'

service_ensure

Data type: Variant[Boolean, Enum['running', 'stopped']]

Desired state of the Falco service

Default value: 'running'

service_enable

Data type: Boolean

Start the Falco service on boot?

Default value: true

service_restart

Data type: Boolean

Does the service support restarting?

Default value: true

auto_ruleset_updates

Data type: Boolean

Enable automatic rule updates?

Default value: true

manage_dependencies

Data type: Boolean

Enable managing of dependencies?

Default value: true

manage_repo

Data type: Boolean

When true, let the module manage the repositories. Default is true.

Default value: true

falco::config

Controls the contents of falco.yaml and sets up log rotate, if needed

falco::install

Installs the falco package

falco::repo

Manages the repository falco is installed from

falco::service

Controls the state of the falco and falcoctl services