From ca182a2dc82f727384c38783d137030d0592e895 Mon Sep 17 00:00:00 2001 From: Henri DF Date: Mon, 9 May 2016 12:11:25 -0700 Subject: [PATCH 1/8] Add installation instructions --- README.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 93 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 28295727..5405dacf 100644 --- a/README.md +++ b/README.md @@ -2,18 +2,109 @@ ### *Host Activity Monitoring using Sysdig Event Filtering* ## Overview -Brief description of what, why, how, and pointer to website. +Sysdig Falco is a behavioral activity monitor designed to secure your applications. Powered by Sysdig’s universal system level visibility, write simple and powerful rules, and then output warnings in the format you need. 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. Rules are expressed in a high-level, human-readable language. +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. Rules are expressed in a high-level, human-readable language. For example, you can easily detect things like: +- A shell is run inside a container +- A server process spawns a child process of an unexpected type +- Unexpected read of a sensitive file (like `/etc/passwd`) +- A non-device file is written to `/dev` +- A standard system binary (like `ls`) makes an outbound network connection ## Installing Falco +### Scripted install + +To install Falco automatically in one step, simply run the following command as root or with sudo: + +`curl -s https://s3.amazonaws.com/download.draios.com/stable/install-falco | sudo bash` + +### Package install + +#### RHEL + +- Trust the Draios GPG key, configure the yum repository +``` +rpm --import https://s3.amazonaws.com/download.draios.com/DRAIOS-GPG-KEY.public +curl -s -o /etc/yum.repos.d/draios.repo http://download.draios.com/stable/rpm/draios.repo +``` +- Install the EPEL repository + +Note: The following command is required only if DKMS is not available in the distribution. You can verify if DKMS is available with yum list dkms + +`rpm -i http://mirror.us.leaseweb.net/epel/6/i386/epel-release-6-8.noarch.rpm` + +- Install kernel headers + +Warning: The following command might not work with any kernel. Make sure to customize the name of the package properly + +`yum -y install kernel-devel-$(uname -r)` + +- Install Falco + +`yum -y install falco` + +#### Debian + +- Trust the Draios GPG key, configure the apt repository, and update the package list + +``` +curl -s https://s3.amazonaws.com/download.draios.com/DRAIOS-GPG-KEY.public | apt-key add - +curl -s -o /etc/apt/sources.list.d/draios.list http://download.draios.com/stable/deb/draios.list +apt-get update +``` + +- Install kernel headers + +Warning: The following command might not work with any kernel. Make sure to customize the name of the package properly + +`apt-get -y install linux-headers-$(uname -r)` + +- Install Falco + +`apt-get -y install falco` + + Instructions for installing via .deb, .rpm, or docker. To be filled in pre-release. For now, local compilation and installation is the way to install (see "Building Falco" below). +#### Container install (general) + +If you have full control of your host operating system, then installing Falco using the normal installation method is the recommended best practice. This method allows full visibility into all containers on the host OS. No changes to the standard automatic/manual installation procedures are required. + +However, Falco can also run inside a Docker container. To guarantee a smooth deployment, the kernel headers must be installed in the host operating system, before running Falco. + +This can usually be done on Debian-like distributions with: +`apt-get -y install linux-headers-$(uname -r)` + +Or, on RHEL-like distributions: +`yum -y install kernel-devel-$(uname -r)` + +Falco can then be run with: + +``` +docker pull sysdig/falco +docker run -i -t --name falco --privileged -v /var/run/docker.sock:/host/var/run/docker.sock -v /dev:/host/dev -v /proc:/host/proc:ro -v /boot:/host/boot:ro -v /lib/modules:/host/lib/modules:ro -v /usr:/host/usr:ro sysdig/falco falco +``` + +#### Container install (CoreOS) + +The recommended way to run Falco on CoreOS is inside of its own Docker container using the install commands in the paragraph above. This method allows full visibility into all containers on the host OS. + +This method is automatically updated, includes some nice features such as automatic setup and bash completion, and is a generic approach that can be used on other distributions outside CoreOS as well. + +However, some users may prefer to run Falco in the CoreOS toolbox. While not the recommended method, this can be achieved by installing Falco inside the toolbox using the normal installation method, and then manually running the sysdig-probe-loader script: + +``` +toolbox --bind=/dev --bind=/var/run/docker.sock +curl -s https://s3.amazonaws.com/download.draios.com/stable/install-falco | bash +sysdig-probe-loader +``` + ## Configuring Falco Falco is primarily configured via two files: a configuration file (such as the `falco.yaml` in this repository) and a rules file (such as the `falco_rules.conf` file in `rules/`). These two files are written to `/etc` after you install the Falco package. From ab80b4ce139570eefbf7f2a54d0cb9693473f0b1 Mon Sep 17 00:00:00 2001 From: Henri DF Date: Mon, 9 May 2016 17:51:23 -0700 Subject: [PATCH 2/8] Move installation instructions down --- README.md | 87 +++++++++++++++++++++++++++---------------------------- 1 file changed, 43 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 5405dacf..cf9d861f 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,48 @@ Falco can detect and alert on any behavior that involves making Linux system cal - A standard system binary (like `ls`) makes an outbound network connection -## Installing Falco +## Configuring Falco + +Falco is primarily configured via two files: a configuration file (such as the `falco.yaml` in this repository) and a rules file (such as the `falco_rules.conf` file in `rules/`). These two files are written to `/etc` after you install the Falco package. + +### Rules file + +The rules file is where you define the events and actions that you want to be notified on. We've provided a sample rule file `./rules/falco_rules.conf` as a starting point, but you'll want to familiarize yourself with the contents, and most likely, to adapt it to your environment. + +_Call for contributions: If you come up with additional rules which you think should be part of this core set - PR welcome! And likewise if you have an entirely separate ruleset that may not belong in the core rule set._ + +A Falco rules file is comprised of two kinds of elements: rules and macro definitions. + +Here's an example of a rule that alerts whenever a bash shell is run inside a container: + +`container.id != host and proc.name = bash | WARNING Bash run in a container (%user.name %proc.name %evt.dir %evt.type %evt.args %fd.name)` + +The part to the left of the pipe (`|`) is the _condition_. It is expressed using the Sysdig [filter syntax](http://www.sysdig.org/wiki/sysdig-user-guide/#filtering). Any Sysdig filter expression is a valid Falco expression (with the caveat of certain excluded system calls, discussed below). In addition, Falco expressions can contain _macro_ terms, which are not present in Sysdig syntax. + +The part to the right of the pipe is the _output_. It is composed of a priority level and an output format. The priority level is case-insensitive and should be one of "emergency", "alert", "critical", "error", "warning", "notice", "informational", or "debug". The output format specifies the message that should be output if a matching event occurs, and follows the Sysdig [output format syntax](http://www.sysdig.org/wiki/sysdig-user-guide/#output-formatting). + +Macro definitions provide a way to define common sub-portions of rules in a reusable way. The syntax for a macro is: + +`macro_name: macro_definition` + +where `macro_name` is a string, and `macro_definition` is any valid Falco condition. + +(_insert example here_). + + +#### Ignored system calls + +For performance reasons, some system calls are currently discarded before Falco processing. The current list is: +`clock_getres,clock_gettime,clock_nanosleep,clock_settime,close,epoll_create,epoll_create1,epoll_ctl,epoll_pwait,epoll_wait,eventfd,fcntl,fcntl64,fstat,fstat64,getitimer,gettimeofday,nanosleep,poll,ppoll,pread64,preadv,pselect6,pwrite64,pwritev,read,readv,recv,recvfrom,recvmmsg,recvmsg,select,send,sendfile,sendfile64,sendmmsg,sendmsg,sendto,setitimer,settimeofday,shutdown,socket,splice,switch,tee,timer_create,timer_delete,timerfd_create,timerfd_gettime,timerfd_settime,timer_getoverrun,timer_gettime,timer_settime,wait4,write,writev,` + + + + +### Configuration file +Falco is configured via a yaml file. The sample config `falco.yaml` in this repo has comments describing the various options. + + +## Installation ### Scripted install To install Falco automatically in one step, simply run the following command as root or with sudo: @@ -26,7 +67,7 @@ To install Falco automatically in one step, simply run the following command as #### RHEL -- Trust the Draios GPG key, configure the yum repository +- Trust the Draios GPG key and configure the yum repository ``` rpm --import https://s3.amazonaws.com/download.draios.com/DRAIOS-GPG-KEY.public curl -s -o /etc/yum.repos.d/draios.repo http://download.draios.com/stable/rpm/draios.repo @@ -105,48 +146,6 @@ curl -s https://s3.amazonaws.com/download.draios.com/stable/install-falco | bash sysdig-probe-loader ``` -## Configuring Falco - -Falco is primarily configured via two files: a configuration file (such as the `falco.yaml` in this repository) and a rules file (such as the `falco_rules.conf` file in `rules/`). These two files are written to `/etc` after you install the Falco package. - -### Rules file - -The rules file is where you define the events and actions that you want to be notified on. We've provided a sample rule file `./rules/falco_rules.conf` as a starting point, but you'll want to familiarize yourself with the contents, and most likely, to adapt it to your environment. - -_Call for contributions: If you come up with additional rules which you think should be part of this core set - PR welcome! And likewise if you have an entirely separate ruleset that may not belong in the core rule set._ - -A Falco rules file is comprised of two kinds of elements: rules and macro definitions. - -Here's an example of a rule that alerts whenever a bash shell is run inside a container: - -`container.id != host and proc.name = bash | WARNING Bash run in a container (%user.name %proc.name %evt.dir %evt.type %evt.args %fd.name)` - -The part to the left of the pipe (`|`) is the _condition_. It is expressed using the Sysdig [filter syntax](http://www.sysdig.org/wiki/sysdig-user-guide/#filtering). Any Sysdig filter expression is a valid Falco expression (with the caveat of certain excluded system calls, discussed below). In addition, Falco expressions can contain _macro_ terms, which are not present in Sysdig syntax. - -The part to the right of the pipe is the _output_. It is composed of a priority level and an output format. The priority level is case-insensitive and should be one of "emergency", "alert", "critical", "error", "warning", "notice", "informational", or "debug". The output format specifies the message that should be output if a matching event occurs, and follows the Sysdig [output format syntax](http://www.sysdig.org/wiki/sysdig-user-guide/#output-formatting). - -Macro definitions provide a way to define common sub-portions of rules in a reusable way. The syntax for a macro is: - -`macro_name: macro_definition` - -where `macro_name` is a string, and `macro_definition` is any valid Falco condition. - -(_insert example here_). - - - -#### Ignored system calls - -For performance reasons, some system calls are currently discarded before Falco processing. The current list is: -`clock_getres,clock_gettime,clock_nanosleep,clock_settime,close,epoll_create,epoll_create1,epoll_ctl,epoll_pwait,epoll_wait,eventfd,fcntl,fcntl64,fstat,fstat64,getitimer,gettimeofday,nanosleep,poll,ppoll,pread64,preadv,pselect6,pwrite64,pwritev,read,readv,recv,recvfrom,recvmmsg,recvmsg,select,send,sendfile,sendfile64,sendmmsg,sendmsg,sendto,setitimer,settimeofday,shutdown,socket,splice,switch,tee,timer_create,timer_delete,timerfd_create,timerfd_gettime,timerfd_settime,timer_getoverrun,timer_gettime,timer_settime,wait4,write,writev,` - - - - -### Configuration file -Falco is configured via a yaml file. The sample config `falco.yaml` in this repo has comments describing the various options. - - ## Running Falco Falco is intended to be run as a service. But for experimentation and designing/testing rulesets, you will likely want to run it manually from the command-line. From 9d306e5a1c146ee3ba17bbdbdeca0e0a63ad9243 Mon Sep 17 00:00:00 2001 From: Henri DF Date: Mon, 9 May 2016 18:04:25 -0700 Subject: [PATCH 3/8] Add ToC and move things around --- README.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index cf9d861f..cdafe9a8 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,15 @@ # Sysdig Falco ### *Host Activity Monitoring using Sysdig Event Filtering* +**Table of Contents** + +- [Overview](#overview) +- [Rules](#rules) +- [Configuration](#configuration) +- [Installation](#installation) +- [Running Falco](#running-falco) + + ## Overview Sysdig Falco is a behavioral activity monitor designed to secure your applications. Powered by Sysdig’s universal system level visibility, write simple and powerful rules, and then output warnings in the format you need. Continuously monitor and detect container, application, host, and network activity... all in one place, from one source of data, with one set of rules. @@ -14,12 +23,10 @@ Falco can detect and alert on any behavior that involves making Linux system cal - A non-device file is written to `/dev` - A standard system binary (like `ls`) makes an outbound network connection - -## Configuring Falco +## Rules Falco is primarily configured via two files: a configuration file (such as the `falco.yaml` in this repository) and a rules file (such as the `falco_rules.conf` file in `rules/`). These two files are written to `/etc` after you install the Falco package. -### Rules file The rules file is where you define the events and actions that you want to be notified on. We've provided a sample rule file `./rules/falco_rules.conf` as a starting point, but you'll want to familiarize yourself with the contents, and most likely, to adapt it to your environment. @@ -50,9 +57,7 @@ For performance reasons, some system calls are currently discarded before Falco `clock_getres,clock_gettime,clock_nanosleep,clock_settime,close,epoll_create,epoll_create1,epoll_ctl,epoll_pwait,epoll_wait,eventfd,fcntl,fcntl64,fstat,fstat64,getitimer,gettimeofday,nanosleep,poll,ppoll,pread64,preadv,pselect6,pwrite64,pwritev,read,readv,recv,recvfrom,recvmmsg,recvmsg,select,send,sendfile,sendfile64,sendmmsg,sendmsg,sendto,setitimer,settimeofday,shutdown,socket,splice,switch,tee,timer_create,timer_delete,timerfd_create,timerfd_gettime,timerfd_settime,timer_getoverrun,timer_gettime,timer_settime,wait4,write,writev,` - - -### Configuration file +## Configuration Falco is configured via a yaml file. The sample config `falco.yaml` in this repo has comments describing the various options. From bcc7521e4e262aac43006d702f8da869125026f6 Mon Sep 17 00:00:00 2001 From: Henri DF Date: Mon, 9 May 2016 20:47:46 -0700 Subject: [PATCH 4/8] Add "how you use it" section Quick & simple outline to make things concrete upfront. --- README.md | 35 ++++++++++++++++++++++++++++------- 1 file changed, 28 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index cdafe9a8..946cb200 100644 --- a/README.md +++ b/README.md @@ -16,23 +16,44 @@ Sysdig Falco is a behavioral activity monitor designed to secure your applicatio ### 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. Rules are expressed in a high-level, human-readable language. 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 server process spawns a child process of an unexpected type - Unexpected read of a sensitive file (like `/etc/passwd`) - A non-device file is written to `/dev` - A standard system binary (like `ls`) makes an outbound network connection +### How you use it + +Falco is deployed as a long-running daemon. You can install it as a debian/rpm +package on a regular host or container host, or you can deploy it as a +container. + +Falco is configured via a rules file defining the behaviors and events to +watch for, and a general configuration file. Rules are expressed in a +high-level, human-readable language. We've provided a sample rule file +`./rules/falco_rules.conf` as a starting point - you can (and will likely +want!) to adapt it to your environment. + +When developing rules, one helpful feature is Falco's ability to read trace +files saved by sysdig. This allows you to "record" the offending behavior +once, and replay it with Falco as many times as needed while tweaking your +rules. + +Once deployed, Falco uses the Sysdig kernel module and userspace libraries to +watch for any events matching one of the conditions defined in the rule +file. If a matching event occurs, a notification is written to the the +configured output(s). + + ## Rules -Falco is primarily configured via two files: a configuration file (such as the `falco.yaml` in this repository) and a rules file (such as the `falco_rules.conf` file in `rules/`). These two files are written to `/etc` after you install the Falco package. - - -The rules file is where you define the events and actions that you want to be notified on. We've provided a sample rule file `./rules/falco_rules.conf` as a starting point, but you'll want to familiarize yourself with the contents, and most likely, to adapt it to your environment. +The rules file is where you define the events and actions that you want to be +notified on. _Call for contributions: If you come up with additional rules which you think should be part of this core set - PR welcome! And likewise if you have an entirely separate ruleset that may not belong in the core rule set._ -A Falco rules file is comprised of two kinds of elements: rules and macro definitions. +A Falco rules file is comprised of two kinds of elements: rules and macro definitions. Here's an example of a rule that alerts whenever a bash shell is run inside a container: @@ -46,7 +67,7 @@ Macro definitions provide a way to define common sub-portions of rules in a reus `macro_name: macro_definition` -where `macro_name` is a string, and `macro_definition` is any valid Falco condition. +where `macro_name` is a string, and `macro_definition` is any valid Falco condition. (_insert example here_). From cd82f6935d804e4727a7180df2337036ec41b275 Mon Sep 17 00:00:00 2001 From: Henri DF Date: Mon, 9 May 2016 21:10:30 -0700 Subject: [PATCH 5/8] Adjust heading levels --- README.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 946cb200..7c989e7b 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Sysdig Falco is a behavioral activity monitor designed to secure your applications. Powered by Sysdig’s universal system level visibility, write simple and powerful rules, and then output warnings in the format you need. 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? +#### 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 @@ -23,7 +23,7 @@ Falco can detect and alert on any behavior that involves making Linux system cal - A non-device file is written to `/dev` - A standard system binary (like `ls`) makes an outbound network connection -### How you use it +#### How you use it Falco is deployed as a long-running daemon. You can install it as a debian/rpm package on a regular host or container host, or you can deploy it as a @@ -83,15 +83,15 @@ Falco is configured via a yaml file. The sample config `falco.yaml` in this repo ## Installation -### Scripted install +#### Scripted install To install Falco automatically in one step, simply run the following command as root or with sudo: `curl -s https://s3.amazonaws.com/download.draios.com/stable/install-falco | sudo bash` -### Package install +#### Package install -#### RHEL +##### RHEL - Trust the Draios GPG key and configure the yum repository ``` @@ -114,7 +114,7 @@ Warning: The following command might not work with any kernel. Make sure to cust `yum -y install falco` -#### Debian +##### Debian - Trust the Draios GPG key, configure the apt repository, and update the package list @@ -139,7 +139,7 @@ Instructions for installing via .deb, .rpm, or docker. To be filled in pre-relea For now, local compilation and installation is the way to install (see "Building Falco" below). -#### Container install (general) +##### Container install (general) If you have full control of your host operating system, then installing Falco using the normal installation method is the recommended best practice. This method allows full visibility into all containers on the host OS. No changes to the standard automatic/manual installation procedures are required. @@ -158,7 +158,7 @@ docker pull sysdig/falco docker run -i -t --name falco --privileged -v /var/run/docker.sock:/host/var/run/docker.sock -v /dev:/host/dev -v /proc:/host/proc:ro -v /boot:/host/boot:ro -v /lib/modules:/host/lib/modules:ro -v /usr:/host/usr:ro sysdig/falco falco ``` -#### Container install (CoreOS) +##### Container install (CoreOS) The recommended way to run Falco on CoreOS is inside of its own Docker container using the install commands in the paragraph above. This method allows full visibility into all containers on the host OS. @@ -176,10 +176,10 @@ sysdig-probe-loader Falco is intended to be run as a service. But for experimentation and designing/testing rulesets, you will likely want to run it manually from the command-line. -### Running Falco as a service +#### Running Falco as a service Instructions for Centos and Ubuntu. -### Running Falco manually +#### Running Falco manually `falco --help` @@ -189,7 +189,7 @@ Instructions for Centos and Ubuntu. Building Falco requires having `cmake` and `g++` installed. -### Building Falco +#### Building Falco Clone this repo in a directory that also contains the sysdig source repo. The result should be something like: ``` @@ -214,7 +214,7 @@ $ make as a result, you should have a falco executable in `build/userspace/falco/falco`. -### Load latest sysdig kernel module +#### Load latest sysdig kernel module If you have a binary version of sysdig installed, an older sysdig kernel module may already be loaded. To ensure you are using the latest version, you should unload any existing sysdig kernel module and load the locally built version. @@ -226,7 +226,7 @@ To load the locally built version, assuming you are in the `build` dir, use: `$ insmod driver/sysdig-probe.ko` -### Running Falco +#### Running Falco Assuming you are in the `build` dir, you can run Falco as: From 1c3ae275d7a3fcb12db329c6aabeb98a852a079e Mon Sep 17 00:00:00 2001 From: Henri DF Date: Mon, 9 May 2016 22:09:57 -0700 Subject: [PATCH 6/8] Rewrite "rules" section --- README.md | 44 +++++++++++++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 7c989e7b..101dba0d 100644 --- a/README.md +++ b/README.md @@ -48,34 +48,52 @@ configured output(s). ## Rules -The rules file is where you define the events and actions that you want to be -notified on. +_Call for contributions: If you come up with additional rules which you'd like to see in the core repository - PR welcome!_ -_Call for contributions: If you come up with additional rules which you think should be part of this core set - PR welcome! And likewise if you have an entirely separate ruleset that may not belong in the core rule set._ +A Falco rules file is comprised of two kinds of elements: rules and macro definitions. Macros are simply definitions that can be re-used inside rules and other macros, providing a way to factor out and name common patterns. -A Falco rules file is comprised of two kinds of elements: rules and macro definitions. +#### Conditions -Here's an example of a rule that alerts whenever a bash shell is run inside a container: +The key part of a rule is the _condition_ field. A condition is simply a boolean predicate on sysdig events. +Conditions are expressed using the Sysdig [filter syntax](http://www.sysdig.org/wiki/sysdig-user-guide/#filtering). Any Sysdig filter is a valid Falco condition (with the caveat of certain excluded system calls, discussed below). In addition, Falco expressions can contain _macro_ terms, which are not present in Sysdig syntax. -`container.id != host and proc.name = bash | WARNING Bash run in a container (%user.name %proc.name %evt.dir %evt.type %evt.args %fd.name)` +Here's an example of a condition that alerts whenever a bash shell is run inside a container: -The part to the left of the pipe (`|`) is the _condition_. It is expressed using the Sysdig [filter syntax](http://www.sysdig.org/wiki/sysdig-user-guide/#filtering). Any Sysdig filter expression is a valid Falco expression (with the caveat of certain excluded system calls, discussed below). In addition, Falco expressions can contain _macro_ terms, which are not present in Sysdig syntax. +`container.id != host and proc.name = bash` -The part to the right of the pipe is the _output_. It is composed of a priority level and an output format. The priority level is case-insensitive and should be one of "emergency", "alert", "critical", "error", "warning", "notice", "informational", or "debug". The output format specifies the message that should be output if a matching event occurs, and follows the Sysdig [output format syntax](http://www.sysdig.org/wiki/sysdig-user-guide/#output-formatting). +The first clause checks that the event happened in a container (sysdig events have a `container` field that is equal to "host" if the event happened on a regular host). The second clause checks that the process name is `bash`. Note that this condition does not even include a clause with system call! It only uses event metadata. As such, if a bash shell does start up in a container, Falco will output events for every syscall that is done by that shell. -Macro definitions provide a way to define common sub-portions of rules in a reusable way. The syntax for a macro is: +_Tip: If you're new to sysdig and unsure what fields are available, run `sysdig -l` to see the list of supported fields._ -`macro_name: macro_definition` +#### Rules -where `macro_name` is a string, and `macro_definition` is any valid Falco condition. +Along with a condition, each rule includes an _output_ and a _priority_. The output format specifies the message that should be output if a matching event occurs, and follows the Sysdig [output format syntax](http://www.sysdig.org/wiki/sysdig-user-guide/#output-formatting). The priority is a case-insensitive representation of severity and should be one of "emergency", "alert", "critical", "error", "warning", "notice", "informational", or "debug". -(_insert example here_). +A complete rule using the above condition might be: + +```yaml +- condition: container.id != host and proc.name = bash + output: "shell in a container (%user.name %container.id %proc.name %evt.dir %evt.type %evt.args %fd.name)" + priority: WARNING +``` + +#### Macros +As noted above, macros provide a way to define common sub-portions of rules in a reusable way. As a very simple example, if we had many rules for events happening in containers, we might to define a `in_container` macro: + +```yaml +- macro: in_container + condition: container.id != host +``` + +With this macro defined, we can then rewrite the above rule's condition as `in_container and proc.name = bash`. + +For many more examples of rules and macros, please take a look at the accompanying [rules file](rules/falco_rules.yaml). #### Ignored system calls For performance reasons, some system calls are currently discarded before Falco processing. The current list is: -`clock_getres,clock_gettime,clock_nanosleep,clock_settime,close,epoll_create,epoll_create1,epoll_ctl,epoll_pwait,epoll_wait,eventfd,fcntl,fcntl64,fstat,fstat64,getitimer,gettimeofday,nanosleep,poll,ppoll,pread64,preadv,pselect6,pwrite64,pwritev,read,readv,recv,recvfrom,recvmmsg,recvmsg,select,send,sendfile,sendfile64,sendmmsg,sendmsg,sendto,setitimer,settimeofday,shutdown,socket,splice,switch,tee,timer_create,timer_delete,timerfd_create,timerfd_gettime,timerfd_settime,timer_getoverrun,timer_gettime,timer_settime,wait4,write,writev,` +`clock_getres,clock_gettime,clock_nanosleep,clock_settime,close,epoll_create,epoll_create1,epoll_ctl,epoll_pwait,epoll_wait,eventfd,fcntl,fcntl64,fstat,fstat64,getitimer,gettimeofday,nanosleep,poll,ppoll,pread64,preadv,pselect6,pwrite64,pwritev,read,readv,recv,recvfrom,recvmmsg,recvmsg,select,send,sendfile,sendfile64,sendmmsg,sendmsg,sendto,setitimer,settimeofday,shutdown,socket,splice,switch,tee,timer_create,timer_delete,timerfd_create,timerfd_gettime,timerfd_settime,timer_getoverrun,timer_gettime,timer_settime,wait4,write,writev` ## Configuration From 4e525e3114423a32781d2fa0c564d40f2f6a57ff Mon Sep 17 00:00:00 2001 From: Henri DF Date: Tue, 10 May 2016 13:27:05 -0700 Subject: [PATCH 7/8] Document general configuration --- README.md | 7 +++++-- falco.yaml | 11 ++++++++++- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 101dba0d..4af0c7d6 100644 --- a/README.md +++ b/README.md @@ -92,12 +92,15 @@ For many more examples of rules and macros, please take a look at the accompanyi #### Ignored system calls -For performance reasons, some system calls are currently discarded before Falco processing. The current list is: +For performance reasons, some system calls are currently discarded before Falco processing. The current list is: `clock_getres,clock_gettime,clock_nanosleep,clock_settime,close,epoll_create,epoll_create1,epoll_ctl,epoll_pwait,epoll_wait,eventfd,fcntl,fcntl64,fstat,fstat64,getitimer,gettimeofday,nanosleep,poll,ppoll,pread64,preadv,pselect6,pwrite64,pwritev,read,readv,recv,recvfrom,recvmmsg,recvmsg,select,send,sendfile,sendfile64,sendmmsg,sendmsg,sendto,setitimer,settimeofday,shutdown,socket,splice,switch,tee,timer_create,timer_delete,timerfd_create,timerfd_gettime,timerfd_settime,timer_getoverrun,timer_gettime,timer_settime,wait4,write,writev` ## Configuration -Falco is configured via a yaml file. The sample config `falco.yaml` in this repo has comments describing the various options. + +General configuration is done via a separate yaml file. The +[config file](falco.yaml) in this repo has comments describing the various +configuration options. ## Installation diff --git a/falco.yaml b/falco.yaml index 719e4598..41a4de53 100644 --- a/falco.yaml +++ b/falco.yaml @@ -1,9 +1,18 @@ -rules_file: /etc/falco_rules.yaml +# File containing Falco rules, loaded at startup. +rules_file: /etc/falco_rules.conf + +# Whether to output events in json or text json_output: false +# 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: false log_syslog: true + +# Where security notifications should go. +# Multiple outputs can be enabled. + syslog_output: enabled: true From 492148d880da0ea17fb0d3d9d013004934697aaa Mon Sep 17 00:00:00 2001 From: Henri DF Date: Tue, 10 May 2016 13:47:30 -0700 Subject: [PATCH 8/8] Running instructions --- README.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 4af0c7d6..eb4ecf30 100644 --- a/README.md +++ b/README.md @@ -155,7 +155,6 @@ Warning: The following command might not work with any kernel. Make sure to cust `apt-get -y install falco` - Instructions for installing via .deb, .rpm, or docker. To be filled in pre-release. For now, local compilation and installation is the way to install (see "Building Falco" below). @@ -197,13 +196,17 @@ sysdig-probe-loader Falco is intended to be run as a service. But for experimentation and designing/testing rulesets, you will likely want to run it manually from the command-line. -#### Running Falco as a service -Instructions for Centos and Ubuntu. +#### Running Falco as a service (after installing package) + +`service falco start` + +#### Running Falco in a container + +`docker run -i -t --name falco --privileged -v /var/run/docker.sock:/host/var/run/docker.sock -v /dev:/host/dev -v /proc:/host/proc:ro -v /boot:/host/boot:ro -v /lib/modules:/host/lib/modules:ro -v /usr:/host/usr:ro sysdig/falco falco` #### Running Falco manually -`falco --help` - +Do `falco --help` to see the command-line options available when running manually. ## Building and running Falco locally from source