Filling in initial rev of wiki.

Most of the content comes from the README.md. A separate commit to the
falco repo will remove the redundant content.

.gitignore

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

About-Falco.md

@@ -0,0 +1,49 @@
+# About Falco
+
+Sysdig Falco is a behavioral activity monitor designed to detect anomalous activity in your applications. Powered by sysdig’s system call capture infrastructure, falco lets you continuously monitor and detect container, application, host, and network activity... all in one place, from one source of data, with one set of rules.
+
+## What kind of behaviors can Falco detect?
+
+Falco can detect and alert on any behavior that involves making Linux system calls. Thanks to Sysdig's core decoding and state tracking functionality, falco alerts can be triggered by the use of specific system calls, their arguments, and by properties of the calling process. For example, you can easily detect things like:
+- A shell is run inside a container
+- A server process spawns a child process of an unexpected type
+- Unexpected read of a sensitive file (like `/etc/shadow`)
+- A non-device file is written to `/dev`
+- A standard system binary (like `ls`) makes an outbound network connection
+
+## How you use it
+
+Falco is deployed as a long-running daemon. You can install it as a debian/rpm
+package on a regular host or container host, or you can deploy it as a
+container.
+
+Falco is configured via a rules file defining the behaviors and events to
+watch for, and a general configuration file. Rules are expressed in a
+high-level, human-readable language. We've provided a sample rule file
+`./rules/falco_rules.yaml` as a starting point - you can (and will likely
+want!) to adapt it to your environment.
+
+When developing rules, one helpful feature is falco's ability to read trace
+files saved by sysdig. This allows you to "record" the offending behavior
+once, and replay it with falco as many times as needed while tweaking your
+rules.
+
+Once deployed, falco uses the Sysdig kernel module and userspace libraries to
+watch for any events matching one of the conditions defined in the rule
+file. If a matching event occurs, a notification is written to the the
+configured output(s).
+
+## Falco Alerts
+
+When Falco detects suspicious behavior, it sends alerts via one or more of the following channels:
+
+* Writing to standard error
+* Writing to a file
+* Writing to syslog
+
+More details on these alerts are described [here](Falco Alerts).
+
+
+
+
+

Configuration.md

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

Falco-Alerts.md

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

Falco-Configuration.md

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

Falco-Examples.md

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

Falco-Rules.md

