Merge pull request #108 from draios/0-3-0-docs-changes

Update docs for 0.3.0 release.

CHANGELOG.md

@@ -2,6 +2,68 @@
 
 This file documents all notable changes to Falco. The release numbering uses [semantic versioning](http://semver.org).
 
+## v0.3.0
+
+Released 2016-08-05
+
+### Major Changes
+
+Significantly improved performance, involving changes in the falco and sysdig repositories:
+
+* Reordering a rule condition's operators to put likely-to-fail operators at the beginning and expensive operators at the end. [[#95](https://github.com/draios/falco/pull/95/)] [[#104](https://github.com/draios/falco/pull/104/)]
+* Adding the ability to perform x in (a, b, c, ...) as a single set membership test instead of individual comparisons between x=a, x=b, etc. [[#624](https://github.com/draios/sysdig/pull/624)] [[#98](https://github.com/draios/falco/pull/98/)]
+* Avoid unnecessary string manipulations. [[#625](https://github.com/draios/sysdig/pull/625)]
+* Using `startswith` as a string comparison operator when possible. [[#623](https://github.com/draios/sysdig/pull/623)]
+* Use `is_open_read`/`is_open_write` when possible instead of searching through open flags. [[#610](https://github.com/draios/sysdig/pull/610)]
+* Group rules by event type, which allows for an initial filter using event type before going through each rule's condition. [[#627](https://github.com/draios/sysdig/pull/627)] [[#101](https://github.com/draios/falco/pull/101/)]
+
+All of these changes result in dramatically reduced CPU usage. Here are some comparisons between 0.2.0 and 0.3.0 for the following workloads:
+
+* [Phoronix](http://www.phoronix-test-suite.com/)'s `pts/apache` and `pts/dbench` tests.
+* Sysdig Cloud Kubernetes Demo: Starts a kubernetes environment using docker with apache and wordpress instances + synthetic workloads.
+* [Juttle-engine examples](https://github.com/juttle/juttle-engine/blob/master/examples/README.md) : Several elasticsearch, node.js, logstash, mysql, postgres, influxdb instances run under docker-compose.
+
+| Workload | 0.2.0 CPU Usage | 0.3.0 CPU Usage |
+|----------| --------------- | ----------------|
+| pts/apache | 24% | 7% |
+| pts/dbench | 70% | 5% |
+| Kubernetes-Demo (Running) | 6% | 2% |
+| Kubernetes-Demo (During Teardown) | 15% | 3% |
+| Juttle-examples | 3% | 1% |
+
+As a part of these changes, falco now 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.
+```
+
+
+### Minor Changes
+
+* Several sets of rule cleanups to reduce false positives. [[#95](https://github.com/draios/falco/pull/95/)]
+* Add example of how falco can detect abuse of a badly designed REST API. [[#97](https://github.com/draios/falco/pull/97/)]
+* Add a new output type "program" that writes a formatted event to a configurable program. Each notification results in one invocation of the program. A common use of this output type would be to send an email for every falco notification. [[#105](https://github.com/draios/falco/pull/105/)] [[#99](https://github.com/draios/falco/issues/99)]
+* Add the ability to run falco on all events, including events that are flagged with `EF_DROP_FALCO`. (These events are high-volume, low-value events that are ignored by default to improve performance). [[#107](https://github.com/draios/falco/pull/107/)] [[#102](https://github.com/draios/falco/issues/102)]
+
+### Bug Fixes
+
+* Add third-party jq library now that sysdig requires it. [[#96](https://github.com/draios/falco/pull/96/)]
+
 ## v0.2.0
 
 Released 2016-06-09

README.md

@@ -2,7 +2,7 @@
 
 ####Latest release
 
-**v0.2.0**
+**v0.3.0**
 Read the [change log](https://github.com/draios/falco/blob/dev/CHANGELOG.md)
 
 Dev Branch: [![Build Status](https://travis-ci.org/draios/falco.svg?branch=dev)](https://travis-ci.org/draios/falco)<br />
@@ -21,12 +21,6 @@ Falco can detect and alert on any behavior that involves making Linux system cal
 - A non-device file is written to `/dev`
 - A standard system binary (like `ls`) makes an outbound network connection
 
-This is the initial falco release. Note that much of falco's code comes from
-[sysdig](https://github.com/draios/sysdig), so overall stability is very good
-for an early release. On the other hand performance is still a work in
-progress. On busy hosts and/or with large rule sets, you may see the current
-version of falco using high CPU. Expect big improvements in coming releases.
-
 Documentation
 ---
 [Visit the wiki] (https://github.com/draios/falco/wiki) for full documentation on falco.