github/falco
1
0
Fork 0
mirror of https://github.com/falcosecurity/falco.git synced 2025-08-31 06:10:45 +00:00
Code Issues Projects Releases Wiki Activity

remove wiki content 

Signed-off-by: Michael Ducy <michael@ducy.org>
Michael Ducy
2019-12-18 08:18:20 -05:00
parent 0182faf528
commit 1f71c116a3
20 changed files with 21 additions and 1840 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
About-Falco.md

@@ -1,58 +1,4 @@
# FALCO DOCUMENTATION HAS MOVED
**The [new home](https://falco.org/docs) for Falco Documentation can be found on the [main Falco site](https://falco.org/docs).**
**This page can be found at https://falco.org/docs**
# About Falco
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. 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 Falco Compares to Other Security Tools like SELinux, Auditd, etc.
One of the questions we often get when we talk about Falco is “How does it compare to other tools like SELinux, AppArmor, Auditd, etc. that also have security policies?”. We wrote a [blog post](https://sysdig.com/blog/selinux-seccomp-falco-technical-discussion/) comparing Falco to other tools.
## 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
* Pipe to a spawned program. A common use of this output type would be to send an email for every falco notification.
More details on these alerts are described [here](Falco Alerts).
**This page can be found at https://falco.org/docs**

36
Actions-For-Dropped-System-Call-Events.md

@@ -1,38 +1,4 @@
# FALCO DOCUMENTATION HAS MOVED
**The [new home](https://falco.org/docs) for Falco Documentation can be found on the [main Falco site](https://falco.org/docs).**
**This page can be found at https://falco.org/docs/event-sources/dropped-events/**
# Introduction
A new feature in 0.15.0 allows Falco to take actions when it detects dropped system call events. When system call events are dropped, Falco may have problems building its internal view of the processes, files, containers, and orchestrator metadata in use, which in turn may affect rules that depend on that metadata. These actions make it easier to detect when dropped system calls are occurring.
## Implementation
Every second, Falco reads system call event counts that are populated by the kernel module/ebpf program. These include counts of the number of system calls processed, and most importantly, the number of times the kernel tried to write system call information to the shared buffer between kernel and userspace but found the buffer to be full. These are considered *dropped* system call events.
When at least one dropped event is detected, Falco can take any of the following actions:
* "ignore": do nothing. If an empty list is provided, ignore is assumed.
* "log": log a CRITICAL message noting that the buffer was full.
* "alert": emit a falco alert noting that the buffer was full.
* "exit": exit falco with a non-zero rc.
Here's an sample log message, alert, and exit message:
```
Wed Mar 27 15:28:22 2019: Falco initialized with configuration file /etc/falco/falco.yaml
Wed Mar 27 15:28:22 2019: Loading rules from file /etc/falco/falco_rules.yaml:
Wed Mar 27 15:28:24 2019: Falco internal: syscall event drop. 1 system calls dropped in last second.
15:28:24.000207862: Critical Falco internal: syscall event drop. 1 system calls dropped in last second.(n_drops=1 n_evts=1181)
Wed Mar 27 15:28:24 2019: Falco internal: syscall event drop. 1 system calls dropped in last second.
Wed Mar 27 15:28:24 2019: Exiting.
```
## Actions Rate Throttling
To reduce the likelihood of a flood of log messages/alerts, actions are governed by a token bucket. The default parameters of the token bucket are a rate of one alert per 30 seconds with an allowed burst of up to 10 messages.
## Configuration
The actions to take on a dropped syscall event and the throttling parameters for the token bucket are configurable in `falco.yaml` and described [[here|Falco-Configuration#syscall_event_drops]].
**This page can be found at https://falco.org/docs/event-sources/dropped-events/**

162
Falco-Alerts.md

@@ -1,164 +1,4 @@
# FALCO DOCUMENTATION HAS MOVED
**The [new home](https://falco.org/docs) for Falco Documentation can be found on the [main Falco site](https://falco.org/docs).**
**This page can be found at https://falco.org/docs/alerts/**
# Falco Alerts
Falco can send alerts to one or more channels:
* Standard Output
* A file
* Syslog
* A spawned program
* (New in 0.14.1) A HTTP URL
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:
```yaml
stdout_output:
enabled: true
```
```
10:20:05.408091526: Warning Sensitive file opened for reading by non-trusted program (user=root command=cat /etc/shadow file=/etc/shadow)
```
Standard output is useful when using Fluentd or Logstash to capture logs from containers. Alerts can then be stored in Elasticsearch, and dashboards can be created to visualize the alerts. For more information, read [this blog post](https://sysdig.com/blog/kubernetes-security-logging-fluentd-falco/).
When run in the background via the `-d/--daemon` command line option, standard output messages are discarded.
## File Output
When configured to send alerts to a file, a message is written to the file for each alert. The format is very similar to the Standard Output format:
```yaml
file_output:
enabled: true
keep_alive: false
filename: ./events.txt
```
When `keep_alive` is false (the default), 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. If `keep_alive` is set to true, the file is opened before the first alert and kept open for all subsequent alerts. Output is buffered and will be flushed only on close. (This can be changed with `--unbuffered`).
If you'd like to use a program like [logrotate](https://github.com/logrotate/logrotate) to rotate the output file, an example logrotate config is available [here](https://github.com/draios/falco/blob/dev/examples/logrotate/falco).
As of Falco 0.10.0, falco will close and reopen its file output when signaled with `SIGUSR1`. The logrotate example above depends on it.
## 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:
```yaml
syslog_output:
enabled: true
```
```
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.
## Program Output
When configured to send alerts to a program, for each alert the program is started and written to its standard input. You can only configure a single program output (e.g. route alerts to a single program) at a time.
For example, given a `falco.yaml` configuration of:
```yaml
program_output:
enabled: true
keep_alive: false
program: mail -s "Falco Notification" someone@example.com
```
When `keep_alive` is false (the default), for each alert falco will run the program `mail -s ...` and write the alert to the program. The program is run via a shell, so it's possible to specify a command pipeline if you wish to add additional formatting.
If `keep_alive` is set to true, before the first alert falco will spawn the program and write the alert. The program pipe will be kept open for subsequent alerts. Output is buffered and will be flushed only on close. (This can be changed with --unbuffered).
*Note*: the program spawned by falco is in the same process group as falco and will receive all signals that falco receives. If you want to, say, ignore SIGTERM to allow for a clean shutdown in the face of buffered outputs, you must override the signal handler yourself.
As of Falco 0.10.0, falco will close and reopen its file output when signaled with `SIGUSR1`.
### Program Output Example: Posting to a Slack Incoming Webhook
If you'd like to send falco notifications to a slack channel, here's the required configuration to massage the JSON output to a form required for the slack webhook endpoint:
```yaml
# Whether to output events in json or text
json_output: true
…
program_output:
enabled: true
program: "jq '{text: .output}' | curl -d @- -X POST https://hooks.slack.com/services/XXX"
```
### Program Output: Sending Alerts to Network Channel
If you'd like to send a stream of alerts over a network connection, here's an example:
```yaml
# Whether to output events in json or text
json_output: true
…
program_output:
enabled: true
keep_alive: true
program: "nc host.example.com 1234"
```
Note the use of `keep_alive: true` to keep the network connection persistent.
### (New in 0.14.1) HTTP URL
If you'd like to send events directly to a http url without invoking the program `curl`, you can use the http output. Here's some example configuration:
```
http_output:
enabled: true
url: http://some.url/you/post/to
```
Events will be POSTed to that url with a `Content-Type: application/json` header. **NOTE:** Currently, this is a blocking operation, meaning that all event processing will stall until the POST completes. We're going to make all of the output channels non-blocking in an upcoming release.
## 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.
* `output_fields`: for each templated value in the output expression, the value of that field from the event that triggered the alert.
Here's an example:
```javascript
{"output":"16:31:56.746609046: Error File below a known binary directory opened for writing (user=root command=touch /bin/hack file=/bin/hack)","priority":"Error","rule":"Write below binary dir","time":"2017-10-09T23:31:56.746609046Z", "output_fields": {"evt.t\
ime":1507591916746609046,"fd.name":"/bin/hack","proc.cmdline":"touch /bin/hack","user.name":"root"}}
```
Here's the same output, pretty-printed:
```javascript
{
"output" : "16:31:56.746609046: Error File below a known binary directory opened for writing (user=root command=touch /bin/hack file=/bin/hack)"
"priority" : "Error",
"rule" : "Write below binary dir",
"time" : "2017-10-09T23:31:56.746609046Z",
"output_fields" : {
"user.name" : "root",
"evt.time" : 1507591916746609046,
"fd.name" : "/bin/hack",
"proc.cmdline" : "touch /bin/hack"
}
}
```
**This page can be found at https://falco.org/docs/alerts/**

140
Falco-Configuration.md

@@ -1,142 +1,4 @@
# FALCO DOCUMENTATION HAS MOVED
**The [new home](https://falco.org/docs) for Falco Documentation can be found on the [main Falco site](https://falco.org/docs).**
**This page can be found at https://falco.org/docs/configuration/**
# 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: [<path1>, <path2>, ...]`
the location of the rules file(s). This can contain one or more paths to separate rules files. In falco.yaml, this is expressed as the equivalent:
```yaml
rules_file:
- <path1>
- <path2>
- ...
```
You can also specify multiple rules files on the command line via one or more `-r` options.
#### `json_output: [true|false]`
whether to use JSON output for alert messages.
#### `json_include_output_property: [true|false]`
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.
#### `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.
#### `log_level: [emergency|alert|critical|error|warning|notice|info|debug]`
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.
#### `priority: [emergency|alert|critical|error|warning|notice|info|debug]`
Minimum rule priority level to load and run. All rules having a priority more severe than this level will be loaded/run.
#### `syscall_event_drops`
Controls [[Actions For Dropped System Call Events]]. An object containing these sub-keys:
* `actions`: A list containing one or more of these sub-keys:
* `ignore`: do nothing. If an empty list is provided, ignore is assumed.
* `log`: log a CRITICAL message noting that the buffer was full.
* `alert`: emit a falco alert noting that the buffer was full.
* `exit`: exit falco with a non-zero rc.
* `rate`: The steady-state rate at which actions can be taken. Units of actions/second. Default 0.03333 (one action per 30 seconds).
* `max_burst`: The maximum number of actions that can be taken before the steady-state rate is applied.
#### `buffered_outputs: [true|false]`
# Whether or not output to any of the output channels below is buffered. Defaults to false.
#### `outputs`
An object containing these sub-keys:
* `rate: <notifications/second>`
* `outputs: max_burst: <number of messages>`
A throttling mechanism implemented as a token bucket limits the rate of falco notifications. This throttling is controlled by the `rate` and `max_burst` options.
`rate` is the number of tokens (i.e. right to send a notification) gained per second, and defaults to 1. `max_burst` is the maximum number of tokens outstanding, and defaults to 1000.
With these defaults, falco could send up to 1000 notifications after an initial quiet period, and then up to 1 notification per second afterward. It would gain the full burst back after 1000 seconds of no activity.
#### `syslog_output`
An object containing these sub-keys:
* `enabled: [true|false]`: if true, falco alerts will be sent via syslog
#### `file_output`
An object containing these sub-keys:
* `enabled: [true|false]`: if true, falco alerts will be sent to the specified file
* `keep_alive: [true|false]`: If false (default), will reopen file for every alert. If true, will open the file once and keep it open for all alerts. Might be necessary to also specify `--unbuffered` on falco command line.
* `filename: <path>`: the location of the file to which alerts will be sent
#### `stdout_output`
An object containing these sub-keys:
* `enabled: [true|false]`: if true, falco alerts will be sent to standard output
#### `program_output`
An object containing these sub-keys:
* `enabled: [true|false]`: if true, falco alerts will be sent to a program
* `keep_alive: [true|false]`: If false (default), run program for each alert. If true, will spawn program once and keep it open for all alerts. Might be necessary to also specify `--unbuffered` on falco command line.
* `program: <program>`: the program to run for each alert. This is started via a shell, so you can specify a command pipeline to allow for additional formatting.
#### http_output
An object containing these sub-keys:
* `enabled: [true|false]`: if true, falco alerts will be sent to the specified url
* `url: <url>`: Send alerts to the provided url.
For more details, see [the full documentation on http outputs](https://github.com/falcosecurity/falco/wiki/Falco-Alerts#new-in-0141-http-url).
#### `webserver`
An object containing these sub-keys:
* `enabled: [true|false]`: if true, falco will start an embedded webserver to accept k8s audit events
* `listen_port`: The port on which to listen for k8s audit events. Default 8765.
* `k8s_audit_endpoint`: The uri on which to listen for k8s audit events. Default `/k8s_audit`.
* `ssl_enabled`: If true, the embedded webserver will use SSL for incoming connections. Default `false`.
* `ssl_certificate`: A path to a combination SSL certificate for the embedded webserver. Default `/etc/falco/falco.pem`, although falco does not actually ship with any certificate.
The SSL Options are new in 0.14.0.
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
```
**This page can be found at https://falco.org/docs/configuration/**

18
Falco-Default-and-Local-Rules-Files.md

@@ -1,20 +1,4 @@
# FALCO DOCUMENTATION HAS MOVED
**The [new home](https://falco.org/docs) for Falco Documentation can be found on the [main Falco site](https://falco.org/docs).**
**This page can be found at https://falco.org/docs/rules/default-custom/**
Starting with Falco 0.8.0, falco officially supports the notion of a _default_ rules file and a _local_ rules file. This has previously been supported by running falco with multiple `-r` arguments. In 0.8.0, we're formalizing this notion to make it easier to customize falco's behavior but still retain access to rule changes as a part of software upgrades. Of course, you can always customize the set of files you want to read by changing the `rules_file` option in `falco.yaml`.
The default rules file is always read first, followed by the local rules file.
When installed via rpm/debian packages, both rules files, as well as the falco configuration file, are flagged as "config" files, meaning they are not overridden on package upgrade/uninstall if modified.
## Default Rules File
The default falco rules file is installed at `/etc/falco/falco_rules.yaml`. It contains a predefined set of rules designed to provide good coverage in a variety of situations. The intent is that this rules file is not modified, and is replaced with each new software version.
## Local Rules File
The local falco rules file is installed at `/etc/falco/falco_rules.local.yaml`. It is empty other than some comments. The intent is that additions/overrides/modifications to the main rules file are added to this local file. It will not be replaced with each new software version.
**This page can be found at https://falco.org/docs/rules/default-custom/**

95
Falco-Examples.md

@@ -1,97 +1,4 @@
# FALCO DOCUMENTATION HAS MOVED
**The [new home](https://falco.org/docs) for Falco Documentation can be found on the [main Falco site](https://falco.org/docs).**
**This page can be found at https://falco.org/docs/examples/**
# 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
```
**This page can be found at https://falco.org/docs/examples/**

48
Falco-Formatting-for-Containers-and-Orchestration.md

@@ -1,50 +1,4 @@
# FALCO DOCUMENTATION HAS MOVED
**The [new home](https://falco.org/docs) for Falco Documentation can be found on the [main Falco site](https://falco.org/docs).**
**This page can be found at https://falco.org/docs/alerts/formatting/**
Like sysdig, falco has native support for containers and orchestration environments. With `-k`, falco communicates with the provided K8s API server to decorate events with the K8s pod/namespace/deployment/etc. associated with the event. With `-m`, falco communicates with the marathon server to do the same thing.
Like sysdig, falco can be run with `-pk`/`-pm`/`-pc`/`-p` arguments that change the formatted output to be a k8s-friendly/mesos-friendly/container-friendly/general format. However, unlike sysdig, the source of formatted output is in the set of rules and not on the command line. This page provides more detail on how `-pk`/`-pm`/`-pc`/`-p` interacts with the format strings in the `output` attribute of rules.
The information from k8s/mesos/containers is used in conjunction with the command line options in these ways:
* In rule outputs, if the format string contains `%container.info`, that is replaced with the value from `-pk`/`-pm`/`-pc`, if one of those options was provided. If no option was provided, `%container.info` is replaced with a generic `%container.name (id=%container.id)` instead.
* If the format string does not contain `%container.info`, and one of `-pk`/`-pm`/`-pc` was provided, that is added to the end of the formatting string.
* If `-p` was specified with a general value (i.e. not `-pk`/`-pm`/`-pc`), the value is simply added to the end and any `%container.info` is replaced with the generic value.
## Examples
Here are some examples of falco command lines, output strings in rules, and the resulting output:
### Output contains `%container.info`
```
output: "Namespace change (setns) by unexpected program (user=%user.name command=%proc.cmdline parent=%proc.pname %container.info)"
$ falco
15:42:35.347416068: Warning Namespace change (setns) by unexpected program (user=root command=test_program parent=hyperkube k8s-kubelet (id=4a4021c50439))
$ falco -pk -k <k8s api server url>
15:42:35.347416068: Warning Namespace change (setns) by unexpected program (user=root command=test_program parent=hyperkube k8s.pod=jclient-3160134038-qqaaz container=4a4021c50439)
$ falco -p "This is Some Extra" -k <k8s api server url>
15:42:35.347416068: Warning Namespace change (setns) by unexpected program (user=root command=test_program parent=hyperkube k8s-kubelet (id=4a4021c50439)) This is Some Extra
```
### Output does not contain `%container.info`
```
output: "File below a known binary directory opened for writing (user=%user.name command=%proc.cmdline file=%fd.name)"
$ falco
15:50:18.866559081: Warning File below a known binary directory opened for writing (user=root command=touch /bin/hack file=/bin/hack) k8s-kubelet (id=4a4021c50439)
$ falco -pk -k <k8s api server url>
15:50:18.866559081: Warning File below a known binary directory opened for writing (user=root command=touch /bin/hack file=/bin/hack) k8s.pod=jclient-3160134038-qqaaz container=4a4021c50439
$ falco -p "This is Some Extra" -k <k8s api server url>
15:50:18.866559081: Warning File below a known binary directory opened for writing (user=root command=touch /bin/hack file=/bin/hack) This is Some Extra
```
**This page can be found at https://falco.org/docs/alerts/formatting/**

18
Falco-Kernel-Module.md

@@ -1,20 +1,4 @@
# FALCO DOCUMENTATION HAS MOVED
**The [new home](https://falco.org/docs) for Falco Documentation can be found on the [main Falco site](https://falco.org/docs).**
**This page can be found at https://falco.org/docs/event-sources/kernel-module/**
# Introduction
Falco depends on a kernel module that taps into the stream of system calls on a machine and passes those system calls to user space.
Versions before v0.6.0 used the kernel module from sysdig called `sysdig-probe`. As of 0.6.0, falco uses its own kernel module `falco-probe`. The kernel modules are actually built from the same source code, but having a falco-specific kernel module allows falco and sysdig to be updated independently without driver compatibility problems.
# Installing the kernel module
By default, the kernel module will be installed when installing the falco debian/redhat package or when running the `faclosecurity/falco` docker image. The script that installs the kernel module tries to install it in 3 different ways:
* Build the kernel module from source using [dkms](https://en.wikipedia.org/wiki/Dynamic_Kernel_Module_Support).
* Download a pre-built kernel module from downloads.draios.com.
* Look for a pre-built kernel module from `~/.sysdig`.
For options using a pre-built kernel module, the kernel module should have the following filename: `falco-probe-<falco version>-<arch>-<kernel release>-<kernel config hash>.ko` `<kernel config hash>` is a md5sum of the config file that sets kernel options (e.g. `/boot/config-4.4.0-64-generic`). This file can reside in other locations--see the [kernel module builder script](https://github.com/draios/sysdig/blob/dev/scripts/sysdig-probe-loader) for full details on the set of paths it tries to find the kernel config file.
**This page can be found at https://falco.org/docs/event-sources/kernel-module/**

172
Falco-Rules-Default-Macros.md

@@ -1,174 +1,4 @@
# FALCO DOCUMENTATION HAS MOVED
**The [new home](https://falco.org/docs) for Falco Documentation can be found on the [main Falco site](https://falco.org/docs).**
**This page can be found at https://falco.org/docs/rules/default-macros/**
## Falco Rules Default Macros
The default Falco rule set defines a number of macros that makes it easier to start writing rules. These macros provide shortcuts for a number of common scenarios and can be used in any user defined rule sets. Falco also provide Macros that should be overridden by the user to provide settings that are specific to a user's environment. The provided Macros can also be [appended to](Falco Rules Default Macros) in a local rules file.
### File Opened for Writing
```
- macro: open_write
condition: (evt.type=open or evt.type=openat) and evt.is_open_write=true and fd.typechar='f' and fd.num>=0
```
### File Opened for Reading
```
- macro: open_read
condition: (evt.type=open or evt.type=openat) and evt.is_open_read=true and fd.typechar='f' and fd.num>=0
```
### Never True
```
- macro: never_true
condition: (evt.num=0)
```
### Always True
```
- macro: always_true
condition: (evt.num=>0)
```
### Proc Name is Set
```
- macro: proc_name_exists
condition: (proc.name!="<NA>")
```
### File System Object Renamed
```
- macro: rename
condition: evt.type in (rename, renameat)
```
### New Directory Created
```
- macro: mkdir
condition: evt.type = mkdir
```
### File System Object Removed
```
- macro: remove
condition: evt.type in (rmdir, unlink, unlinkat)
```
### File System Object Modified
```
- macro: modify
condition: rename or remove
```
### New Process Spawned
```
- macro: spawned_process
condition: evt.type = execve and evt.dir=<
```
### Common Directories for Binaries
```
- macro: bin_dir
condition: fd.directory in (/bin, /sbin, /usr/bin, /usr/sbin)
```
### Shell is Started
```
- macro: shell_procs
condition: (proc.name in (shell_binaries))
```
### Known Sensitive Files
```
- macro: sensitive_files
condition: >
fd.name startswith /etc and
(fd.name in (sensitive_file_names)
or fd.directory in (/etc/sudoers.d, /etc/pam.d))
```
### Newly Created Process
```
- macro: proc_is_new
condition: proc.duration <= 5000000000
```
### Inbound Network Connections
```
- macro: inbound
condition: >
(((evt.type in (accept,listen) and evt.dir=<)) or
(fd.typechar = 4 or fd.typechar = 6) and
(fd.ip != "0.0.0.0" and fd.net != "127.0.0.0/8") and (evt.rawres >= 0 or evt.res = EINPROGRESS))
```
### Outbound Network Connections
```
- macro: outbound
condition: >
(((evt.type = connect and evt.dir=<)) or
(fd.typechar = 4 or fd.typechar = 6) and
(fd.ip != "0.0.0.0" and fd.net != "127.0.0.0/8") and (evt.rawres >= 0 or evt.res = EINPROGRESS))
```
### Inbound or Outbound Network Connections
```
- macro: inbound_outbound
condition: >
(((evt.type in (accept,listen,connect) and evt.dir=<)) or
(fd.typechar = 4 or fd.typechar = 6) and
(fd.ip != "0.0.0.0" and fd.net != "127.0.0.0/8") and (evt.rawres >= 0 or evt.res = EINPROGRESS))
```
### Object is a Container
```
- macro: container
condition: container.id != host
```
### Interactive Process Spawned
```
- macro: interactive
condition: >
((proc.aname=sshd and proc.name != sshd) or
proc.name=systemd-logind or proc.name=login)
```
## Macros to Override
The below macros contain values that can be overridden for a user's specific environment.
### Common SSH Port
Override this macro to reflect ports in your environment that provide SSH services.
```
- macro: ssh_port
condition: fd.sport=22
```
### Allowed SSH Hosts
Override this macro to reflect hosts that can connect to known SSH ports (ie a bastion or jump box).
```
- macro: allowed_ssh_hosts
condition: ssh_port
```
### User Whitelisted Containers
Whitelist containers that are allowed to run in privileged mode.
```
- macro: user_trusted_containers
condition: (container.image startswith sysdig/agent)
```
### Containers Allowed to Spawn Shells
Whitelist containers that are allowed to spawn shells, which may be needed if containers are used in the CI/CD pipeline.
```
- macro: user_shell_container_exclusions
condition: (never_true)
```
### Containers Allowed to Communicate with EC2 Metadata Services
Whitelist containers that are allowed to communicate with the EC2 metadata service. Default: any container.
```
- macro: ec2_metadata_containers
condition: container
```
### Kubernetes API Server
Set the IP of your Kubernetes API Service here.
```
- macro: k8s_api_server
condition: (fd.sip="1.2.3.4" and fd.sport=8080)
```
### Containers Allowed to Communicate with the Kubernetes API
Whitelist containers that are allowed to communicate with the Kubernetes API Service. Requires `k8s_api_server` being set.
```
- macro: k8s_containers
condition: >
(container.image startswith gcr.io/google_containers/hyperkube-amd64 or
container.image startswith gcr.io/google_containers/kube2sky or
container.image startswith sysdig/agent or
container.image startswith sysdig/falco or
container.image startswith sysdig/sysdig)
```
### Containers Allowed to Communicate with Kubernetes Service NodePorts
```
- macro: nodeport_containers
condition: container
```
**This page can be found at https://falco.org/docs/rules/default-macros/**

317
Falco-Rules.md

@@ -1,319 +1,4 @@
# FALCO DOCUMENTATION HAS MOVED
**The [new home](https://falco.org/docs) for Falco Documentation can be found on the [main Falco site](https://falco.org/docs).**
**This page can be found at https://falco.org/docs/rules/**
# 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 three kinds of elements: *rules*, *macros*, and *lists*.
Rules consist 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.
Lists are (surprise!) lists of items that can be included in rules, macros, or other lists. Unlike rules/macros, they can not be parsed as sysdig filtering expressions.
## Versioning
From time to time, we make changes to the rules file format that are not backwards-compatible with older versions of falco. Similarly, the sysdig libraries incorporated into falco may define new filtercheck fields, operators, etc. We want to denote that a given set of rules depends on the fields/operators from those sysdig libraries.
To address this, as of falco 0.14.0 we're introducing explicit versioning of both the falco engine and the falco rules file.
### Falco Engine Versioning
The falco executable and the falco_engine c++ object now support returning a version number. The initial version will be 2 (implying prior versions were 1). Any time we make an incompatible change to the rules file format or add new filtercheck fields/operators to falco, we will increment this version.
### Falco Rules File Versioning
The falco rules files included with falco will include a new top-level object `required_engine_version: N` that mandates the minimum engine version required to read this rules file. If not included, no version check is performed when reading the rules file.
If a rules file has a engine_version greater than the falco engine version, the rules file will not be loaded and an error will be returned.
## Rules
A Rule is a node containing the following keys:
* _rule_: a short unique name for the rule
* _condition_: a filtering expression that is applied against events to see if they match 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](https://github.com/draios/sysdig/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".
* (optional) _enabled_: can be either `true` or `false`. If `enabled=false`, a rule will not be loaded nor will it be matched against any events. The default for `enabled` is `true`.
* (optional) _tags_: a list of tags applied to the rule. More on this below.
* (optional) _warn_evttypes_: can be either `true` or `false`. If `warn_evttypes=false`, falco will suppress warnings related to a rule not having an event type (See [here](#rule-condition-best-practices)). The default for `warn_evttypes` is `true`.
* (optional) _skip-if-unknown-filter_: Can be either `true` or `false`. If `skip-if-unknown-filter=true`, if a rule's condition contains a filtercheck (e.g. `fd.some_new_field`) that is not known to this version of falco, falco will silently accept the rule but not execute it. With the default `false`, upon finding an unknown filtercheck Falco will report an error and exit.
## 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](https://github.com/draios/sysdig/wiki/Sysdig-User-Guide#user-content-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`.
## Lists
The third type of item in a rules file is lists. A list is a node with the following keys:
* _list_: a name for the list
* _items_: a list of values
Here's an example:
```yaml
- list: shell_binaries
items: [bash, csh, ksh, sh, tcsh, zsh, dash]
- list: userexec_binaries
items: [sudo, su]
- list: known_binaries
items: [shell_binaries, userexec_binaries]
- macro: safe_procs
condition: proc.name in (known_binaries)
```
Referring to a list inserts the list items in the macro, rule, or list. Note that lists can contain other lists.
## Appending to Lists, Rules, and Macros
If you use multiple falco rules files, you might want to append new items to an existing list, rule, or macro. To do that, define a item with the same name as an existing item and add an `append: true` attribute to the list. When appending lists, items are added to the end of the list. When appending rules/macros, the additional text is appended to the condition: field of the rule/macro.
### Examples
In all of the examples below, it's assumed one is running falco via `falco -r /etc/falco/falco_rules.yaml -r /etc/falco/falco_rules.local.yaml`, or has the default entries for `rules_file` in falco.yaml, which has `/etc/falco/falco.yaml` first and `/etc/falco/falco_rules.local.yaml` second.
#### Appending to lists
Here's an example of appending to lists:
**/etc/falco/falco_rules.yaml**
```yaml
- list: my_programs
items: [ls, cat, pwd]
- rule: my_programs_opened_file
desc: track whenever a set of programs opens a file
condition: proc.name in (my_programs) and evt.type=open
output: a tracked program opened a file (user=%user.name command=%proc.cmdline file=%fd.name)
priority: INFO
```
**/etc/falco/falco_rules.local.yaml**
```yaml
- list: my_programs
append: true
items: [cp]
```
The rule `my_programs_opened_file` would trigger whenever any of `ls`, `cat`, `pwd`, or `cp` opened a file.
#### Appending to Macros
Here's an example of appending to macros:
**/etc/falco/falco_rules.yaml**
```yaml
- macro: access_file
condition: evt.type=open
- rule: program_accesses_file
desc: track whenever a set of programs opens a file
condition: proc.name in (cat, ls) and (access_file)
output: a tracked program opened a file (user=%user.name command=%proc.cmdline file=%fd.name)
priority: INFO
```
**/etc/falco/falco_rules.local.yaml**
```yaml
- macro: access_file
append: true
condition: or evt.type=openat
```
The rule `program_accesses_file` would trigger when `ls`/`cat` either used `open`/`openat` on a file.
#### Appending to Rules
Here's an example of appending to rules:
**/etc/falco/falco_rules.yaml**
```yaml
- rule: program_accesses_file
desc: track whenever a set of programs opens a file
condition: proc.name in (cat, ls) and evt.type=open
output: a tracked program opened a file (user=%user.name command=%proc.cmdline file=%fd.name)
priority: INFO
```
**/etc/falco/falco_rules.local.yaml**
```yaml
- rule: program_accesses_file
append: true
condition: and not user.name=root
```
The rule `program_accesses_file` would trigger when `ls`/`cat` either used `open` on a file, but not if the user was root.
### Gotchas with rule/macro append and logical operators
Remember that when appending rules and macros, the text of the second rule/macro is simply added to the condition of the first rule/macro. This can result in unintended results if the original rule/macro has potentially ambiguous logical operators. Here's an example:
```yaml
- rule: my_rule
desc: ...
condition: evt.type=open and proc.name=apache
output: ...
- rule: my_rule
append: true
condition: or proc.name=nginx
```
Should `proc.name=nginx` be interpreted as relative to the `and proc.name=apache`, that is to allow either apache/nginx to open files, or relative to the `evt.type=open`, that is to allow apache to open files or to allow nginx to do anything?
In cases like this, be sure to scope the logical operators of the original condition with parentheses when possible, or avoid appending conditions when not possible.
## Rule Priorities
Every falco rule has a priority which indicates how serious a violation of the rule is. The priority will be included in the message/json output/etc. The possible set of priorities are:
* EMERGENCY
* ALERT
* CRITICAL
* ERROR
* WARNING
* NOTICE
* INFORMATIONAL
* DEBUG
The general guidelines used to assign priorities to rules are the following:
* If a rule is related to a write of state (i.e. filesystem, etc.), its priority is ERROR.
* If a rule is related to an unauthorized read of state (i.e. reading sensitive filees, etc.), its priority is WARNING.
* If a rule is related to unexpected behavior (spawning an unexpected shell in a container, opening an unexpected network connection, etc.), its priority is NOTICE.
* If a rule is related to behaving against good practices (unexpected privileged containers, containers with sensitive mounts, running interactive commands as root), its priority is INFO.
One exception is that the rule "Run shell untrusted", which is fairly FP-prone, has a priority of DEBUG.
## Rule Tags
As of 0.6.0, rules have an optional set of _tags_ that are used to categorize the ruleset into groups of related rules. Here's an example:
```
- rule: File Open by Privileged Container
desc: Any open by a privileged container. Exceptions are made for known trusted images.
condition: (open_read or open_write) and container and container.privileged=true and not trusted_containers
output: File opened for read/write by privileged container (user=%user.name command=%proc.cmdline %container.info file=%fd.name)
priority: WARNING
tags: [container, cis]
```
In this case, the rule "File Open by Privileged Container" has been given the tags "container" and "cis". If the tags key is not present for a given rule or the list is empty, a rule has no tags.
Here's how you can use tags:
* You can use the `-T <tag>` argument to disable rules having a given tag. `-T` can be specified multiple times. For example, to skip all rules with the "filesystem" and "cis" tags you would run falco with `falco -T filesystem -T cis ...`. `-T` can not be specified with `-t`.
* You can use the `-t <tag>` argument to *only* run those rules having a given tag. `-t` can be specified multiple times. For example, to only run those rules with the "filesystem" and "cis" tags, you would run falco with `falco -t filesystem -t cis ...`. `-t` can not be specified with `-T` or `-D <pattern>` (disable rules by rule name regex).
### Tags for Current Falco Ruleset
We've also gone through the default ruleset and tagged all the rules with an initial set of tags. Here are the tags we've used:
* filesystem: the rule relates to reading/writing files
* sofware_mgmt: the rule relates to any software/package management tool like rpm, dpkg, etc.
* process: the rule relates to starting a new process or changing the state of a current process.
* database: the rule relates to databases
* host: the rule *only* works outside of containers
* shell: the rule specifically relates to starting shells
* container: the rule *only* works inside containers
* cis: the rule is related to the CIS Docker benchmark.
* users: the rule relates to management of users or changing the identity of a running process.
* network: the rule relates to network activity
Rules can have multiple tags if they relate to multiple of the above. Every rule in the falco ruleset currently has at least one tag.
## Rule Condition Best Practices
To allow for grouping of rules by event type, which improves performance, falco prefers rule conditions that have at least one `evt.type=` operator, at the beginning of the condition, before any negative operators (i.e. `not` or `!=`). If a condition does not have any `evt.type=` operator, falco will log a warning like:
```
Rule no_evttype: warning (no-evttype):
proc.name=foo
did not contain any evt.type restriction, meaning it will run for all event types.
This has a significant performance penalty. Consider adding an evt.type restriction if possible.
```
If a rule has a `evt.type` operator in the later portion of the condition, falco will log a warning like:
```
Rule evttype_not_equals: warning (trailing-evttype):
evt.type!=execve
does not have all evt.type restrictions at the beginning of the condition,
or uses a negative match (i.e. "not"/"!=") for some evt.type restriction.
This has a performance penalty, as the rule can not be limited to specific event types.
Consider moving all evt.type restrictions to the beginning of the rule and/or
replacing negative matches with positive matches if possible.
```
## Escaping Special Characters
In some cases, rules may need to contain special characters like '(', spaces, etc. For example, you may need to look for a `proc.name` of `(systemd)`, including the surrounding parentheses.
Falco, like sysdig, supports quoting using `"` to capture these special characters. Here's an example:
```yaml
- rule: Any Open Activity by Systemd
desc: Detects all open events by systemd.
condition: evt.type=open and proc.name="(systemd)" or proc.name=systemd
output: "File opened by systemd (user=%user.name command=%proc.cmdline file=%fd.name)"
priority: WARNING
```
When including items in lists, you also need to ensure the double quotes are not interpreted at the yaml document level, so you should surround the quoted string with single quotes. Here's an example:
```yaml
- list: systemd_procs
items: [systemd, '"(systemd)"']
- rule: Any Open Activity by Systemd
desc: Detects all open events by systemd.
condition: evt.type=open and proc.name in (systemd_procs)
output: "File opened by systemd (user=%user.name command=%proc.cmdline file=%fd.name)"
priority: WARNING
```
## Ignored system calls
For performance reasons, some system calls are currently discarded before falco processing. The current list is:
`accept access alarm brk capget clock_getres clock_gettime clock_nanosleep clock_settime clone close container cpu_hotplug drop epoll_create epoll_create1 epoll_ctl epoll_pwait epoll_wait eventfd eventfd2 execve exit_group fcntl fcntl64 fdatasync fgetxattr flistxattr fork fstat fstat64 fstatat64 fstatfs fstatfs64 fsync futex get_robust_list get_thread_area getcpu getcwd getdents getdents64 getegid geteuid getgid getgroups getitimer getpeername getpgid getpgrp getpid getppid getpriority getresgid getresuid getrlimit getrusage getsid getsockname getsockopt gettid gettimeofday getuid getxattr infra io_cancel io_destroy io_getevents io_setup io_submit ioctl ioprio_get ioprio_set k8s lgetxattr listxattr llistxattr llseek lseek lstat lstat64 madvise mesos mincore mlock mlockall mmap mmap2 mprotect mq_getsetattr mq_notify mq_timedreceive mq_timedsend mremap msgget msgrcv msgsnd munlock munlockall munmap nanosleep newfstatat newselect notification olduname page_fault pause poll ppoll pread pread64 preadv procexit procinfo pselect6 pwrite pwrite64 pwritev read readv recv recvmmsg remap_file_pages rt_sigaction rt_sigpending rt_sigprocmask rt_sigsuspend rt_sigtimedwait sched_get_priority_max sched_get_priority_min sched_getaffinity sched_getparam sched_getscheduler sched_yield select semctl semget semop send sendfile sendfile64 sendmmsg setitimer setresgid setrlimit settimeofday sgetmask shutdown signaldeliver signalfd signalfd4 sigpending sigprocmask sigreturn splice stat stat64 statfs statfs64 switch sysdigevent tee time timer_create timer_delete timer_getoverrun timer_gettime timer_settime timerfd_create timerfd_gettime timerfd_settime times ugetrlimit umask uname unlink unlinkat ustat vfork vmsplice wait4 waitid waitpid write writev`
When run with `-i`, falco will print the set of events/syscalls ignored and exit. If you'd like to run falco against all events, including system calls in the above list, you can run falco with the `-A` flag.
**This page can be found at https://falco.org/docs/rules/**

55
Generating-Sample-Events.md

@@ -1,57 +1,4 @@
# FALCO DOCUMENTATION HAS MOVED
**The [new home](https://falco.org/docs) for Falco Documentation can be found on the [main Falco site](https://falco.org/docs).**
**This page can be found at https://falco.org/docs/event-sources/sample-events/**
If you'd like to see if falco is working properly, we've created a test program [event_generator](https://github.com/draios/falco/blob/dev/docker/event-generator/event_generator.cpp) that performs a bunch of suspect actions that are detected by the current falco ruleset.
Here's the usage block for the test program:
```
Usage event_generator [options]
Options:
-h/--help: show this help
-a/--action: actions to perform. Can be one of the following:
write_binary_dir Write to files below /bin
write_etc Write to files below /etc
read_sensitive_file Read a sensitive file
read_sensitive_file_after_startup As a trusted program, wait a while,
then read a sensitive file
write_rpm_database Write to files below /var/lib/rpm
spawn_shell Run a shell (bash)
db_program_spawn_process As a database program, try to spawn
another program
modify_binary_dirs Modify a file below /bin
mkdir_binary_dirs Create a directory below /bin
change_thread_namespace Change namespace
system_user_interactive Change to a system user and try to
run an interactive command
network_activity Open network connections
(used by system_procs_network_activity below)
system_procs_network_activity Open network connections as a program
that should not perform network actions
non_sudo_setuid Setuid as a non-root user
create_files_below_dev Create files below /dev
exec_ls execve() the program ls
(used by user_mgmt_binaries below)
user_mgmt_binaries Become the program "vipw", which triggers
rules related to user management programs
exfiltration Read /etc/shadow and send it via udp to a
specific address and port
all All of the above
The action can also be specified via the environment variable EVENT_GENERATOR_ACTIONS
as a colon-separated list
if specified, -a/--action overrides any environment variables
-i/--interval: Number of seconds between actions
-o/--once: Perform actions once and exit
```
This program is packaged in a [docker image](https://hub.docker.com/r/sysdig/falco-event-generator/) at docker hub. You can run it via the following:
```
docker pull sysdig/falco-event-generator
docker run -it --name falco-event-generator sysdig/falco-event-generator
```
It's highly recommended to run the program within docker, as it modifies files and directories below `/bin`, `/etc`, `/dev`, etc.
**This page can be found at https://falco.org/docs/event-sources/sample-events/**

44
Home.md

@@ -1,46 +1,4 @@
# FALCO DOCUMENTATION HAS MOVED
**The [new home](https://falco.org/docs) for Falco Documentation can be found on the [main Falco site](https://falco.org/docs).**
**The wiki has been kept for historical reasons, but will be removed in the near future**
# Welcome to the **Falco** wiki!
On this wiki, you can find information about Falco. If this is your first time hearing about Falco, we recommend you [start with the website](https://falco.org).
#### 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-and-or-Orchestration)
* [Install Falco (K8s/Minikube)](Install-Falco-(Minikube))
* Details on Falco's [Kernel Module](Falco-Kernel-Module)
* [Compile the Source Code](How-to-Install-Falco-from-Source)
#### Falco Documentation
* [Running Falco](Running-Falco): How to run falco
* [Generating Sample Events](Generating-Sample-Events): How to get a stream of sample events to show that falco is working.
* [Falco Default and Local Rules Files](Falco-Default-and-Local-Rules-Files): Describing the breakdown between default and local rules.
* [Falco Rules](Falco-Rules): Describing the falco rule format
* [Falco Rules - Default Macros](Falco-Rules-Default-Macros): Describing Macros falco ships with that provide useful shortcuts for rule development.
* [Falco Configuration](Falco-Configuration): How to configure falco
* [Falco Alerts](Falco-Alerts): Describing the alert channels
* [Falco Formatting for Containers and Orchestration](Falco-Formatting-for-Containers-and-Orchestration): Describing output formatting and how it relates to containers/orchestration.
* [Falco Examples](Falco-Examples): Examples of what falco can detect
* [Actions For Dropped System Call Events](Actions-For-Dropped-System-Call-Events): How to configure actions to take to detected dropped system calls.
* [K8s Audit Event Support](K8s-Audit-Event-Support): How to Process K8s Audit Events with Falco.
* Helpful blog posts
* [Introducing Falco](https://sysdig.com/blog/sysdig-falco/)
* [Friends don't let friends curl | bash](https://sysdig.com/blog/friends-dont-let-friends-curl-bash/)
* [Sending little bobby tables to detention](https://sysdig.com/blog/sending-little-bobby-tables-detention/)
* [SELinux, Seccomp, Falco, and You: A Technical Discussion](https://sysdig.com/blog/selinux-seccomp-falco-technical-discussion/)
#### Releases
* [List of falco releases](https://github.com/falcosecurity/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 the sysdig OSS project.
**Support / Join the Community**
* Join our [Public Slack](https://slack.sysdig.com) channel #falco for falco announcements and discussions.
**The wiki has been kept for redirect reasons, but will be removed in the near future**

77
How-to-Install-Falco-for-Linux.md

@@ -1,79 +1,4 @@
# FALCO DOCUMENTATION HAS MOVED
**The [new home](https://falco.org/docs) for Falco Documentation can be found on the [main Falco site](https://falco.org/docs).**
**This page can be found at https://falco.org/docs/installation/**
# Installation
## Scripted install
To install falco, you can download a shell script that takes care of the necessary steps. First download the script:
`curl -o install-falco.sh -s https://s3.amazonaws.com/download.draios.com/stable/install-falco`
Then verify the md5 checksum of the script. It should be `3632bde02be5aeaef522138919cfece2`.
Then run the script either as root or with sudo:
`sudo bash install-falco.sh`
## 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 https://s3.amazonaws.com/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`. If required, install using:
`rpm -i https://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 https://s3.amazonaws.com/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`.
## Package Management Systems (Puppet, Ansible, etc.)
### Puppet
A puppet module for falco, `sysdig-falco`, is available in the [examples](https://github.com/draios/falco/blob/dev/examples/puppet-module/README.md) directory and [Puppet Forge](https://forge.puppet.com/sysdig/falco/readme).
### Ansible
@juju4 has helpfully written an ansible role, `juju4.falco`. It's available on [github](https://github.com/juju4/ansible-falco/) and [ansible galaxy](https://galaxy.ansible.com/juju4/falco/). The latest version on ansible galaxy (v0.7) does not work with falco 0.9.0, but the version on github does.
**This page can be found at https://falco.org/docs/installation/**

82
How-to-Install-Falco-from-Source.md

@@ -1,84 +1,4 @@
# FALCO DOCUMENTATION HAS MOVED
**The [new home](https://falco.org/docs) for Falco Documentation can be found on the [main Falco site](https://falco.org/docs).**
**This page can be found at https://falco.org/docs/source/**
# Building falco from source
Building falco requires having `cmake` and `g++` installed.
## Build using docker-builder container
One easy way to build falco is to run the [falco-builder](https://hub.docker.com/r/falcosecurity/falco-builder) container. It contains the reference toolchain we use to build packages.
The image depends on the following parameters:
* `FALCO_VERSION`: the version to give any built packages
* `BUILD_TYPE`: Debug or Release
* `BUILD_DRIVER`: whether or not to build the kernel module when
building. This should usually be OFF, as the kernel module would be
built for the files in the centos image, not the host.
* `BUILD_BPF`: Like `BUILD_DRIVER` but for the ebpf program.
* `BUILD_WARNINGS_AS_ERRORS`: consider all build warnings fatal
* `MAKE_JOBS`: passed to the -j argument of make
A typical way to run this builder is the following. Assumes you have
checked out falco and sysdig to directories below /home/user/src, and
want to use a build directory of /home/user/build/falco:
```
$ docker run --user $(id -u):$(id -g) -v /etc/passwd:/etc/passwd:ro -e MAKE_JOBS=4 -it -v /home/user/src:/source -v /home/user/build/falco:/build falcosecurity/falco-builder cmake
$ docker run --user $(id -u):$(id -g) -v /etc/passwd:/etc/passwd:ro -e MAKE_JOBS=4 -it -v /home/user/src:/source -v /home/user/build/falco:/build falcosecurity/falco-builder package
```
## Build directly on host
If you'd rather build directly on the host, you can use your local toolchain and cmake binaries.
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
```
To build from the head of falco's dev branch, make sure you're also using the head of the sysdig dev branch. If you're building from a specific version of falco (say x.y.z), there will be a corresponding tag `falco/x.y.z` on the sysdig repository that you should use.
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 falco-probe kernel module
If you have a binary version of falco installed, an older falco kernel module may already be loaded. To ensure you are using the latest version, you should unload any existing falco kernel module and load the locally built version.
Unload any existing kernel module via:
`$ rmmod falco_probe`
To load the locally built version, assuming you are in the `build` dir, use:
`$ insmod driver/falco-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.
**This page can be found at https://falco.org/docs/source/**

58
How-to-Install-Falco-using-Containers-and-or-Orchestration.md

@@ -1,60 +1,4 @@
# FALCO DOCUMENTATION HAS MOVED
**The [new home](https://falco.org/docs) for Falco Documentation can be found on the [main Falco site](https://falco.org/docs).**
**This page can be found at https://falco.org/docs/installation/**
# 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 falcosecurity/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 falcosecurity/falco
```
To see it in action, also run the [event generator](Generating Sample Events) to perform actions that trigger falco's ruleset:
```
docker pull sysdig/falco-event-generator
docker run -it --name falco-event-generator sysdig/falco-event-generator
```
### Using custom rules with docker container
The falco image has a built-in set of rules located at `/etc/falco/falco_rules.yaml` which is suitable for most purposes. However, you may want to provide your own rules file and still use the falco image. In that case, you should add a volume mapping to map the external rules file to `/etc/falco/falco_rules.yaml` within the container, by adding `-v path-to-falco-rules.yaml:/etc/falco/falco_rules.yaml` to your docker run command.
## 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 falco-probe-loader script:
```
toolbox --bind=/dev --bind=/var/run/docker.sock
curl -s https://s3.amazonaws.com/download.draios.com/stable/install-falco | bash
falco-probe-loader
```
## Container install (K8s)
If you'd like to run falco as a K8s DaemonSet, we have instructions and some sample yaml files [here](https://github.com/draios/falco/tree/dev/integrations/k8s-using-daemonset).
## Additional Notes on Running Falco in Containers/K8s
### Growing Memory Usage for Falco Container When Using File Output
If you notice that the memory usage for a container running Falco increases when using file output methods, even when the memory usage of the falco process itself does not increase, it could be due to the buffer page cache being counted against the memory usage of the container. See falco issue https://github.com/draios/falco/issues/338 for a longer discussion, and the underlying K8s bug/feature is discussed in https://github.com/kubernetes/kubernetes/issues/43916. You can safely cap the memory size of the container to a value like 160Mb, at which point the buffer page cache growth will be limited.
**This page can be found at https://falco.org/docs/installation/**

16
Install-Falco-(Minikube).md

@@ -1,18 +1,4 @@
# FALCO DOCUMENTATION HAS MOVED
**The [new home](https://falco.org/docs) for Falco Documentation can be found on the [main Falco site](https://falco.org/docs).**
**This page can be found at https://falco.org/docs/installation/**
# Introduction
The installation steps for Minikube aren't any different than other K8s Environment. See our [K8s Installation Instructions](../blob/dev/integrations/k8s-using-daemonset/README.md) for details.
### Notes on Kernel Modules
A part of falco's installation involves compiling a kernel module that allows it to see the stream of system calls on the machine where falco runs. The kernel module is built using DKMS and relies on the kernel headers being installed for the running kernel. If the dkms step fails, as a fallback the installation script will try to download pre-built kernel modules from `https://s3.amazonaws.com/download.draios.com`.
When running minikube with the default `--driver` arguments, minikube creates a VM that runs the various K8s services and a container framework to run pods, etc. Generally, it's not possible to build kernel modules directly on the minikube VM, as the vm doesn't include the kernel-headers for the running kernel.
To address this, starting with falco 0.13.1 we prebuild kernel modules for the last 10 minikube versions and make them available at `https://s3.amazonaws.com/download.draios.com`. This allows the fallback step to succeed with a loadable kernel module.
Going forward we'll continue to support the most recent 10 minikube versions with each new falco release. We also keep previously built kernel modules around for download, so we will continue to have limited historical support as well.
**This page can be found at https://falco.org/docs/installation/**

195
K8s-Audit-Event-Support.md

@@ -1,197 +1,4 @@
# FALCO DOCUMENTATION HAS MOVED
**The [new home](https://falco.org/docs) for Falco Documentation can be found on the [main Falco site](https://falco.org/docs).**
**This page can be found at https://falco.org/docs/event-sources/kubernetes-audit/**
# Introduction
As of Falco 0.13.0, falco supports a second source of events in addition to system call events: [K8s Audit Events](https://kubernetes.io/docs/tasks/debug-application-cluster/audit/#audit-backends). An improved implementation of k8s audit events was introduced in k8s v1.11 and provides a log of requests and responses to [kube-apiserver](https://kubernetes.io/docs/admin/kube-apiserver). Since almost all cluster management tasks are done through the api server, the audit log is a way to track the changes made to your cluster. Examples of this include:
* Creating/destroying pods, services, deployments, daemonsets, etc.
* Creating/updating/removing config maps or secrets
* Attempts to subscribe to changes to any endpoint
We also added additional falco rules that look for notable or suspicious activity, including:
* Creating pods that are privileged, mount sensitive host paths, or use host networking.
* Granting overly broad permissions such as `cluster-admin` to users.
* Creating configmaps with sensitive information.
Once you've configured your cluster with audit logging and selected which events you'd like to pass along to falco, you can write falco rules that read these events and send notifications for suspicious or other notable activity.
# Falco Changes
The overall architecture of Falco remains the same, with events being matched against sets of rules, with a rule identifying suspicious/notable behavior. What's new is that there are two parallel independent streams of events being read separately and matched separately against the sets of rules instead of just one.
To receive k8s audit events, falco embeds a [civetweb](https://github.com/civetweb/civetweb) webserver that listens on a configurable port and accepts POST requests on a configurable endpoint. Details on configuring the embedded webserver are on the [config page](Falco-Configuration). The posted json object comprises the event.
A given rule is tied to either system call events or k8s audit events, via the `source` attribute. If not specified, the source defaults to `syscall`. Rules with source `syscall` are matched against system call events. Rules with source `k8s_audit` are matched against k8s audit events.
## Conditions and Fields
Like system call rules, a condition field for k8s audit rules is a logical expression based on operators and event fields (e.g. `ka.user.name`). A given event field selects one property value from the json object. For example, the field `ka.user.name` first identifies the `user` object within the k8s audit event, and then selects the `username` property of that object.
Falco includes a number of predefined fields that access common properties of the k8s event/json object. You can view these via `falco --list <source>`, using `k8s_audit` for `<source>`. The current list of fields is defined [here](Supported-Fields).
If you wish to select a property value of the k8s audit event/json object that isn't covered by one of the predefined fields, you can use `jevt.value[<json pointer>]`. A [JSON Pointer](http://rapidjson.org/md_doc_pointer.html) is a way to select a single property value from a json object. This allows you to select arbitrary property values from the k8s audit event to create your rule's condition. For example, an equivalent way to extract `ka.username` is `jevt.value[/user/username]`.
## K8s Audit Rules
Rules devoted to k8s audit events are in [k8s_audit_rules.yaml](https://github.com/falcosecurity/falco/blob/dev/rules/k8s_audit_rules.yaml). When installed as a daemon, falco installs this rules file to `/etc/falco/`, so they are available for use.
## Example
Here's an example. One of the rules in `k8s_audit_rules.yaml` is the following:
```
- list: k8s_audit_stages
items: ["ResponseComplete"]
# This macro selects the set of Audit Events used by the below rules.
- macro: kevt
condition: (jevt.value[/stage] in (k8s_audit_stages))
- macro: create
condition: ka.verb=create
- macro: configmap
condition: ka.target.resource=configmaps
- macro: contains_private_credentials
condition: >
(ka.req.configmap.obj contains "aws_access_key_id" or
ka.req.configmap.obj contains "aws-access-key-id" or
ka.req.configmap.obj contains "aws_s3_access_key_id" or
ka.req.configmap.obj contains "aws-s3-access-key-id" or
ka.req.configmap.obj contains "password" or
ka.req.configmap.obj contains "passphrase")
- rule: Configmap contains private credentials
desc: >
Detect configmap operations with map containing a private credential (aws key, password, etc.)
condition: kevt and configmap and modify and contains_private_credentials
output: K8s configmap with private credential (user=%ka.user.name verb=%ka.verb name=%ka.req.configmap.name configmap=%ka.req.configmap.name config=%ka.req.configmap.obj)
priority: WARNING
source: k8s_audit
tags: [k8s]
```
The rule `Configmap contains private credentials` checks for a configmap being created where the contents of the configmap contain possibly sensitive items like aws keys or passwords.
Assuming that K8s Audit Logging is configured, we can create a configmap containing the following:
```
apiVersion: v1
data:
ui.properties: |
color.good=purple
color.bad=yellow
allow.textmode=true
access.properties: |
aws_access_key_id = MY-ID
aws_secret_access_key = MY-KEY
kind: ConfigMap
metadata:
creationTimestamp: 2016-02-18T18:52:05Z
name: my-config
namespace: default
resourceVersion: "516"
selfLink: /api/v1/namespaces/default/configmaps/my-config
uid: b4952dc3-d670-11e5-8cd0-68f728db1985
```
Note that the configmap contains aws credentials.
Assuming that k8s audit logging is enabled, creating the configmap results in the following json object in the audit log:
```
{
"kind": "Event",
"apiVersion": "audit.k8s.io/v1beta1",
"metadata": {
"creationTimestamp": "2018-10-20T00:18:28Z"
},
"level": "RequestResponse",
"timestamp": "2018-10-20T00:18:28Z",
"auditID": "33fa264e-1124-4252-af9e-2ce6e45fe07d",
"stage": "ResponseComplete",
"requestURI": "/api/v1/namespaces/default/configmaps",
"verb": "create",
"user": {
"username": "minikube-user",
"groups": [
"system:masters",
"system:authenticated"
]
},
"sourceIPs": [
"192.168.99.1"
],
"objectRef": {
"resource": "configmaps",
"namespace": "default",
"name": "my-config",
"uid": "b4952dc3-d670-11e5-8cd0-68f728db1985",
"apiVersion": "v1"
},
"responseStatus": {
"metadata": {
},
"code": 201
},
"requestObject": {
"kind": "ConfigMap",
"apiVersion": "v1",
"metadata": {
"name": "my-config",
"namespace": "default",
"selfLink": "/api/v1/namespaces/default/configmaps/my-config",
"uid": "b4952dc3-d670-11e5-8cd0-68f728db1985",
"creationTimestamp": "2016-02-18T18:52:05Z"
},
"data": {
"access.properties": "aws_access_key_id = MY-ID\naws_secret_access_key = MY-KEY\n",
"ui.properties": "color.good=purple\ncolor.bad=yellow\nallow.textmode=true\n"
}
},
"responseObject": {
"kind": "ConfigMap",
"apiVersion": "v1",
"metadata": {
"name": "my-config",
"namespace": "default",
"selfLink": "/api/v1/namespaces/default/configmaps/my-config",
"uid": "ab04e510-d3fd-11e8-8645-080027728ac4",
"resourceVersion": "45437",
"creationTimestamp": "2018-10-20T00:18:28Z"
},
"data": {
"access.properties": "aws_access_key_id = MY-ID\naws_secret_access_key = MY-KEY\n",
"ui.properties": "color.good=purple\ncolor.bad=yellow\nallow.textmode=true\n"
}
},
"requestReceivedTimestamp": "2018-10-20T00:18:28.420807Z",
"stageTimestamp": "2018-10-20T00:18:28.428398Z",
"annotations": {
"authorization.k8s.io/decision": "allow",
"authorization.k8s.io/reason": ""
}
}
```
When the rule Configmap contains private credentials, it first uses the `kevt` field to check that the object's `stage` property is in the list `k8s_audit_stages`. It then uses `configmap` to check the value of the property `objectRef->resource` and see if it equals "configmap". `modify` checks that the value of `verb` is one of `create`,`update`,`patch`. `contains-private-credentials` looks at the configmap contents at `requestObject->data` to see if they contain any of the sensitive strings named in the `contains_private_credentials` macro.
If they do, a falco event is generated:
```
17:18:28.428398080: Warning K8s configmap with private credential (user=minikube-user verb=create configmap=my-config config={"access.properties":"aws_access_key_id = MY-ID\naws_secret_access_key = MY-KEY\n","ui.properties":"color.good=purple\ncolor.bad=yellow\nallow.textmode=true\n"})
```
The output string is used to print essential information about the audit event, including:
* the user `%ka.user.name`, verb `%ka.verb`, and configmap name `%ka.req.configmap.name`
* the full configmap contents `%ka.req.configmap.obj`
# Enabling K8s Audit Logs
In order to enable k8s audit logs, you need to change the arguments to the `kube-apiserver` process to add `--audit-policy-file` and `--audit-webhook-config` arguments and provide files that implement an audit policy/webhook config. Exactly how to do this is somewhat out of the scope of falco's documentation, but we've provided some example files [here](https://github.com/falcosecurity/falco/blob/dev/examples/k8s_audit_config/README.md) that show how we added audit logging to minikube.
**This page can be found at https://falco.org/docs/event-sources/kubernetes-audit/**

51
Reporting-Issues.md

@@ -1,49 +1,2 @@
# Falco's `--support` command line option
When reporting issues, it may be handy to run `falco --support` to collect version, config, and rules information via a single command. Here is some sample output, truncated for clarity:
```
$ falco --version | jq "."
{
"cmdline": "./userspace/falco/falco --support",
"config": "#\n# Copyright (C) 2016-2018 Draios Inc dba Sysdig.\n#\n# This file is part of falco ....\n",
"rules_files": [
{
"name": "/etc/falco/falco_rules.yaml",
"variants": [
{
"content": "... macro: write\n# condition: (syscall.type=write and fd.type in (file, directory))\n#...",
"required_engine_version": 0
}
]
},
{
"name": "/etc/falco/falco_rules.local.yaml",
"variants": [
{
"content": "... ####################\n# Your custom rules!\n####################\n\n# Add new rules, like this one\n#...",
"required_engine_version": 0
}
]
},
{
"name": "/etc/falco/k8s_audit_rules.yaml",
"variants": [
{
"content": "... list: k8s_audit_stages\n items: [\"ResponseComplete\"]\n\n#...",
"required_engine_version": 2
}
]
}
],
"system_info": {
"machine": "x86_64",
"nodename": "ubuntu",
"release": "4.13.0-26-generic",
"sysname": "Linux",
"version": "#29~16.04.2-Ubuntu SMP Tue Jan 9 22:00:44 UTC 2018"
},
"version": "0.14.0"
}
```
# FALCO DOCUMENTATION HAS MOVED
**The [new home](https://falco.org/docs) for Falco Documentation can be found on the [main Falco site](https://falco.org/docs).**

106
Running-Falco.md

@@ -1,108 +1,4 @@
# FALCO DOCUMENTATION HAS MOVED
**The [new home](https://falco.org/docs) for Falco Documentation can be found on the [main Falco site](https://falco.org/docs).**
**This page can be found at https://falco.org/docs/running/**
# 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.
## Reloading Configuration
As of Falco >= 0.13.0, on SIGHUP falco will entirely restart its main loop, closing the device for the kernel module and re-reading all config, etc. from scratch. This can be useful if you want to change the set of rules files, config, etc. on the fly without having to restart falco.
## 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 falcosecurity/falco`
By default, starting the container will attempt to load and/or build the falco kernel module. If you already know the kernel module is loaded and want to skip this step, you can set the environment variable SYSDIG_SKIP_LOAD to 1, for example:
`docker run ... -e SYSDIG_SKIP_LOAD=1 ... falcosecurity/falco`
## Running falco manually
If you'd like to run falco by hand, here's the full usage description for falco:
```
Usage: falco [options]
Options:
-h, --help Print this page
-c Configuration file (default /mnt/sf_mstemm/work/src/falco/falco.yaml, /etc/falco/falco.yaml)
-A Monitor all events, including those with EF_DROP_FALCO flag.
-b, --print-base64 Print data buffers in base64. This is useful for encoding
binary data that needs to be used over media designed to
-d, --daemon Run as a daemon
-D <pattern> Disable any rules matching the regex <pattern>. Can be specified multiple times.
Can not be specified with -t.
-e <events_file> Read the events from <events_file> (in .scap format for sinsp events, or jsonl for
k8s audit events) instead of tapping into live.
-k <url>, --k8s-api=<url>
Enable Kubernetes support by connecting to the API server
specified as argument. E.g. "http://admin:password@127.0.0.1:8080".
The API server can also be specified via the environment variable
FALCO_K8S_API.
-K <bt_file> | <cert_file>:<key_file[#password]>[:<ca_cert_file>], --k8s-api-cert=<bt_file> | <cert_file>:<key_file[#password]>[:<ca_cert_file>]
Use the provided files names to authenticate user and (optionally) verify the K8S API
server identity.
Each entry must specify full (absolute, or relative to the current directory) path
to the respective file.
Private key password is optional (needed only if key is password protected).
CA certificate is optional. For all files, only PEM file format is supported.
Specifying CA certificate only is obsoleted - when single entry is provided
for this option, it will be interpreted as the name of a file containing bearer token.
Note that the format of this command-line option prohibits use of files whose names contain
':' or '#' characters in the file name.
-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.
--list [<source>] List all defined fields. If <source> is provided, only list those fields for
the source <source>. Current values for <source> are "syscall", "k8s_audit"
-m <url[,marathon_url]>, --mesos-api=<url[,marathon_url]>
Enable Mesos support by connecting to the API server
specified as argument. E.g. "http://admin:password@127.0.0.1:5050".
Marathon url is optional and defaults to Mesos address, port 8080.
The API servers can also be specified via the environment variable
FALCO_MESOS_API.
-M <num_seconds> Stop collecting after <num_seconds> reached.
-N When used with --list, only print field names.
-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>
-p <output_format>, --print=<output_format>
Add additional information to each falco notification's output.
With -pc or -pcontainer will use a container-friendly format.
With -pk or -pkubernetes will use a kubernetes-friendly format.
With -pm or -pmesos will use a mesos-friendly format.
Additionally, specifying -pc/-pk/-pm will change the interpretation
of %container.info in rule output fields
See the examples section below for more info.
-P, --pidfile <pid_file> When run as a daemon, write pid to specified file
-r <rules_file> Rules file/directory (defaults to value set in configuration file,
or /etc/falco_rules.yaml). Can be specified multiple times to read
from multiple files/directories.
-s <stats_file> If specified, write statistics related to falco's reading/processing of events
to this file. (Only useful in live mode).
-S <len>, --snaplen=<len>
Capture the first <len> bytes of each I/O buffer.
By default, the first 80 bytes are captured. Use this
option with caution, it can generate huge trace files.
--support Print support information including version, rules files used, etc.
and exit.
-T <tag> Disable any rules with a tag=<tag>. Can be specified multiple times.
Can not be specified with -t.
-t <tag> Only run those rules with a tag=<tag>. Can be specified multiple times.
Can not be specified with -T/-D.
-U,--unbuffered Turn off output buffering to configured outputs. This causes every
single line emitted by falco to be flushed, which generates higher CPU
usage but is useful when piping those outputs into another process
or into a script.
-V,--validate <rules_file> Read the contents of the specified rules(s) file and exit
Can be specified multiple times to validate multiple files.
-v Verbose output.
--version Print version number.
```
**This page can be found at https://falco.org/docs/running/**

115
Supported-Fields.md

@@ -1,117 +1,4 @@
# FALCO DOCUMENTATION HAS MOVED
**The [new home](https://falco.org/docs) for Falco Documentation can be found on the [main Falco site](https://falco.org/docs).**
**This page can be found at https://falco.org/docs/rules/supported-fields/**
# Introduction
Here are the fields supported by falco on top of those supported by [Sysdig](https://github.com/draios/sysdig/wiki/Sysdig-User-Guide#user-content-filtering). You can also see this set of fields via `falco --list=<source>`, with `<source>` being one of the sources below.
# K8s Audit (source `k8s_audit`)
```
----------------------
Field Class: jevt (generic ways to access json events)
jevt.time json event timestamp as a string that includes the nanosecond p
art
jevt.rawtime absolute event timestamp, i.e. nanoseconds from epoch.
jevt.value General way to access single property from json object. The syn
tax is [<json pointer expression>]. The property is returned as
a string
jevt.obj The entire json object, stringified
----------------------
Field Class: ka (Access K8s Audit Log Events)
ka.auditid The unique id of the audit event
ka.stage Stage of the request (e.g. RequestReceived, ResponseComplete, e
tc.)
ka.auth.decision
The authorization decision
ka.auth.reason The authorization reason
ka.user.name The user name performing the request
ka.user.groups The groups to which the user belongs
ka.impuser.name The impersonated user name
ka.verb The action being performed
ka.uri The request URI as sent from client to server
ka.uri.param The value of a given query parameter in the uri (e.g. when uri=
/foo?key=val, ka.uri.param[key] is val).
ka.target.name The target object name
ka.target.namespace
The target object namespace
ka.target.resource
The target object resource
ka.target.subresource
The target object subresource
ka.req.binding.subjects
When the request object refers to a cluster role binding, the s
ubject (e.g. account/users) being linked by the binding
ka.req.binding.subject.has_name
When the request object refers to a cluster role binding, retur
n true if a subject with the provided name exists
ka.req.binding.role
When the request object refers to a cluster role binding, the r
ole being linked by the binding
ka.req.configmap.name
If the request object refers to a configmap, the configmap name
ka.req.configmap.obj
If the request object refers to a configmap, the entire configm
ap object
ka.req.container.image
When the request object refers to a container, the container's
images. Can be indexed (e.g. ka.req.container.image[0]). Withou
t any index, returns the first image
ka.req.container.image.repository
The same as req.container.image, but only the repository part (
e.g. sysdig/falco)
ka.req.container.host_network
When the request object refers to a container, the value of the
hostNetwork flag.
ka.req.container.privileged
When the request object refers to a container, whether or not a
ny container is run privileged. With an index, return whether o
r not the ith container is run privileged.
ka.req.role.rules
When the request object refers to a role/cluster role, the rule
s associated with the role
ka.req.role.rules.apiGroups
When the request object refers to a role/cluster role, the api
groups associated with the role's rules. With an index, return
only the api groups from the ith rule. Without an index, return
all api groups concatenated
ka.req.role.rules.nonResourceURLs
When the request object refers to a role/cluster role, the non
resource urls associated with the role's rules. With an index,
return only the non resource urls from the ith rule. Without an
index, return all non resource urls concatenated
ka.req.role.rules.verbs
When the request object refers to a role/cluster role, the verb
s associated with the role's rules. With an index, return only
the verbs from the ith rule. Without an index, return all verbs
concatenated
ka.req.role.rules.resources
When the request object refers to a role/cluster role, the reso
urces associated with the role's rules. With an index, return o
nly the resources from the ith rule. Without an index, return a
ll resources concatenated
ka.req.service.type
When the request object refers to a service, the service type
ka.req.service.ports
When the request object refers to a service, the service's port
s. Can be indexed (e.g. ka.req.service.ports[0]). Without any i
ndex, returns all ports
ka.req.volume.hostpath
If the request object contains volume definitions, whether or n
ot a hostPath volume exists that mounts the specified path from
the host (...hostpath[/etc]=true if a volume mounts /etc from
the host). The index can be a glob, in which case all volumes a
re considered to find any path matching the specified glob (...
hostpath[/usr/*] would match either /usr/local or /usr/bin)
ka.resp.name The response object name
ka.response.code
The response code
ka.response.reason
The response reason (usually present only for failures)
```
**This page can be found at https://falco.org/docs/rules/supported-fields/**