@@ -0,0 +1,58 @@
+# Rules
+
+_Call for contributions: If you come up with additional rules which you'd like to see in the core repository - PR welcome!_
+
+A falco rules file is a [YAML](http://www.yaml.org/start.html) file containing two kinds of elements: *rules* and *macros*. Rules consiste of a *condition* under which an alert should be generated and a *output string* to send with the alert.
+
+Macros are simply rule condition snippets that can be re-used inside rules and other macros, providing a way to factor out and name common patterns.
+
+## Rules
+
+A Rule is a node containing the following keys:
+
+* _rule_: a short unique name for the rule
+* _desc_: a longer description of what the rule detects
+* _output_ and _priority_: The output format specifies the message that should be output if a matching event occurs, and follows the Sysdig [output format syntax](http://www.sysdig.org/wiki/sysdig-user-guide/#output-formatting). The priority is a case-insensitive representation of severity and should be one of "emergency", "alert", "critical", "error", "warning", "notice", "informational", or "debug".
+
+## Conditions
+
+The key part of a rule is the _condition_ field. A condition is simply a boolean predicate on sysdig events.
+Conditions are expressed using the Sysdig [filter syntax](http://www.sysdig.org/wiki/sysdig-user-guide/#filtering). Any Sysdig filter is a valid falco condition (with the caveat of certain excluded system calls, discussed below). In addition, falco conditions can contain macro terms--this capability is not present in Sysdig syntax.
+
+Here's an example of a condition that alerts whenever a bash shell is run inside a container:
+
+`container.id != host and proc.name = bash`
+
+The first clause checks that the event happened in a container (sysdig events have a `container` field that is equal to "host" if the event happened on a regular host). The second clause checks that the process name is `bash`. Note that this condition does not even include a clause with system call! It only uses event metadata. As such, if a bash shell does start up in a container, falco will output events for every syscall that is done by that shell.
+
+_Tip: If you're new to sysdig and unsure what fields are available, run `sysdig -l` to see the list of supported fields._
+
+A complete rule using the above condition might be:
+
+```yaml
+- rule: shell_in_container
+  desc: notice shell activity within a container
+  condition: container.id != host and proc.name = bash
+  output: "shell in a container (user=%user.name container_id=%container.id container_name=%container.name shell=%proc.name parent=%proc.pname cmdline=%proc.cmdline)
+  priority: WARNING
+```
+
+## Macros
+
+As noted above, macros provide a way to define common sub-portions of rules in a reusable way. As a very simple example, if we had many rules for events happening in containers, we might to define a `in_container` macro:
+
+```yaml
+- macro: in_container
+  condition: container.id != host
+```
+
+With this macro defined, we can then rewrite the above rule's condition as `in_container and proc.name = bash`.
+
+For many more examples of rules and macros, please take a look `rules/falco_rules.yaml`.
+
+## Ignored system calls
+
+For performance reasons, some system calls are currently discarded before falco processing. The current list is:
+`clock_getres,clock_gettime,clock_nanosleep,clock_settime,close,epoll_create,epoll_create1,epoll_ctl,epoll_pwait,epoll_wait,eventfd,fcntl,fcntl64,fstat,fstat64,fstatat64,fstatfs,fstatfs64,futex,getitimer,gettimeofday,ioprio_get,ioprio_set,llseek,lseek,lstat,lstat64,mmap,mmap2,munmap,nanosleep,poll,ppoll,pread64,preadv,procinfo,pselect6,pwrite64,pwritev,read,readv,recv,recvfrom,recvmmsg,recvmsg,sched_yield,select,send,sendfile,sendfile64,sendmmsg,sendmsg,sendto,setitimer,settimeofday,shutdown,splice,stat,stat64,statfs,statfs64,switch,tee,timer_create,timer_delete,timerfd_create,timerfd_gettime,timerfd_settime,timer_getoverrun,timer_gettime,timer_settime,wait4,write,writev`
+
+

Home.md

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

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

@@ -0,0 +1,57 @@
+## Installation
+
+## Scripted install
+
+To install falco automatically in one step, simply run the following command as root or with sudo:
+
+`curl -s https://s3.amazonaws.com/download.draios.com/stable/install-falco | sudo bash`
+
+## Package install
+
+### RHEL
+
+- Trust the Draios GPG key and configure the yum repository
+```
+rpm --import https://s3.amazonaws.com/download.draios.com/DRAIOS-GPG-KEY.public
+curl -s -o /etc/yum.repos.d/draios.repo http://download.draios.com/stable/rpm/draios.repo
+```
+- Install the EPEL repository
+
+Note: The following command is required only if DKMS is not available in the distribution. You can verify if DKMS is available with yum list dkms
+
+`rpm -i http://mirror.us.leaseweb.net/epel/6/i386/epel-release-6-8.noarch.rpm`
+
+- Install kernel headers
+
+Warning: The following command might not work with any kernel. Make sure to customize the name of the package properly
+
+`yum -y install kernel-devel-$(uname -r)`
+
+- Install falco
+
+`yum -y install falco`
+
+
+To uninstall, just do `yum erase falco`.
+
+### Debian
+
+- Trust the Draios GPG key, configure the apt repository, and update the package list
+
+```
+curl -s https://s3.amazonaws.com/download.draios.com/DRAIOS-GPG-KEY.public | apt-key add -
+curl -s -o /etc/apt/sources.list.d/draios.list http://download.draios.com/stable/deb/draios.list
+apt-get update
+```
+
+- Install kernel headers
+
+Warning: The following command might not work with any kernel. Make sure to customize the name of the package properly
+
+`apt-get -y install linux-headers-$(uname -r)`
+
+- Install falco
+
+`apt-get -y install falco`
+
+To uninstall, just do `apt-get remove falco`.

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

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

How-to-Install-Falco-using-Containers.md

@@ -0,0 +1,41 @@
+# How to Install Falco using Containers
+
+## Container install (general)
+
+If you have full control of your host operating system, then installing falco using the normal installation method is the recommended best practice. This method allows full visibility into all containers on the host OS. No changes to the standard automatic/manual installation procedures are required.
+
+However, falco can also run inside a Docker container. To guarantee a smooth deployment, the kernel headers must be installed in the host operating system, before running Falco.
+
+This can usually be done on Debian-like distributions with:
+`apt-get -y install linux-headers-$(uname -r)`
+
+Or, on RHEL-like distributions:
+`yum -y install kernel-devel-$(uname -r)`
+
+Falco can then be run with:
+
+```
+docker pull sysdig/falco
+docker run -i -t --name falco --privileged -v /var/run/docker.sock:/host/var/run/docker.sock -v /dev:/host/dev -v /proc:/host/proc:ro -v /boot:/host/boot:ro -v /lib/modules:/host/lib/modules:ro -v /usr:/host/usr:ro sysdig/falco
+```
+
+## Container install (CoreOS)
+
+The recommended way to run falco on CoreOS is inside of its own Docker container using the install commands in the paragraph above. This method allows full visibility into all containers on the host OS.
+
+This method is automatically updated, includes some nice features such as automatic setup and bash completion, and is a generic approach that can be used on other distributions outside CoreOS as well.
+
+However, some users may prefer to run falco in the CoreOS toolbox. While not the recommended method, this can be achieved by installing Falco inside the toolbox using the normal installation method, and then manually running the sysdig-probe-loader script:
+
+```
+toolbox --bind=/dev --bind=/var/run/docker.sock
+curl -s https://s3.amazonaws.com/download.draios.com/stable/install-falco | bash
+sysdig-probe-loader
+```
+
+
+
+## Building and running falco locally from source
+Building falco requires having `cmake` and `g++` installed.
+
+

Running-Falco.md

@@ -0,0 +1,34 @@
+# Running Falco
+
+Falco is intended to be run as a service. But for experimentation and designing/testing rulesets, you will likely want to run it manually from the command-line.
+
+## Running falco as a service (after installing package)
+
+`service falco start` will start the falco service. The default configuration logs events to syslog.
+
+## Running falco in a container
+
+`docker run -i -t --name falco --privileged -v /var/run/docker.sock:/host/var/run/docker.sock -v /dev:/host/dev -v /proc:/host/proc:ro -v /boot:/host/boot:ro -v /lib/modules:/host/lib/modules:ro -v /usr:/host/usr:ro sysdig/falco`
+
+## Running falco manually
+
+If you'd like to run falco by hand, here's the full usage description for falco:
+
+```
+$ ./userspace/falco/falco --help
+Usage: falco [options]
+
+Options:
+ -h, --help                    Print this page
+ -c                            Configuration file (default /mnt/sf_mstemm/work/src/falco/falco.yaml, /etc/falco.yaml)
+ -o, --option <key>=<val>      Set the value of option <key> to <val>. Overrides values in configuration file.
+                               <key> can be a two-part <key>.<subkey>
+ -d, --daemon                  Run as a daemon
+ -p, --pidfile <pid_file>      When run as a daemon, write pid to specified file
+ -e <events_file>              Read the events from <events_file> (in .scap format) instead of tapping into live.
+ -r <rules_file>               Rules file (defaults to value set in configuration file, or /etc/falco_rules.yaml).
+ -L                            Show the name and description of all rules and exit.
+ -l <rule>                     Show the name and description of the rule with name <rule> and exit.
+```
+
+