Falco

Falco is a behavioral activity monitor designed to detect anomalous activity in your applications. Powered by Falco libraries system call capture and inspection infrastructure, Falco lets you continuously monitor and detect container, application, host, and network activity... all in one place, from one source of data, with one set of rules.

• What kind of behaviors can Falco detect?
• Module Description
• Setup
  • Beginning with Falco
• Reference
• Limitations
• Development
  • History

What kind of behaviors can Falco detect?

Falco can detect and alert on any behavior that involves making Linux system calls. Thanks to the Falco drivers, libscap and libsinsp Falco libraries which capture, parse, enrich and filter collected system calls as a raw data source, Falco alerts can be triggered by the use of specific system calls, their arguments, and by properties of the calling process. For example, you can easily detect things like:

• A shell is run inside a container
• A container is running in privileged mode, or is mounting a sensitive path like /proc from the host.
• A server process spawns a child process of an unexpected type
• Unexpected read of a sensitive file (like /etc/shadow)
• A non-device file is written to /dev
• A standard system binary (like ls) makes an outbound network connection

Module Description

This module configures Falco as a systemd service. You configure Falco to send its notifications to one or more output channels (syslog, files, programs).

Setup

Beginning with Falco

To have Puppet install Falco with the default parameters, declare the Falco class:

class { 'falco': }

When you declare this class with the default options, the module:

• 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.
• Manages the local rules file /etc/falco/falco_rules.local.yaml.
• Starts the Falco service.

Reference

This module is documented via bundle exec rake strings:generate:reference. Please see REFERENCE.md for more info and example usage.

Limitations

The module works where Falco works as a daemonized service (generally, Linux only). Also, newer configuration options in falco.yaml may not have been templated yet... PRs welcome if you find such a case.

Development

PRs are welcome!

History

This module is derrived from falcosecurity/evolution. That code came from falcosecurity/falco as part of resolving issue #1114. The old code is the basis for sysdig/falco. #2005 was submitted to request that module be depreciated since it appears to be abondoned.

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
• local_rules
• watch_config_files
• json_output
• json_include_output_property
• log_stderr
• log_syslog
• log_level
• priority
• buffered_outputs
• outputs_rate
• outputs_max_burst
• syslog_output
• file_output
• stdout_output
• webserver
• program_output
• http_output
• driver
• package_ensure
• service_ensure
• service_enable
• service_restart
• auto_ruleset_updates
• manage_dependencies
• manage_repo

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

Changelog

All notable changes to this project will be documented in this file. Each new release typically also includes the latest modulesync defaults. These should not affect the functionality of the module.

v3.0.1 (2023-07-17)

Full Changelog

Merged pull requests:

• Fix falco fact #31 (hunner)

v3.0.0 (2023-07-06)

Full Changelog

Breaking changes:

• Drop Puppet 6 support #27 (bastelfreak)

Implemented enhancements:

• Add feature flag to enable/disable managing of the falco repository #24 (jordyb6)
• Add watch_config _files parameter #23 (jordyb6)

Fixed bugs:

• Make falco file output really optional #28 (claviola)
• Fix falco-driver-loader bpf #26 (jordyb6)
• Fix: Add missing dependencies when building bpf probe #25 (jordyb6)

v2.0.0 (2023-04-13)

Full Changelog

Breaking changes:

• (ITSYS-2824) Falco >= 0.34.0 Compatibility #20 (yachub)

v1.2.0 (2023-04-11)

Full Changelog

Implemented enhancements:

• Add support for SUSE Linux, add EL 9 to metadata #13 (genebean)

Fixed bugs:

• Apt key errors #16
• Update repo keys #17 (genebean)

v1.1.0 (2022-06-01)

Full Changelog

Implemented enhancements:

• Allow local rules to be applied; require puppetlabs/stdlib 8.2 or newer #11 (genebean)

v1.0.1 (2022-05-25)

Full Changelog

Closed issues:

• release workflow has wrong owner listed #9

v1.0.0 (2022-05-24)

Full Changelog

This is the first release as part of Vox Pupuli.

This module is derrived from falcosecurity/evolution. That code came from falcosecurity/falco as part of resolving issue https://github.com/falcosecurity/falco/issues/1114. The old code is the basis for sysdig/falco. https://github.com/falcosecurity/falco/issues/2005 was submitted to request that module be depreciated since it appears to be abandoned.

The v1.0.0 release includes an overhaul of the code to make everything work and bring it up to current coding standards. It also incorporates all the change needed as part of migrating a module to Vox Pupuli.

Breaking changes:

• Rework module post-fork #1 (genebean)

Fixed bugs:

• Fix default value for program_output #6 (genebean)

Closed issues:

• Falco crashes due to formatting error in config file #7
• Update metadata.json to reflect transfer to Vox Pupuli #2

Merged pull requests:

• Add missing files, update metadata post-migration #3 (genebean)

v0.4.0 (2022-05-19)

Full Changelog

* This Changelog was automatically generated by github_changelog_generator