github/falco
1
0
Fork 0
mirror of https://github.com/falcosecurity/falco.git synced 2025-09-02 15:15:17 +00:00
Code Issues Projects Releases Wiki Activity

Filling in initial rev of wiki. 

Most of the content comes from the README.md. A separate commit to the
falco repo will remove the redundant content.
Mark Stemm
2016-06-07 11:32:12 -07:00
parent 3d481c6bab
commit 597d579c8b
12 changed files with 508 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored Normal file

@@ -0,0 +1 @@
*~

49
About-Falco.md Normal file

@@ -0,0 +1,49 @@
# About Falco
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 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
## 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.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
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).
## Falco Alerts
When Falco detects suspicious behavior, it sends alerts via one or more of the following channels:
* Writing to standard error
* Writing to a file
* Writing to syslog
More details on these alerts are described [here](Falco Alerts).

7
Configuration.md Normal file

@@ -0,0 +1,7 @@
## Configuration
General configuration is done via a separate yaml file. The
[config file](falco.yaml) in this repo has comments describing the various
configuration options.

64
Falco-Alerts.md Normal file

@@ -0,0 +1,64 @@
# Falco Alerts
Falco can send alerts to one or more channels:
* Standard Output
* A file
* Syslog
The channels are configured via the falco configuration file `falco.yaml`. See the [Falco Configuration](Falco Configuration) page for more details. Here are details on each of those channels.
## Standard Output
When configured to send alerts via standard output, a line is printed for each alert. Here's an example:
```
10:20:05.408091526: Warning Sensitive file opened for reading by non-trusted program (user=root command=cat /etc/shadow file=/etc/shadow)
```
When run in the background via the `-d/--daemon` command line option, standard output output is discarded.
## File Output
When configured to send alerts to a file, a message is written to the file for each alert. The format is identical to the Standard Output format.
For each alert, the file is opened for appending, the single alert is written, and the file is closed. The file is not rotated or truncated.
## Syslog Output
When configured to send alerts to syslog, a syslog message is sent for each alert. The actual format depends on your syslog daemon, but here's an example:
```
Jun 7 10:20:05 ubuntu falco: Sensitive file opened for reading by non-trusted program (user=root command=cat /etc/shadow file=/etc/shadow)
```
Syslog messages are sent with a facility of LOG_USER. The rule's priority is used as the priority of the syslog message.
## JSON Output
For all output channels, you can switch to JSON output either in the configuration file or on the command line. For each alert, falco will print a JSON object, on a single line, containing the following properties:
* `time`: the time of the alert, in ISO8601 format.
* `rule`: the rule that resulted in the alert.
* `priority`: the priority of the rule that generated the alert.
* `output`: the formatted output string for the alert.
Here's an example:
```
{"output":"16:47:44.080226697: Warning Sensitive file opened for reading by non-trusted program (user=root command=cat /etc/shadow file=/etc/shadow)","priority":"Warning","rule":"read_sensitive_file_untrusted","time":"2016-06-06T23:47:44.080226697Z"}
```
Here's the same output, pretty-printed:
```
{
"output": "16:47:44.080226697: Warning Sensitive file opened for reading by non-trusted program (user=root command=cat /etc/shadow file=/etc/shadow)",
"priority": "Warning",
"rule": "read_sensitive_file_untrusted",
"time": "2016-06-06T23:47:44.080226697Z"
}
```

21
Falco-Configuration.md Normal file

@@ -0,0 +1,21 @@
# Falco Configuration
Falco's configuration file is a [YAML](http://www.yaml.org/start.html)
file containing a collection of `key: value` or `key: [value list]` pairs.
Any configuration option can be overridden on the command line via the `-o/--option key=value` flag. For `key: [value list]` options, you can specify individual list items using ``--option key.subkey=value``.
The current configuration keys are:
* `rules_file: <path>`: the location of the rules file. This can also be overridden on the command line via `-r`.
* `json_output: [true|false]`: whether to use JSON output for alert messages.
* `log_stderr: [true|false]`: if true, log messages describing falco's activity will be logged to stderr. Note these are *not* alert messages--these are log messages for falco itself.
* `log_syslog: [true|false]`: if true, log messages describing falco's activity will be logged to syslog.
* `syslog_output`: a list containing these sub-keys:
** `enabled: [true|false]`: if true, falco alerts will be sent via syslog
* `file_output`: a list containing these sub-keys:
** `enabled: [true|false]`: if true, falco alerts will be sent to the specified file
** `filename: <path>`: the location of the file to which alerts will be sent
* `stdout_output`: a list containing thse sub-keys:
** `enabled: [true|false]`: if true, falco alerts will be sent to standard output

