Puppet Class: falco

Inherited by:

falco::repo
falco::config
falco::install
falco::service

Defined in:

manifests/init.pp

Summary

Guides the basic setup and installation of Falco on your system.

Overview

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:

• rules_file (Array) (defaults to: [ '/etc/falco/falco_rules.yaml', '/etc/falco/falco_rules.local.yaml', '/etc/falco/k8s_audit_rules.yaml', '/etc/falco/rules.d', ]) —

  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.

• local_rules (Array[Hash]) (defaults to: []) —

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

• watch_config_files (Boolean) (defaults to: true) —

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

• json_output (Boolean) (defaults to: false) —

  Whether to output events in json or text

• json_include_output_property (Boolean) (defaults to: true) —

  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.

• log_stderr (Boolean) (defaults to: true) —

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

• log_syslog (Boolean) (defaults to: true) —

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

• log_level (Enum['alert', 'critical', 'error', 'warning', 'notice', 'info', 'debug']) (defaults to: 'info') —

  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”.

• priority (Enum['emergency', 'alert', 'critical', 'error', 'warning', 'notice', 'informational', 'debug']) (defaults to: '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”.

• buffered_outputs (Boolean) (defaults to: false) —

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

• outputs_rate (Integer) (defaults to: 1) —

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

• outputs_max_burst (Integer) (defaults to: 1000) —

  The maximum number of tokens outstanding.

• syslog_output (Hash) (defaults to: { 'enabled' => true, }) —

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

• file_output (Hash) (defaults to: { 'enabled' => false, 'keep_alive' => false, 'filename' => '/var/log/falco-events.log', }) —

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

• stdout_output (Hash) (defaults to: { 'enabled' => true, }) —

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

• webserver (Hash) (defaults to: { 'enabled' => false, 'listen_port' => 8765, 'k8s_audit_endpoint' => '/k8s-audit', 'k8s_healthz_endpoint' => '/healthz', 'ssl_enabled' => false, 'ssl_certificate' => '/etc/falco/falco.pem', }) —

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

• program_output (Hash) (defaults to: { 'enabled' => false, 'keep_alive' => false, 'program' => '"jq \'{text: .output}\' | curl -d @- -X POST https://hooks.slack.com/services/XXX"', }) —

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

• http_output (Hash) (defaults to: { 'enabled' => false, 'url' => 'http://some.url', 'user_agent' => '"falcosecurity/falco"', }) —

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

• driver (Enum['bpf', 'modern-bpf', 'kmod']) (defaults to: 'kmod') —

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

• package_ensure (String[1]) (defaults to: '>= 0.34') —

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

• service_ensure (Variant[Boolean, Enum['running', 'stopped']]) (defaults to: 'running') —

  Desired state of the Falco service

• service_enable (Boolean) (defaults to: true) —

  Start the Falco service on boot?

• service_restart (Boolean) (defaults to: true) —

  Does the service support restarting?

• auto_ruleset_updates (Boolean) (defaults to: true) —

  Enable automatic rule updates?

• manage_dependencies (Boolean) (defaults to: true) —

  Enable managing of dependencies?

• manage_repo (Boolean) (defaults to: true) —

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

# File 'manifests/init.pp', line 192

class falco (
  # Configuration parameters
  Array $rules_file = [
    '/etc/falco/falco_rules.yaml',
    '/etc/falco/falco_rules.local.yaml',
    '/etc/falco/k8s_audit_rules.yaml',
    '/etc/falco/rules.d',
  ],
  Array[Hash] $local_rules = [],
  Boolean $watch_config_files = true,
  Boolean $json_output = false,
  Boolean $json_include_output_property = true,

  Boolean $log_stderr = true,
  Boolean $log_syslog = true,
  Enum['alert', 'critical', 'error', 'warning', 'notice', 'info', 'debug'] $log_level = 'info',
  Enum['emergency', 'alert', 'critical', 'error', 'warning', 'notice', 'informational', 'debug'] $priority = 'debug',

  Boolean $buffered_outputs = false,
  Integer $outputs_rate = 1,
  Integer $outputs_max_burst = 1000,

  Hash $syslog_output = {
    'enabled' => true,
  },
  Hash $file_output = {
    'enabled'    => false,
    'keep_alive' => false,
    'filename'   => '/var/log/falco-events.log',
  },
  Hash $stdout_output = {
    'enabled' => true,
  },
  Hash $webserver = {
    'enabled'              => false,
    'listen_port'          => 8765,
    'k8s_audit_endpoint'   => '/k8s-audit',
    'k8s_healthz_endpoint' => '/healthz',
    'ssl_enabled'          => false,
    'ssl_certificate'      => '/etc/falco/falco.pem',
  },
  Hash $program_output = {
    'enabled'    => false,
    'keep_alive' => false,
    'program'    => '"jq \'{text: .output}\' | curl -d @- -X POST https://hooks.slack.com/services/XXX"',
  },
  Hash $http_output = {
    'enabled'    => false,
    'url'        => 'http://some.url',
    'user_agent' => '"falcosecurity/falco"',
  },

  Enum['bpf', 'modern-bpf', 'kmod'] $driver = 'kmod',

  Boolean $manage_repo = true,

  # Installation parameters
  String[1] $package_ensure = '>= 0.34',

  # Service parameters
  Variant[Boolean, Enum['running', 'stopped']] $service_ensure = 'running',
  Boolean $service_enable = true,
  Boolean $service_restart = true,
  Boolean $auto_ruleset_updates = true,
  Boolean $manage_dependencies = true,
) {
  Class['falco::repo']
  -> Class['falco::install']
  -> Class['falco::config']
  ~> Class['falco::service']

  contain falco::repo
  contain falco::install
  contain falco::config
  contain falco::service
}