falco

Sysdig Falco: Behavioral Activity Monitoring With Container Support

Sysdig

sysdig

5,712 downloads

3,189 latest version

2.6 quality score

Version information

  • 0.4.0 (latest)
  • 0.3.0
  • 0.2.0
  • 0.1.0
released Mar 1st 2019
This version is compatible with:
  • Puppet Enterprise 2018.1.x, 2017.3.x, 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet >= 4.7.0 < 6.0.0

Start using this module

Documentation

sysdig/falco — version 0.4.0 Mar 1st 2019

Falco

Table of Contents

  1. Overview
  2. Module Description - What the module does and why it is useful
  3. Setup - The basics of getting started with Falco
  4. Usage - Configuration options and additional functionality
  5. Reference - An under-the-hood peek at what the module is doing and how
  6. Limitations - OS compatibility, etc.
  7. Development - Guide for contributing to the module

Overview

Sysdig Falco is a behavioral activity monitor designed to detect anomalous activity in your applications. Powered by sysdig’s system call capture 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?

Falco can detect and alert on any behavior that involves making Linux system calls. Thanks to Sysdig's core decoding and state tracking functionality, 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

What Falco affects

This module affects the following:

  • The main Falco configuration file /etc/falco/falco.yaml, including Output format (JSON vs plain text) Log level Rule priority level to run Output buffering Output throttling Output channels (syslog, file, program)

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. By default only syslog output is enabled.
  • Starts the Falco service.

Usage

Enabling file output

To enable file output, set the file_output hash, as follows:

class { 'falco':
  file_output => {
    'enabled' => 'true',
    'keep_alive' => 'false',
    'filename' => '/tmp/falco-events.txt'
  },
}

Enabling program output

To enable program output, set the program_output hash and optionally the json_output parameters, as follows:

class { 'falco':
  json_output => 'true',
  program_output => {
    'enabled' => 'true',
    'keep_alive' => 'false',
    'program' => 'curl http://some-webhook.com'
  },
}

Reference

Public Classes

Class: falco

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

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.

You can simply declare the default falco class:

class { 'falco': }
rules_file

An array of files for Falco to load. Order matters--the first file listed will be loaded first.

Default: ['/etc/falco/falco_rules.yaml', '/etc/falco/falco_rules.local.yaml']

json_output

Whether to output events in json or text.

Default: false

log_stderr

Send Falco's logs to stderr. Note: this is not notifications, this is logs from the Falco daemon itself.

Default: false

log_syslog

Send Falco's logs to syslog. Note: this is not notifications, this is logs from the Falco daemon itself.

Default: true

log_level

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: info

priority

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", "info", "debug".

Default: debug

buffered_outputs

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

Default: true

outputs_rate/outputs_max_burst

A throttling mechanism implemented as a token bucket limits the rate of Falco notifications. This throttling is controlled by the following configuration options:

  • outputs_rate: the number of tokens (i.e. right to send a notification) gained per second. Defaults to 1.
  • outputs_max_burst: the maximum number of tokens outstanding. Defaults to 1000.
`syslog_output

Controls syslog output for notifications. Value: a hash, containing the following:

  • enabled: true or false. Default: true.

Example:

class { 'falco':
  syslog_output => {
    'enabled' => 'true',
  },
}
file_output

Controls file output for notifications. Value: a hash, containing the following:

  • enabled: true or false. Default: false.
  • keep_alive: If keep_alive is set to true, the file will be opened once and continuously written to, with each output message on its own line. If keep_alive is set to false, the file will be re-opened for each output message. Default: false.
  • filename: Notifications will be written to this file.

Example:

class { 'falco':
  file_output => {
    'enabled' => 'true',
    'keep_alive' => 'false',
    'filename' => '/tmp/falco-events.txt'
  },
}
`program_output

Controls program output for notifications. Value: a hash, containing the following:

  • enabled: true or false. Default: false.
  • keep_alive: If keep_alive is set to true, the file will be opened once and continuously written to, with each output message on its own line. If keep_alive is set to false, the file will be re-opened for each output message. Default: false.
  • program: Notifications will be written to this program.

Example:

class { 'falco':
  program_output => {
    'enabled' => 'true',
    'keep_alive' => 'false',
    'program' => 'curl http://some-webhook.com'
  },
}

Limitations

The module works where Falco works as a daemonized service (generally, Linux only).

Development

For more information on Sysdig Falco, visit our github or web site.