92
Falco-Examples.md Normal file

@@ -0,0 +1,92 @@
# Falco Examples
Here are some examples of the types of behavior falco can detect.
For a more comprehnsive set of examples, see the full rules file at `falco_rules.yaml`
##A shell is run in a container
```yaml
- macro: container
condition: container.id != host
- macro: spawned_process
condition: evt.type = execve and evt.dir=<
- rule: run_shell_in_container
desc: a shell was spawned by a non-shell program in a container. Container entrypoints are excluded.
condition: container and proc.name = bash and spawned_process and proc.pname exists and not proc.pname in (bash, docker)
output: "Shell spawned in a container other than entrypoint (user=%user.name container_id=%container.id container_name=%container.name shell=%proc.name parent=%proc.pname cmdline=%proc.cmdline)"
priority: WARNING
```
##Unexpected outbound Elasticsearch connection
```yaml
- macro: outbound
condition: syscall.type=connect and evt.dir=< and (fd.typechar=4 or fd.typechar=6)
- macro: elasticsearch_cluster_port
condition: fd.sport=9300
- rule: elasticsearch_unexpected_network_outbound
desc: outbound network traffic from elasticsearch on a port other than the standard ports
condition: user.name = elasticsearch and outbound and not elasticsearch_cluster_port
output: "Outbound network traffic from Elasticsearch on unexpected port (connection=%fd.name)"
priority: WARNING
```
##Write to directory holding system binaries
```yaml
- macro: open_write
condition: >
(evt.type=open or evt.type=openat) and
fd.typechar='f' and
(evt.arg.flags contains O_WRONLY or
evt.arg.flags contains O_RDWR or
evt.arg.flags contains O_CREAT or
evt.arg.flags contains O_TRUNC)
- macro: package_mgmt_binaries
condition: proc.name in (dpkg, dpkg-preconfigu, rpm, rpmkey, yum)
- macro: bin_dir
condition: fd.directory in (/bin, /sbin, /usr/bin, /usr/sbin)
- rule: write_binary_dir
desc: an attempt to write to any file below a set of binary directories
condition: evt.dir = < and open_write and not package_mgmt_binaries and bin_dir
output: "File below a known binary directory opened for writing (user=%user.name command=%proc.cmdline file=%fd.name)"
priority: WARNING
```
##Non-authorized container namespace change
```yaml
- rule: change_thread_namespace
desc: an attempt to change a program/thread\'s namespace (commonly done as a part of creating a container) by calling setns.
condition: syscall.type = setns and not proc.name in (docker, sysdig, dragent)
output: "Namespace change (setns) by unexpected program (user=%user.name command=%proc.cmdline container=%container.id)"
priority: WARNING
```
##Non-device files written in /dev (some rootkits do this)
```yaml
- rule: create_files_below_dev
desc: creating any files below /dev other than known programs that manage devices. Some rootkits hide files in /dev.
condition: (evt.type = creat or evt.arg.flags contains O_CREAT) and proc.name != blkid and fd.directory = /dev and fd.name != /dev/null
output: "File created below /dev by untrusted program (user=%user.name command=%proc.cmdline file=%fd.name)"
priority: WARNING
```
##Process other than skype/webex tries to access camera
```yaml
- rule: access_camera
desc: a process other than skype/webex tries to access the camera
condition: evt.type = open and fd.name = /dev/video0 and not proc.name in (skype, webex)
output: Unexpected process opening camera video device (command=%proc.cmdline)
priority: WARNING
```

58
Falco-Rules.md Normal file

