diff --git a/README.md b/README.md index 807e6afb..e582da56 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,17 @@ # Sysdig Falco -### *Host Activity Monitoring using Sysdig Event Filtering* -**Table of Contents** +####Latest release + +**v0.1.0** +Read the [change log](https://github.com/draios/falco/blob/dev/CHANGELOG.md) + +This is the initial falco release. Note that much of falco's code comes from +[sysdig](https://github.com/draios/sysdig), so overall stability is very good +for an early release. On the other hand performance is still a work in +progress. On busy hosts and/or with large rule sets, you may see the current +version of falco using high CPU. Expect big improvements in coming releases. + +####Table of Contents - [Overview](#overview) - [Rules](#rules) @@ -16,7 +26,7 @@ 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. 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`) @@ -35,12 +45,12 @@ high-level, human-readable language. We've provided a sample rule file `./rules/falco_rules.yaml` 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 +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 +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 +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). @@ -50,18 +60,18 @@ configured output(s). _Call for contributions: If you come up with additional rules which you'd like to see in the core repository - PR welcome!_ -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. Macros are simply definitions that can be re-used inside rules and other macros, providing a way to factor out and name common patterns. #### Conditions 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. +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. Here's an example of a condition that alerts whenever a bash shell is run inside a container: `container.id != host and proc.name = bash` -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. +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. _Tip: If you're new to sysdig and unsure what fields are available, run `sysdig -l` to see the list of supported fields._ @@ -96,7 +106,7 @@ 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,fstatat64,fstatfs,fstatfs64,futex,getitimer,gettimeofday,ioprio_get,ioprio_set,llseek,lseek,lstat,lstat64,mmap,mmap2,munmap,nanosleep,poll,ppoll,pread64,preadv,procinfo,pselect6,pwrite64,pwritev,read,readv,recv,recvfrom,recvmmsg,recvmsg,sched_yield,select,send,sendfile,sendfile64,sendmmsg,sendmsg,sendto,setitimer,settimeofday,shutdown,splice,stat,stat64,statfs,statfs64,switch,tee,timer_create,timer_delete,timerfd_create,timerfd_gettime,timerfd_settime,timer_getoverrun,timer_gettime,timer_settime,wait4,write,writev` @@ -110,7 +120,7 @@ configuration options. ## Installation #### Scripted install -To install Falco automatically in one step, simply run the following command as root or with sudo: +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` @@ -135,7 +145,7 @@ Warning: The following command might not work with any kernel. Make sure to cust `yum -y install kernel-devel-$(uname -r)` -- Install Falco +- Install falco `yum -y install falco` @@ -158,7 +168,7 @@ Warning: The following command might not work with any kernel. Make sure to cust `apt-get -y install linux-headers-$(uname -r)` -- Install Falco +- Install falco `apt-get -y install falco` @@ -167,9 +177,9 @@ To uninstall, just do `apt-get remove falco`. ##### 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. +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. +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)` @@ -186,11 +196,11 @@ docker run -i -t --name falco --privileged -v /var/run/docker.sock:/host/var/run ##### 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. +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: +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 @@ -204,24 +214,24 @@ 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 (after installing package) +#### Running falco as a service (after installing package) `service falco start` -#### Running Falco in a container +#### 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` -#### Running Falco manually +#### Running falco manually Do `falco --help` to see the command-line options available when running manually. -## Building and running Falco locally from source -Building Falco requires having `cmake` and `g++` installed. +## Building and running falco locally from source +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: ``` @@ -258,9 +268,9 @@ 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: +Assuming you are in the `build` dir, you can run falco as: `$ sudo ./userspace/falco/falco -c ../falco.yaml -r ../rules/falco_rules.yaml`