improve docs

Readme.md

@@ -14,14 +14,14 @@ Watch a quick video demo of Tracee: <br>
 
 ## Documentation
 
-The full documentation of Tracee is available at [https://aquasecurity.github.io/tracee](https://aquasecurity.github.io/tracee).
+The full documentation of Tracee is available at [https://aquasecurity.github.io/tracee/dev](https://aquasecurity.github.io/tracee). You can use the version selector on top to view documentation for a specific version of Tracee.
 
 ## Quickstart
 
 Before you proceed, make sure you follow the [minimum requirements for running Tracee](https://aquasecurity.github.io/tracee/install/prerequisites.md).
 
 ```bash
-docker run --name tracee --rm --privileged -v /lib/modules/:/lib/modules/:ro -v /usr/src:/usr/src:ro -v /tmp/tracee:/tmp/tracee aquasec/tracee:latest
+docker run --name tracee --rm --privileged -v /lib/modules/:/lib/modules/:ro -v /usr/src:/usr/src:ro -v /tmp/tracee:/tmp/tracee -it aquasec/tracee:latest
 ```
 
 This will run Tracee with default settings and start reporting detections to standard output.  

docs/tracee-ebpf/capture.md

@@ -10,7 +10,36 @@ Tracee can capture the following types of artifacts:
 2. Executed files: Anytime a binary is being executed, the binary file will be captured. If the same binary is executed multiple times, it will be captured just once.
 3. Memory files: Anytime a "memory unpacker" is detected, the suspicious memory region will be captured. This is triggered when memory protection changes from Write+Execute to Write.
 
-To use, `--capture exec`, `--capture mem`, and `--capture write` capture executed, memory, and written files respectively. 
-To filter written files, add a prefix expression like so: `--capture write=/etc/*`. This will capture anything written blow `/etc/`.
+## CLI Options
+
+CLI Option | Description
+--- | ---
+`[artifact:]write[=/path/prefix*]` | capture written files. A filter can be given to only capture file writes whose path starts with some prefix (up to 50 characters). Up to 3 filters can be given.
+`[artifact:]exec` | capture executed files.
+`[artifact:]mem` | capture memory regions that had write+execute (w+x) protection, and then changed to execute (x) only.
+`[artifact:]all` | capture all of the above artifacts.
+`dir:/path/to/dir` | path where tracee will save produced artifacts. the artifact will be saved into an 'out' subdirectory. (default: /tmp/tracee).
+`clear-dir` | clear the captured artifacts output dir before starting (default: false).
+
+(Use this flag multiple times to choose multiple capture options)
+
+## Examples
+
+Capture executed files into the default output directory
+
+```
+--capture exec
+```
+
+Delete /my/dir/out and then capture all supported artifacts into it
+
+```
+--capture all --capture dir:/my/dir --capture clear-dir
+```
+
+Capture files that were written into anywhere under `/usr/bin/` or `/etc/`
+
+```
+--capture write=/usr/bin/* --capture write=/etc/* 
+```
 
-For a complete list of capture options, run `--capture help`.

docs/tracee-ebpf/index.md

@@ -2,21 +2,17 @@
 
 In some cases, you might want to leverage Tracee's eBPF event collection capabilities directly, without involving the detection engine. This might be useful for debugging/troubleshooting/analysis/research/education. In this case you can use Tracee's eBPF collector component, which will start dumping raw data directly into standard output.
 
-[Check out this quick demo of using Tracee's eBPF tracing capabilities](https://youtu.be/WTqE2ae257o)
+[Watch a quick video demo of Tracee's eBPF tracing capabilities](https://youtu.be/WTqE2ae257o)
 
-## Getting Started
+## Quickstart
 
-Before you proceed, make sure you follow the [minimum requirements for running Tracee](../../install/prerequisites).
+Before you proceed, make sure you follow the [minimum requirements for running Tracee](https://aquasecurity.github.io/tracee/install/prerequisites.md).
 
-You can obtain Tracee-eBPF in any of the following ways:
-1. Download from the [GitHub Releases](https://github.com/aquasecurity/tracee/releases) (`tracee.tar.gz`).
-2. Use the docker image from Docker Hub: `aquasec/tracee` with the `trace` sub-command.
-3. Build the executable from source using `make build`. For that you will need additional development tooling.
-4. Build the executable from source in a Docker container which includes all development tooling, using `make build DOCKER=1`.
-
-All of the other setup options and considerations listed under Tracee's Installation section applies to Tracee-eBPF as well.
+```bash
+docker run --name tracee --rm --privileged -v /lib/modules/:/lib/modules/:ro -v /usr/src:/usr/src:ro -v /tmp/tracee:/tmp/tracee -it aquasec/tracee:latest trace
+```
 
-Here's a sample output of running Tracee-eBPF with no additional arguments:
+Here we are running the same `aquasec/tracee` container, but with the `trace` sub-command, which will start just a raw trace (Tracee-eBPF), without the detection engine (Tracee-Rules). Here's a sample output of running with no additional arguments:
 
 ```
 TIME(s)        UID    COMM             PID     TID     RET             EVENT                ARGS
@@ -40,3 +36,13 @@ Each line is a single event collected by Tracee-eBPF, with the following informa
 
 Use the `--help` flag to see a full description of available options. Some flags has specific help sections that can be accessed by passing `help` to the flag, for example `--output help`.
 This section covers some of the more common options.
+
+## Getting Tracee-eBPF
+
+You can obtain Tracee-eBPF in any of the following ways:
+1. Download from the [GitHub Releases](https://github.com/aquasecurity/tracee/releases) (`tracee.tar.gz`).
+2. Use the docker image from Docker Hub: `aquasec/tracee` with the `trace` sub-command.
+3. Build the executable from source using `make build`. For that you will need additional development tooling.
+4. Build the executable from source in a Docker container which includes all development tooling, using `make build DOCKER=1`.
+
+All of the other setup options and considerations listed under Tracee's Installation section applies to Tracee-eBPF as well.

docs/tracee-ebpf/output.md

@@ -1,7 +1,37 @@
 # Output Options
 
-Tracee-eBPF supports different output formats. For example, to choose json output, use `--output json`.
+Control how and where output is printed.
 
-To tell it to write events to a file instead of stdout, use `--output out-file:/path/to/file`.
+## CLI Options
 
-For a full list of output options, run `--output help`.
+CLI Option | Description
+--- | ---
+`[format:]{table,table-verbose,json,gob,gotemplate=/path/to/template}` | output events in the specified format. for gotemplate, specify the mandatory template file
+`out-file:/path/to/file` | write the output to a specified file. the path to the file will be created if not existing and the file will be deleted if existing (deafult: stdout)
+`err-file:/path/to/file` | write the errors to a specified file. the path to the file will be created if not existing and the file will be deleted if existing (deafult: stderr)
+`option:{stack-addresses,detect-syscall,exec-env}` | augment output according to given options (default: none)
+  stack-addresses | include stack memory addresses for each event
+  detect-syscall | when tracing kernel functions which are not syscalls, detect and show the original syscall that called that function
+  exec-env | when tracing execve/execveat, show the environment variables that were used for execution
+
+(Use this flag multiple times to choose multiple capture options)
+
+## Examples
+
+output as json
+
+```
+--output json
+```
+
+output as the provided go template
+
+```
+--output gotemplate=/path/to/my.tmpl
+```
+
+output to `/my/out` and errors to `/my/err`
+
+```
+--output out-file:/my/out err-file:/my/err
+```

docs/tracee-ebpf/trace-options.md

@@ -14,4 +14,179 @@ Event metadata can be used in trace expression as well. For example, to trace on
 A useful trace mode is the `--trace follow` which, if specified, will trace not only processes that match the given trace expressions, but also their child processes.
 For example, the following will trace all the events that originate from zsh shell, including all of the processes that it will spawn: `--trace command=zsh --follow`.
 
-For a complete list of trace options, run `--trace help`.
+## CLI Options
+
+Only events that match all trace expressions will be traced (trace flags are ANDed).
+The following types of expressions are supported:
+
+Numerical expressions which compare numbers and allow the following operators: '=', '!=', '<', '>'.
+Available numerical expressions: uid, pid, mntns, pidns.
+
+String expressions which compares text and allow the following operators: '=', '!='.
+Available string expressions: event, set, uts, comm.
+
+Boolean expressions that check if a boolean is true and allow the following operator: '!'.
+Available boolean expressions: container.
+
+Event arguments can be accessed using 'event_name.event_arg' and provide a way to filter an event by its arguments.
+Event arguments allow the following operators: '=', '!='.
+Strings can be compared as a prefix if ending with '*'.
+
+Event return value can be accessed using 'event_name.retval' and provide a way to filter an event by its return value.
+Event return value expression has the same syntax as a numerical expression.
+
+Non-boolean expressions can compare a field to multiple values separated by ','.
+Multiple values are ORed if used with equals operator '=', but are ANDed if used with any other operator.
+
+The field 'container' and 'pid' also support the special value 'new' which selects new containers or pids, respectively.
+
+The field 'set' selects a set of events to trace according to predefined sets, which can be listed by using the 'list' flag.
+
+The special 'follow' expression declares that not only processes that match the criteria will be traced, but also their descendants.
+
+Note: some of the above operators have special meanings in different shells. To 'escape' those operators, please use single quotes, e.g.: 'uid>0'
+
+## Examples
+
+only trace events from new processes
+
+```
+--trace pid=new
+```
+
+only trace events from pid 510 or pid 1709
+
+```
+--trace pid=510,1709
+```
+
+only trace events from pid 510 or pid 1709 (same as above)
+
+```
+--trace p=510 --trace p=1709
+```
+
+only trace events from newly created containers
+
+```
+--trace container=new
+```
+
+only trace events from containers
+
+```
+--trace container
+```
+
+only trace events from containers (same as above)
+
+```
+--trace c
+```
+
+only trace events from the host
+
+```
+--trace '!container'
+```
+
+only trace events from uid 0
+
+```
+--trace uid=0
+```
+
+only trace events from mntns id 4026531840
+
+```
+--trace mntns=4026531840
+```
+
+only trace events from pidns id not equal to 4026531840
+
+```
+--trace pidns!=4026531836
+```
+
+only trace events from uids greater than 0
+
+```
+--trace 'uid>0'
+```
+
+only trace events from pids between 0 and 1000
+
+```
+--trace 'pid>0' --trace 'pid<1000'
+```
+
+only trace events from uids greater than 0 but not 1000
+
+```
+--trace 'u>0' --trace u!=1000
+```
+
+only trace execve and open events
+
+```
+--trace event=execve,open
+```
+
+only trace events prefixed by "open"
+
+```
+--trace event=open*
+```
+
+don't trace events prefixed by "open" or "dup"
+
+```
+--trace event!=open*,dup*
+```
+
+trace all file-system related events
+```
+--trace set=fs
+```
+
+trace all file-system related events, but not open(at)
+
+```
+--trace s=fs --trace e!=open,openat
+```
+
+don't trace events from uts name ab356bc4dd554
+
+```
+--trace uts!=ab356bc4dd554
+```
+
+only trace events from ls command
+
+```
+--trace comm=ls
+```
+
+only trace 'close' events that have 'fd' equals 5
+
+```
+--trace close.fd=5
+```
+
+only trace 'openat' events that have 'pathname' prefixed by "/tmp"
+
+```
+--trace openat.pathname=/tmp*
+```
+
+don't trace 'openat' events that have 'pathname' equals /tmp/1 or /bin/ls
+
+```
+--trace openat.pathname!=/tmp/1,/bin/ls
+```
+
+trace all events that originated from bash or from one of the processes spawned by bash
+
+```
+--trace comm=bash --trace follow
+```

tracee-ebpf/Readme.md

@@ -2,21 +2,21 @@
 
 In some cases, you might want to leverage Tracee's eBPF event collection capabilities directly, without involving the detection engine. This might be useful for debugging/troubleshooting/analysis/research/education. In this case you can use Tracee's eBPF collector component, which will start dumping raw data directly into standard output.
 
-[Check out this quick demo of using Tracee's eBPF tracing capabilities](https://youtu.be/WTqE2ae257o)
+[Watch a quick video demo of Tracee's eBPF tracing capabilities](https://youtu.be/WTqE2ae257o)
 
-## Getting Started
+## Documentation
 
-Before you proceed, make sure you follow the [minimum requirements for running Tracee](https://aquasecurity.github.io/tracee/install/prerequisites.md).
+The full documentation of Tracee's eBPF tracing is available at [https://aquasecurity.github.io/tracee/dev/tracee-ebpf/](https://aquasecurity.github.io/tracee/dev/tracee-ebpf/). You can use the version selector on top to view documentation for a specific version of Tracee.
 
-You can obtain Tracee-eBPF in any of the following ways:
-1. Download from the [GitHub Releases](https://github.com/aquasecurity/tracee/releases) (`tracee.tar.gz`).
-2. Use the docker image from Docker Hub: `aquasec/tracee` with the `trace` sub-command.
-3. Build the executable from source using `make build`. For that you will need additional development tooling.
-4. Build the executable from source in a Docker container which includes all development tooling, using `make build DOCKER=1`.
+## Quickstart
 
-All of the other setup options and considerations listed under Tracee's Installation section applies to Tracee-eBPF as well.
+Before you proceed, make sure you follow the [minimum requirements for running Tracee](https://aquasecurity.github.io/tracee/install/prerequisites.md).
+
+```bash
+docker run --name tracee --rm --privileged -v /lib/modules/:/lib/modules/:ro -v /usr/src:/usr/src:ro -v /tmp/tracee:/tmp/tracee -it aquasec/tracee:latest trace
+```
 
-Here's a sample output of running Tracee-eBPF with no additional arguments:
+Here we are running the same `aquasec/tracee` container, but with the `trace` sub-command, which will start just a raw trace (Tracee-eBPF), without the detection engine (Tracee-Rules). Here's a sample output of running with no additional arguments:
 
 ```
 TIME(s)        UID    COMM             PID     TID     RET             EVENT                ARGS
@@ -40,3 +40,13 @@ Each line is a single event collected by Tracee-eBPF, with the following informa
 
 Use the `--help` flag to see a full description of available options. Some flags has specific help sections that can be accessed by passing `help` to the flag, for example `--output help`.
 This section covers some of the more common options.
+
+## Getting Tracee-eBPF
+
+You can obtain Tracee-eBPF in any of the following ways:
+1. Download from the [GitHub Releases](https://github.com/aquasecurity/tracee/releases) (`tracee.tar.gz`).
+2. Use the docker image from Docker Hub: `aquasec/tracee` with the `trace` sub-command.
+3. Build the executable from source using `make build`. For that you will need additional development tooling.
+4. Build the executable from source in a Docker container which includes all development tooling, using `make build DOCKER=1`.
+
+All of the other setup options and considerations listed under Tracee's Installation section applies to Tracee-eBPF as well.