@@ -0,0 +1,58 @@
# Rules
_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 a [YAML](http://www.yaml.org/start.html) file containing two kinds of elements: *rules* and *macros*. Rules consiste of a *condition* under which an alert should be generated and a *output string* to send with the alert.
Macros are simply rule condition snippets that can be re-used inside rules and other macros, providing a way to factor out and name common patterns.
## Rules
A Rule is a node containing the following keys:
* _rule_: a short unique name for the rule
* _desc_: a longer description of what the rule detects
* _output_ and _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".
## 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 conditions can contain macro terms--this capability is 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.
_Tip: If you're new to sysdig and unsure what fields are available, run `sysdig -l` to see the list of supported fields._
A complete rule using the above condition might be:
```yaml
- rule: shell_in_container
desc: notice shell activity within a container
condition: container.id != host and proc.name = bash
output: "shell in a container (user=%user.name container_id=%container.id container_name=%container.name shell=%proc.name parent=%proc.pname cmdline=%proc.cmdline)
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 `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,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`

36
Home.md

@@ -1 +1,35 @@
No wiki yet. Please see the [Readme](https://github.com/draios/falco) on the GitHub project page. #Welcome to the **falco** wiki!
On this wiki, you can find information about sysdig falco. If this is your first time hearing about falco, we recommend you [start with the website](http://www.sysdig.org/falco).
####Overview
* [About Falco](About Falco) - What falco is and what it can do.
####Setup
* [Install Falco (Linux)](How to Install Falco for Linux)
* [Install Falco (Containers)](How to Install Falco using Containers)
* [Compile the Source Code](How to Install Falco from Source)
####Falco Documentation
* [Running Falco](Running Falco): How to run falco
* [Falco Rules](Falco Rules): Describing the falco rule format
- [Falco Configuration](Falco Configuration): How to configure falco
* [Falco Alerts](Falco Alerts): Describing the alert channels
* [Falco Examples](Falco Examples): Examples of what falco can detect
* Helpful blog posts
** [Introducing Falco](https://sysdig.com/blog/sysdig-falco/)
####Releases
* [List of falco releases](https://github.com/draios/falco/releases)
####Coding Conventions
* [Sysdig User Level Coding Conventions] (https://github.com/draios/sysdig/blob/master/coding_conventions.md): Falco uses the same coding conventions as sysdig.
**Support / Join the Community**
* For support using falco, please see the documentation below or contact the [official mailing list] (https://groups.google.com/forum/#!forum/falco).
* Follow us on [Twitter] (https://twitter.com/sysdig) for general falco and sysdig news.
* This is our [blog] (https://sysdig.com/blog/), where you can find the latest [falco](https://sysdig.com/blog/tag/falco/) posts.
* Join our [Public Slack](https://sysdig.slack.com) channel #falco for falco announcements and discussions.
Like what sysdig is doing? [We are hiring] (http://sysdig.com/jobs/).

57
How-to-Install-Falco-for-Linux.md Normal file

@@ -0,0 +1,57 @@
## Installation
## 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 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
```
- 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`
To uninstall, just do `yum erase 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`
To uninstall, just do `apt-get remove falco`.

49
How-to-Install-Falco-from-Source.md Normal file

@@ -0,0 +1,49 @@
# Building falco from source
## Check out source code
Clone this repo in a directory that also contains the sysdig source repo. The result should be something like:
```
22:50 vagrant@vagrant-ubuntu-trusty-64:/sysdig
$ pwd
/sysdig
22:50 vagrant@vagrant-ubuntu-trusty-64:/sysdig
$ ls -l
total 20
drwxr-xr-x 1 vagrant vagrant 238 Feb 21 21:44 falco
drwxr-xr-x 1 vagrant vagrant 646 Feb 21 17:41 sysdig
```
create a build dir, then setup cmake and run make from that dir:
```
$ mkdir build
$ cd build
$ cmake ..
$ make
```
Afterward, you should have a falco executable in `build/userspace/falco/falco`.
If you'd like to build a debug version, run cmake as `cmake -DCMAKE_BUILD_TYPE=Debug ..` instead.
## 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.
Unload any existing kernel module via:
`$ rmmod sysdig_probe`
To load the locally built version, assuming you are in the `build` dir, use:
`$ insmod driver/sysdig-probe.ko`
## Running falco
Assuming you are in the `build` dir, you can run falco as:
`$ sudo ./userspace/falco/falco -c ../falco.yaml -r ../rules/falco_rules.yaml`
By default, falco logs events to standard error.

41
How-to-Install-Falco-using-Containers.md Normal file

@@ -0,0 +1,41 @@
# How to Install Falco using Containers
## 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
```
## 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
```
## Building and running falco locally from source
Building falco requires having `cmake` and `g++` installed.

34
Running-Falco.md Normal file

@@ -0,0 +1,34 @@
# 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.
## Running falco as a service (after installing package)
`service falco start` will start the falco service. The default configuration logs events to syslog.
## 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
If you'd like to run falco by hand, here's the full usage description for falco:
```
$ ./userspace/falco/falco --help
Usage: falco [options]
Options:
-h, --help Print this page
-c Configuration file (default /mnt/sf_mstemm/work/src/falco/falco.yaml, /etc/falco.yaml)
-o, --option <key>=<val> Set the value of option <key> to <val>. Overrides values in configuration file.
<key> can be a two-part <key>.<subkey>
-d, --daemon Run as a daemon
-p, --pidfile <pid_file> When run as a daemon, write pid to specified file
-e <events_file> Read the events from <events_file> (in .scap format) instead of tapping into live.
-r <rules_file> Rules file (defaults to value set in configuration file, or /etc/falco_rules.yaml).
-L Show the name and description of all rules and exit.
-l <rule> Show the name and description of the rule with name <rule> and exit.
```