falco
Version information
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
Add this module to your Puppetfile:
mod 'sysdig-falco', '0.4.0'
Learn more about managing modules with a PuppetfileDocumentation
Falco
Table of Contents
- Overview
- Module Description - What the module does and why it is useful
- Setup - The basics of getting started with Falco
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- 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
orfalse
. Default:true
.
Example:
class { 'falco':
syslog_output => {
'enabled' => 'true',
},
}
file_output
Controls file output for notifications. Value: a hash, containing the following:
enabled
:true
orfalse
. 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
orfalse
. 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.
Dependencies
- puppetlabs-apt (>= 4.5.1 < 4.6.0)
- stahnma/epel (>= 1.3.1 < 1.4.0)
- puppet-logrotate (>= 3.1.0 < 3.2.0)
- puppetlabs/stdlib (>= 4.25.1 < 5.0.0)