diff --git a/integrations/puppet-module/sysdig-falco/Gemfile b/integrations/puppet-module/sysdig-falco/Gemfile index 7bd34cda751..87b743e59e6 100644 --- a/integrations/puppet-module/sysdig-falco/Gemfile +++ b/integrations/puppet-module/sysdig-falco/Gemfile @@ -1,6 +1,6 @@ source 'https://rubygems.org' -puppetversion = ENV.key?('PUPPET_VERSION') ? "= #{ENV['PUPPET_VERSION']}" : ['>= 3.3'] +puppetversion = ENV.key?('PUPPET_VERSION') ? "= #{ENV['PUPPET_VERSION']}" : ['>= 4.7'] gem 'puppet', puppetversion gem 'puppetlabs_spec_helper', '>= 0.1.0' gem 'puppet-lint', '>= 0.3.2' diff --git a/integrations/puppet-module/sysdig-falco/README.md b/integrations/puppet-module/sysdig-falco/README.md index 8e8f89ea730..03fc7e809cb 100644 --- a/integrations/puppet-module/sysdig-falco/README.md +++ b/integrations/puppet-module/sysdig-falco/README.md @@ -1,12 +1,12 @@ -# falco +# Falco #### Table of Contents 1. [Overview](#overview) 2. [Module Description - What the module does and why it is useful](#module-description) -3. [Setup - The basics of getting started with falco](#setup) - * [What falco affects](#what-falco-affects) - * [Beginning with falco](#beginning-with-falco) +3. [Setup - The basics of getting started with Falco](#setup) + * [What Falco affects](#what-falco-affects) + * [Beginning with Falco](#beginning-with-falco) 4. [Usage - Configuration options and additional functionality](#usage) 5. [Reference - An under-the-hood peek at what the module is doing and how](#reference) 5. [Limitations - OS compatibility, etc.](#limitations) @@ -14,11 +14,11 @@ ## 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. +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: +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. @@ -29,17 +29,17 @@ Falco can detect and alert on any behavior that involves making Linux system cal ## Module Description -This module configures falco as a systemd service. You configure falco +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 +### What Falco affects This module affects the following: -* The main falco configuration file `/etc/falco/falco.yaml`, including +* The main Falco configuration file `/etc/falco/falco.yaml`, including ** Output format (JSON vs plain text) ** Log level ** Rule priority level to run @@ -47,9 +47,9 @@ This module affects the following: ** Output throttling ** Output channels (syslog, file, program) -### Beginning with falco +### Beginning with Falco -To have Puppet install falco with the default parameters, declare the falco class: +To have Puppet install Falco with the default parameters, declare the Falco class: ``` puppet class { 'falco': } @@ -57,9 +57,9 @@ 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. +* 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. +* Starts the Falco service. ## Usage @@ -101,12 +101,12 @@ class { 'falco': #### Class: `falco` -Guides the basic setup and installation of falco on your system. +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. +* 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: @@ -117,7 +117,7 @@ class { 'falco': } ###### `rules_file` -An array of files for falco to load. Order matters--the first file listed will be loaded first. +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']` @@ -129,15 +129,15 @@ Default: `false` ##### `log_stderr` -Send falco's logs to stderr. Note: this is not notifications, this is -logs from the falco daemon itself. +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. +Send Falco's logs to syslog. Note: this is not notifications, this is +logs from the Falco daemon itself. Default: `true` @@ -145,7 +145,7 @@ Default: `true` 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", +log level of Falco's internal logging. Can be one of "emergency", "alert", "critical", "error", "warning", "notice", "info", "debug". Default: `info` @@ -169,7 +169,7 @@ 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 +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) @@ -234,8 +234,8 @@ class { 'falco': ## Limitations -The module works where falco works as a daemonized service (generally, Linux only). +The module works where Falco works as a daemonized service (generally, Linux only). ## Development -For more information on Sysdig Falco, visit our [github](https://github.com/draios/falco) or [web site](https://sysdig.com/opensource/falco/). +For more information on Sysdig Falco, visit our [github](https://github.com/falcosecurity/falco) or [web site](https://sysdig.com/opensource/falco/). diff --git a/integrations/puppet-module/sysdig-falco/manifests/config.pp b/integrations/puppet-module/sysdig-falco/manifests/config.pp index 68ccd594094..460524b436d 100644 --- a/integrations/puppet-module/sysdig-falco/manifests/config.pp +++ b/integrations/puppet-module/sysdig-falco/manifests/config.pp @@ -1,13 +1,12 @@ # == Class: falco::config class falco::config inherits falco { - file { '/etc/falco/falco.yaml': - notify => Service['falco'], ensure => file, + require => Class['falco::install'], + notify => Service['falco'], owner => 'root', group => 'root', mode => '0644', content => template('falco/falco.yaml.erb'), } - -} \ No newline at end of file +} diff --git a/integrations/puppet-module/sysdig-falco/manifests/init.pp b/integrations/puppet-module/sysdig-falco/manifests/init.pp index 1e944b1e110..8a718f7604b 100644 --- a/integrations/puppet-module/sysdig-falco/manifests/init.pp +++ b/integrations/puppet-module/sysdig-falco/manifests/init.pp @@ -1,31 +1,39 @@ +# == Class: falco class falco ( - $rules_file = [ - '/etc/falco/falco_rules.yaml', - '/etc/falco/falco_rules.local.yaml' - ], - $json_output = 'false', - $log_stderr = 'false', - $log_syslog = 'true', - $log_level = 'info', - $priority = 'debug', - $buffered_outputs = 'true', - $outputs_rate = 1, - $outputs_max_burst = 1000, - $syslog_output = { - 'enabled' => 'true' - }, - $file_output = { - 'enabled' => 'false', - 'keep_alive' => 'false', - 'filename' => '/tmp/falco_events.txt' - }, - $program_output = { - 'enabled' => 'false', - 'keep_alive' => 'false', - 'program' => 'curl http://some-webhook.com' - }, - ) { - include falco::install - include falco::config - include falco::service + # Configuration parameters + $rules_file = $falco::params::rules_file, + $json_output = $falco::params::json_output, + $json_include_output_property = $falco::params::json_include_output_property, + + $log_stderr = $falco::params::log_stderr, + $log_syslog = $falco::params::log_syslog, + $log_level = $falco::params::log_level, + $priority = $falco::params::priority, + + $buffered_outputs = $falco::params::buffered_outputs, + $outputs_rate = $falco::params::outputs_rate, + $outputs_max_burst = $falco::params::outputs_max_burst, + + $syslog_output = $falco::params::syslog_output, + $file_output = $falco::params::file_output, + $stdout_output = $falco::params::stdout_output, + $webserver = $falco::params::webserver, + $program_output = $falco::params::program_output, + $http_output = $falco::params::http_output, + + # Installation parameters + $package_ensure = $falco::params::package_ensure, + + # Service parameters + $service_ensure = $falco::params::service_ensure, + $service_enable = $falco::params::service_enable, + $service_restart = $falco::params::service_restart, +) inherits falco::params { + contain falco::install + contain falco::config + contain falco::service + + Class['::falco::install'] + -> Class['::falco::config'] + ~> Class['::falco::service'] } diff --git a/integrations/puppet-module/sysdig-falco/manifests/install.pp b/integrations/puppet-module/sysdig-falco/manifests/install.pp index a057559da8f..1218b2cb46f 100644 --- a/integrations/puppet-module/sysdig-falco/manifests/install.pp +++ b/integrations/puppet-module/sysdig-falco/manifests/install.pp @@ -1,6 +1,61 @@ # == Class: falco::install class falco::install inherits falco { + case $::osfamily { + 'Debian': { + apt::source { 'sysdig': + location => 'http://download.draios.com/stable/deb', + release => 'stable-$(ARCH)/', + repos => '', + key => { + source => 'https://s3.amazonaws.com/download.draios.com/DRAIOS-GPG-KEY.public', + id => 'D27A72F32D867DF9300A241574490FD6EC51E8C4' + }, + } + + ensure_packages(["linux-headers-${::kernelrelease}"]) + + $dependencies = [ + Apt::Source['sysdig'], + Package["linux-headers-${::kernelrelease}"], + ] + } + 'RedHat': { + include 'epel' + + yumrepo { 'sysdig': + baseurl => 'http://download.draios.com/stable/rpm/$basearch', + descr => 'Sysdig repository by Draios', + enabled => 1, + gpgcheck => 0, + } + + ensure_packages(["kernel-devel-${::kernelrelease}"]) + + $dependencies = [ + Yumrepo['sysdig'], + Class['epel'] + ] + } + default: { + $dependencies = [] + } + } + package { 'falco': - ensure => installed, + ensure => $::falco::package_ensure, + require => $dependencies, + } + + if ($::falco::file_output != undef) { + logrotate::rule { 'falco_output': + path => $::falco::file_output[filename], + rotate => 5, + rotate_every => 'day', + size => '1M', + missingok => true, + compress => true, + sharedscripts => true, + postrotate => '/usr/bin/killall -USR1 falco' + } } -} \ No newline at end of file +} diff --git a/integrations/puppet-module/sysdig-falco/manifests/params.pp b/integrations/puppet-module/sysdig-falco/manifests/params.pp new file mode 100644 index 00000000000..58447734d40 --- /dev/null +++ b/integrations/puppet-module/sysdig-falco/manifests/params.pp @@ -0,0 +1,59 @@ +# == Class falco::params +# +class falco::params { + # Configuration parameters + $rules_file = [ + '/etc/falco/falco_rules.yaml', + '/etc/falco/falco_rules.local.yaml', + '/etc/falco/k8s_audit_rules.yaml', + '/etc/falco/rules.d', + ] + + $json_output = false + $json_include_output_property = true + + $log_stderr = true + $log_syslog = true + $log_level = 'info' + $priority = 'debug' + + $buffered_outputs = false + $outputs_rate = 1 + $outputs_max_burst = 1000 + + $syslog_output = { + 'enabled' => true + } + $file_output = { + 'enabled' => false, + 'keep_alive' => false, + 'filename' => '/var/log/falco-events.log' + } + $stdout_output = { + 'enabled' => true + } + $webserver = { + 'enabled' => false, + 'listen_port' => 8765, + 'k8s_audit_endpoint' => '/k8s_audit', + 'ssl_enabled' => false, + 'ssl_certificate' => '/etc/falco/falco.pem' + } + $program_output = { + 'enabled' => false, + 'keep_alive' => false, + 'program' => 'curl http://some-webhook.com' + } + $http_output = { + 'enabled' => false, + 'url' => 'http://some.url' + } + + # Installation parameters + $package_ensure = 'installed' + + # Service parameters + $service_ensure = 'running' + $service_enable = true + $service_restart = true +} diff --git a/integrations/puppet-module/sysdig-falco/manifests/service.pp b/integrations/puppet-module/sysdig-falco/manifests/service.pp index 0d3c21e8d6a..db25722bfd2 100644 --- a/integrations/puppet-module/sysdig-falco/manifests/service.pp +++ b/integrations/puppet-module/sysdig-falco/manifests/service.pp @@ -1,11 +1,24 @@ # == Class: falco::service class falco::service inherits falco { + validate_bool($falco::service_enable) + + case $falco::service_ensure { + true, false, 'running', 'stopped': { + $_service_ensure = $falco::service_ensure + } + default: { + $_service_ensure = undef + } + } service { 'falco': - ensure => running, - enable => true, + ensure => $_service_ensure, + enable => $falco::service_enable, hasstatus => true, - hasrestart => true, - require => Package['falco'], + hasrestart => $falco::service_restart, + require => [ + Class['falco::install'], + Class['falco::config'], + ] } } diff --git a/integrations/puppet-module/sysdig-falco/metadata.json b/integrations/puppet-module/sysdig-falco/metadata.json index b2e7ff53916..719de2de69c 100644 --- a/integrations/puppet-module/sysdig-falco/metadata.json +++ b/integrations/puppet-module/sysdig-falco/metadata.json @@ -1,14 +1,34 @@ { "name": "sysdig-falco", - "version": "0.1.0", + "version": "0.2.0", "author": "sysdig", "summary": "Sysdig Falco: Behavioral Activity Monitoring With Container Support", - "license": "Apache v2.0", - "source": "https://github.com/draios/falco", - "project_page": "https://github.com/draios/falco", - "issues_url": "https://github.com/draios/falco/issues", + "license": "Apache-2.0", + "source": "https://github.com/falcosecurity/falco", + "project_page": "https://github.com/falcosecurity/falco", + "issues_url": "https://github.com/falcosecurity/falco/issues", + "requirements": [ + { + "name": "puppet", + "version_requirement": ">= 4.7.0 < 6.0.0" + } + ], "dependencies": [ - {"name":"puppetlabs-stdlib","version_requirement":">= 1.0.0"} + { + "name": "puppetlabs-apt", + "version_requirement": ">= 4.5.1 < 4.6.0" + }, + { + "name": "stahnma/epel", + "version_requirement": ">= 1.3.1 < 1.4.0" + }, + { + "name": "puppet-logrotate", + "version_requirement": ">= 3.1.0 < 3.2.0" + }, + { + "name": "puppetlabs/stdlib", + "version_requirement": ">= 4.25.1 < 5.0.0" + } ] -} - +} \ No newline at end of file diff --git a/integrations/puppet-module/sysdig-falco/spec/classes/init_spec.rb b/integrations/puppet-module/sysdig-falco/spec/classes/init_spec.rb index 05f94ad120e..baeee4b5c06 100644 --- a/integrations/puppet-module/sysdig-falco/spec/classes/init_spec.rb +++ b/integrations/puppet-module/sysdig-falco/spec/classes/init_spec.rb @@ -1,6 +1,6 @@ require 'spec_helper' -describe 'falco' do +describe 'falco' do context 'with defaults for all parameters' do it { should contain_class('falco') } end diff --git a/integrations/puppet-module/sysdig-falco/templates/falco.yaml.erb b/integrations/puppet-module/sysdig-falco/templates/falco.yaml.erb index 17fbb423e75..e1c085a05ca 100644 --- a/integrations/puppet-module/sysdig-falco/templates/falco.yaml.erb +++ b/integrations/puppet-module/sysdig-falco/templates/falco.yaml.erb @@ -2,7 +2,28 @@ # THIS FILE MANAGED BY PUPPET. DO NOT MODIFY #### -# File(s) containing Falco rules, loaded at startup. +# +# Copyright (C) 2016-2018 Draios Inc dba Sysdig. +# +# This file is part of falco . +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +# 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 @@ -19,6 +40,11 @@ rules_file: # Whether to output events in json or text json_output: <%= @json_output %> +# 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. +json_include_output_property: <%= @json_include_output_property %> + # Send information logs to stderr and/or syslog Note these are *not* security # notification logs! These are just Falco lifecycle (and possibly error) logs. log_stderr: <%= @log_stderr %> @@ -37,7 +63,7 @@ log_level: <%= @log_level %> priority: <%= @priority %> # Whether or not output to any of the output channels below is -# buffered. Defaults to true +# buffered. Defaults to false buffered_outputs: <%= @buffered_outputs %> # A throttling mechanism implemented as a token bucket limits the @@ -58,6 +84,7 @@ outputs: # Where security notifications should go. # Multiple outputs can be enabled. + <% unless @syslog_output.nil? -%> syslog_output: enabled: <%= @syslog_output['enabled'] %> @@ -67,6 +94,10 @@ syslog_output: # 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. +# +# Also, the file will be closed and reopened if falco is signaled with +# SIGUSR1. + <% unless @file_output.nil? -%> file_output: enabled: <%= @file_output['enabled'] %> @@ -74,6 +105,31 @@ file_output: filename: <%= @file_output['filename'] %> <% end -%> +<% unless @stdout_output.nil? -%> +stdout_output: + enabled: <%= @stdout_output['enabled'] %> +<% end -%> + +# Falco contains an embedded webserver that can be used to accept K8s +# Audit Events. These config options control the behavior of that +# webserver. (By default, the webserver is disabled). +# +# The ssl_certificate is a combination SSL Certificate and corresponding +# key contained in a single file. You can generate a key/cert as follows: +# +# $ openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem +# $ cat certificate.pem key.pem > falco.pem +# $ sudo cp falco.pem /etc/falco/falco.pem + +<% unless @webserver.nil? -%> +webserver: + enabled: <%= @webserver['enabled'] %> + listen_port: <%= @webserver['listen_port'] %> + k8s_audit_endpoint: <%= @webserver['k8s_audit_endpoint'] %> + ssl_enabled: <%= @webserver['ssl_enabled'] %> + ssl_certificate: <%= @webserver['ssl_certificate'] %> +<% end -%> + # Possible additional things you might want to do with program output: # - send to a slack webhook: # program: "jq '{text: .output}' | curl -d @- -X POST https://hooks.slack.com/services/XXX" @@ -86,6 +142,9 @@ file_output: # continuously written to, with each output message on its own # line. If keep_alive is set to false, the program will be re-spawned # for each output message. +# +# Also, the program will be closed and reopened if falco is signaled with +# SIGUSR1. <% unless @program_output.nil? -%> program_output: @@ -94,3 +153,8 @@ program_output: program: <%= @program_output['program'] %> <% end -%> +<% unless @http_output.nil? -%> +http_output: + enabled: <%= @http_output['enabled'] %> + url: <%= @http_output['url'] %> +<% end -%>