diff --git a/docs/contributing/architecture.md b/docs/contributing/architecture.md deleted file mode 100644 index 5b9d1ec5b89a..000000000000 --- a/docs/contributing/architecture.md +++ /dev/null @@ -1,80 +0,0 @@ -# Architecture - -## Tracee Architecture Overview - -![Architecture](../images/architecture.png) - -!!! Overview Note - - 1. Kernel eBPF programs **GENERATE** Tracee Events to Userland: - 1. Tracepoints - 1. Probes - 1. Traffic Control Hooks - - 1. Userland events are **COLLECTED and ENRICHED** with more information: - 1. Kernel Events (Syscalls, Tracepoints, Kprobes) - 1. OS Events (Running Containers, ...) - 1. Derived (from other) Events - 1. Network Events - - 1. **DETECT** patterns based on existing signatures: - 1. [OPA/Rego signatures](../docs/events/custom/rego.md) - 1. [Golang signatures](../docs/events/custom/golang.md) - - 1. Let other tools to **CONSUME** detection events: - 1. [Filters](../docs/filters/filtering.md) - - 1. **ENFORCE** - 1. Work in Progress - -## Tracee Pipeline Concept - -![Tracee Pipeline](../images/tracee-pipeline-overview.png) - -!!! Pipeline Warning - - 1. Multiple CPUs constantly generate events from the eBPF programs running - inside the kernel (inside an eBPF VM). - - 1. The eBPF programs are executed whenever the kernel (or network) hooks - they're attached to are triggered. - - 1. eBPF programs decide whether they should submit the events to - **tracee** or not, based on given filters. - - 1. Those events are sent to **libbpfgo** through a [shared memory ring buffer] - mechanism (called **perfbuffer**). - - 1. **libbpfgo** sends collected events to tracee through **golang - channels**. - - 1. **tracee** parses received events and does multiple things: - - 1. [parse events for argument type] conversions if requested - 1. [enriches the events] that need enrichment (containers, network, processes) - 1. capture artifacts from collected events into external files - - 1. **tracee** writes events to **tracee-rules** through a mechanism - called **printer**. - - 1. **tracee-rules** receives events and evaluate them using either [golang] - or [rego] signatures. - - 1. Golang signatures are faster and do pretty much anything the language - allows. They might connect (or have cached) external data sources to - evaluate events, for example. - - 1. Detections are [spit out] from **tracee-rules** if evaluations are - positive. - - > This mechanism is what we call the **tracee pipeline**: to receive events - > from the kernel into userland (**tracee**), then to parse and enrich - > those events and to submit them to **tracee-rules** for it to evaluate - > them looking for detection patterns described as **signatures**. - -[parse events for argument type]: ./../docs/outputs/output-options.md -[enriches the events]: ./../docs/integrating/container-engines.md -[golang]: ./../docs/events/custom/golang.md -[rego]: ./../docs/events/custom/rego.md -[spit out]: ./../docs/integrating/webhook.md - diff --git a/docs/docs/config/overview.md b/docs/docs/config/overview.md deleted file mode 100644 index b3e4f9d44162..000000000000 --- a/docs/docs/config/overview.md +++ /dev/null @@ -1,64 +0,0 @@ -# Config - -## Configuring Tracee with the `--config` Flag - -The `--config` flag allows you to specify global configuration options for Tracee by providing a configuration file in YAML or JSON format, among other supported formats. The `--config` flag can be used to set any flag that is available through the command line interface (CLI), except for a few reserved flags. - -## Usage - -To use the `--config` flag, you need to provide the path to the configuration file. For example, if you have a YAML configuration file located at /path/to/tracee-config.yaml, you can load it with the following command: - -```console -tracee --config /path/to/tracee-config.yaml -``` - -You can also override specific configuration options by passing additional flags on the command line. For example, the following command overrides the log level set in the configuration file with info: - -```console -sudo ./dist/tracee --config ./examples/config/global_config.yaml --log info -``` - -!!! Note - Any flags specified on the command line will take precedence over the values specified in the configuration file. - -## Configuration File Format - -The configuration file can be in any format supported by the [viper](https://github.com/spf13/viper) library, which includes YAML, JSON, TOML, INI, HCL and Java properties. The configuration file should contain a mapping of flag names to their values. For example, to output aggregated debug level logs every default seconds `--log debug --log aggregate`, you would add the following to your configuration file: - -```yaml -log: - - debug - - aggregate -``` - -Or in a structured format: - -```yaml -log: - level: debug - aggregate: - enabled: true -``` - -## Reserved Flags - -There are a few flags that are reserved for the CLI and cannot be set through the configuration file. These include: -`--config`, `--capture`, `--policy`, `--scope`, and `--events`. - -## Example Configuration Files - -To help you get started with configuring Tracee using the `--config` flag, we've provided two example configuration files in the `examples/config` directory of the Tracee repository: - -- `examples/config/global_config.yaml`: This file contains an example configuration in YAML format. -- `examples/config/global_config_cli.yaml`: This file contains the same example configuration as global_config.yaml, but using cli flags (not structured). -- `examples/config/global_config.json`: This file contains the same example configuration as global_config_cli.yaml, but in JSON format. - -These example files demonstrate how you can set various configuration options using the `--config` flag. You can use these files as a starting point for your own configuration, or as a reference for the available configuration options. - -To use one of the example configuration files with Tracee, simply pass the path to the file as an argument to the -`-config` flag. For example, to use the YAML configuration file, you could run the following command: - -```console -tracee --config examples/config/global_config.yaml -``` - -By starting with one of these example files and modifying it to suit your needs, you can quickly get up and running with Tracee's configuration options. \ No newline at end of file diff --git a/docs/docs/data-sources/containers.md b/docs/docs/data-sources/containers.md index c88a71edcf6c..1a4d733b63be 100644 --- a/docs/docs/data-sources/containers.md +++ b/docs/docs/data-sources/containers.md @@ -1,6 +1,6 @@ # Containers Data Source -The [container enrichment](../integrating/container-engines.md) feature gives Tracee the ability to extract details about active containers and link this information to the events it captures. +The [container enrichment](../install/container-engines.md) feature gives Tracee the ability to extract details about active containers and link this information to the events it captures. The [data source](./overview.md) feature makes the information gathered from active containers accessible to signatures. When an event is captured and triggers a signature, that signature can retrieve information about the container using its container ID, which is bundled with the event being analyzed by the signature. diff --git a/docs/docs/deep-dive/caching-events.md b/docs/docs/deep-dive/caching-events.md index a785ea6a450a..b36c81bc072a 100644 --- a/docs/docs/deep-dive/caching-events.md +++ b/docs/docs/deep-dive/caching-events.md @@ -8,13 +8,8 @@ caching options you may execute: man tracee-cache ``` --> -!!! Read Important - Before continuing, please read the [architecture page], in order to - understand the [tracee pipeline] concept, AND the [performance page], to - understand possible pain points. -[architecture page]: ../../contributing/architecture.md -[tracee pipeline]: ../../contributing/architecture.md#tracee-pipeline-concept + ![Tracee Cache](../../images/tracee-cache.png) diff --git a/docs/docs/deep-dive/ksyms.md b/docs/docs/deep-dive/ksyms.md index 8c3b4a69623e..53d40958a4e0 100644 --- a/docs/docs/deep-dive/ksyms.md +++ b/docs/docs/deep-dive/ksyms.md @@ -1,6 +1,6 @@ # About Kernel symbols -As explained in the [prerequisites](./install/prerequisites.md) doc, Tracee +As explained in the [prerequisites](../install/prerequisites.md) doc, Tracee needs the kernel symbol table for some operations. A Linux kernel might lack the `/proc/kallsyms` file due to: diff --git a/docs/docs/events/custom/analyze.md b/docs/docs/events/custom/analyze.md deleted file mode 100644 index ebf2e5a38b58..000000000000 --- a/docs/docs/events/custom/analyze.md +++ /dev/null @@ -1,16 +0,0 @@ -# Analyze - -The tracee subcommand `analyze` allows you to execute behavior signatures on past data. -For example, you can collect the ptrace event into one node using the following command: - -``` -tracee --events=ptrace --output=json:events.json -``` - -Then, on another node, you can check if the behavior signature for anti-debugging was triggered using the following command: - -``` -tracee analyze --events=anti_debugging events.json -``` - -The `analyze` command can also be used to test new signatures from the collected past data. You can run tracee on a node, collect several events, and based on the collected events, create your behavior signature. Afterward, you can test if the signature would be triggered using the `analyze` command. diff --git a/docs/docs/events/index.md b/docs/docs/events/index.md new file mode 100644 index 000000000000..609e41a0b518 --- /dev/null +++ b/docs/docs/events/index.md @@ -0,0 +1,64 @@ +# Events + +Events refer to the system activity that tracee monitors. There are two types of events, built-in events that are part of Tracee and custom events, which are user defined events. + +As part of built-in events, there are six types of events: + +* syscalls +* network +* security +* lsm +* containers +* misc + +This section documents all of the different events that Tracee exposes. + +## Configuring Tracee Events + +Events are defined in the [Policy](../policies/index.md) YAML manifest. + +Tracing the `execve` events in a [policy](../policies/index.md): + +``` +apiVersion: tracee.aquasec.com/v1beta1 +kind: Policy +metadata: + name: sample-policy + annotations: + description: traces execve events +spec: + scope: + - global + rules: + - event: execve +``` + +If no event is passed with [filters] or [policies], tracee will start with a set of default events. + +Please head over to the [Tracee usage](../policies/usage/kubernetes.md) documentation for more information on configuring events. + +### Event Sets + +Events can be part of a set. For example, `default`, `network_events`, `syscalls`. +We can ask Tracee to trace a full set, or sets, instead of passing event by event, for example: + +``` +apiVersion: tracee.aquasec.com/v1beta1 +kind: Policy +metadata: + name: sample-policy + annotations: + description: traces execve events +spec: + scope: + - global + rules: + - event: syscalls +``` + +## Video Content + +If you are curious to learn more about the Tracee Events architecture and related decision making, then have a look at the following video Q&A: + +Everything is an Event in Tracee + [![Watch the video](../../images/liveqa.png)](https://www.youtube.com/live/keqVe4d71uk?si=OTbVxgWsFBtdqEMW) diff --git a/docs/docs/events/overview.md b/docs/docs/events/overview.md deleted file mode 100644 index 1259a20da528..000000000000 --- a/docs/docs/events/overview.md +++ /dev/null @@ -1,150 +0,0 @@ -# Events - -This section documents all of the different events that Tracee exposes. - -## Everything is an event - -Tracee uses eBPF technology to tap into your system and give you access to hundreds of events that help you understand how your system behaves. The events can be specified either through CLI with [filters] or with [policies]. - -eg: - -Tracing `execve` events with [filters]: - -```console -tracee --events execve -``` - -Tracing `execve` events with [policies]: - -``` -cat <sample_policy.yaml -apiVersion: tracee.aquasec.com/v1beta1 -kind: Policy -metadata: - name: sample-policy - annotations: - description: traces execve events -spec: - scope: - - global - rules: - - event: execve -EOF -``` - -``` -tracee --policies sample_policy.yaml -``` - -If no event is passed with [filters] or [policies], tracee will start with a set of default events. -Below a list of tracee default events. - -### Default events - -Name | Sets | --------|-----------------------------------| -stdio_over_socket | [signatures default] | -k8s_api_connection |[signatures default] | -aslr_inspection | [signatures default] | -proc_mem_code_injection | [signatures default] | -docker_abuse | [signatures default] | -scheduled_task_mod | [signatures default] | -ld_preload | [signatures default] | -cgroup_notify_on_release | [signatures default] | -default_loader_mod | [signatures default] | -sudoers_modification | [signatures default] | -sched_debug_recon | [signatures default] | -system_request_key_mod | [signatures default] | -cgroup_release_agent | [signatures default] | -rcd_modification | [signatures default] | -core_pattern_modification | [signatures default] | -proc_kcore_read | [signatures default] | -proc_mem_access | [signatures default] | -hidden_file_created | [signatures default] | -anti_debugging | [signatures default] | -ptrace_code_injection | [signatures default] | -process_vm_write_inject | [signatures default] | -disk_mount | [signatures default] | -dynamic_code_loading | [signatures default] | -fileless_execution | [signatures default] | -illegitimate_shell | [signatures default] | -kernel_module_loading | [signatures default] | -k8s_cert_theft | [signatures default] | -proc_fops_hooking | [signatures default] | -syscall_hooking | [signatures default] | -dropped_executable | [signatures default] | -creat | [default syscalls fs fs_file_ops] | -chmod | [default syscalls fs fs_file_attr] | -fchmod | [default syscalls fs fs_file_attr] | -chown | [default syscalls fs fs_file_attr] | -fchown | [default syscalls fs fs_file_attr] | -lchown | [default syscalls fs fs_file_attr]| -ptrace | [default syscalls proc] | -setuid | [default syscalls proc proc_ids] | -setgid | [default syscalls proc proc_ids] | -setpgid | [default syscalls proc proc_ids] | -setsid | [default syscalls proc proc_ids] | -setreuid | [default syscalls proc proc_ids] | -setregid | [default syscalls proc proc_ids] | -setresuid | [default syscalls proc proc_ids] | -setresgid | [default syscalls proc proc_ids] | -setfsuid | [default syscalls proc proc_ids] | -setfsgid | [default syscalls proc proc_ids] | -init_module | [default syscalls system system_module] | -fchownat | [default syscalls fs fs_file_attr] | -fchmodat | [default syscalls fs fs_file_attr] | -setns | [default syscalls proc] | -process_vm_readv | [default syscalls proc] | -process_vm_writev | [default syscalls proc] | -finit_module | [default syscalls system system_module] | -memfd_create | [default syscalls fs fs_file_ops] | -move_mount | [default syscalls fs] | -sched_process_exec | [default proc] | -security_inode_unlink | [default lsm_hooks fs fs_file_ops] | -security_socket_connect | [default lsm_hooks net net_sock] | -security_socket_accept | [default lsm_hooks net net_sock] | -security_socket_bind | [default lsm_hooks net net_sock] | -security_sb_mount | [default lsm_hooks fs] | -container_create | [default containers] | -container_remove | [default containers] | -net_packet_icmp | [default network_events] | -net_packet_icmpv6 | [default network_events] | -net_packet_dns_request | [default network_events] | -net_packet_dns_response | [default network_events] | -net_packet_http_request | [default network_events] | -net_packet_http_response | [default network_events] | - -### Sets - -Events can be part of a set, for example on the table above we can see a few sets like `default`, `network_events`, `syscalls`. -We can ask tracee to trace a full set, or sets, instead of passing event by event, for example: - -```console -tracee --events syscalls -``` -or - -```console -tracee --events syscalls,network_events -``` - - -## Read in CLI - -You can view the list of available events and their schema by running `tracee list` command. - -## Read in AVD - -[Aqua Vulnerability Database (AVD)](https://avd.aquasec.com) is a public index of all security information that can be reported across all of Aqua's products and tools. As such, it also contains entries about Tracee security events. The AVD entries on runtime security are generated from the [detection signatures](https://github.com/aquasecurity/tracee/tree/main/signatures) and are organized by MITRE ATT&CK categorization. Browse at [avd.aquasec.com/tracee](https://avd.aquasec.com/tracee/). - -👈 Please use the side-navigation on the left in order to browse the different topics. - -[filters]: ../../filters/filtering -[policies]: ../../policies - -## Video Content - -If you are curious to learn more about the Tracee Events architecture and related decision making, then have a look at the following video Q&A: - -Everything is an Event in Tracee - [![Watch the video](../../images/liveqa.png)](https://www.youtube.com/live/keqVe4d71uk?si=OTbVxgWsFBtdqEMW) diff --git a/docs/docs/filters/filtering.md b/docs/docs/filters/filtering.md deleted file mode 100644 index 1070dedc2356..000000000000 --- a/docs/docs/filters/filtering.md +++ /dev/null @@ -1,211 +0,0 @@ -# Tracing Event Filtering - -```console -./dist/tracee man -./dist/tracee man scope -./dist/tracee man events -``` - -Tracee output might become too hard to consume when tracing all the events from -a system. Luckily, Tracee has a powerful mechanism to accurately filter just the -information that is relevant to the user using the `--scope` and `--events` flags. - -With those command line flags you define expressions that tell **tracee** -what you are interested in based on event metadata filtering -capabilities. Only events that match given criteria will be traced. - -!!! Tip - You can filter events by most of the visible fields from Tracee events. - -## Initial Example - -All the examples bellow this item can be executed with the following tracee -prefix command: - -```console -sudo ./dist/tracee \ - --output json \ - --scope comm=bash \ - --scope follow - --output option:parse-arguments \ - -``` - -This will allow you to test the filtering rules by executing a new process in -any running shell and might serve as a good indicative if your filter works as -expected. - -## Filters and Operators - -1. **Event** and **Scope** `(Operators: event "-" and scope "follow". Prefix/Suffix: *)` - - ```text - 1) --events openat - 2) --events execve,open - 3) --events 'open*' - 4) --events '-open*,-dup*' - 5) --events 'fs,-dup*' - 6) --scope follow - ``` - - !!! Note - The event "-" remove operator will work like it means. - !!! Note - The event 'fs,-dup*' will select all file-system events but dup* events. - !!! Note - The "follow" operator will make tracee follow all newly created - child processes of the parents being filtered. - -1. **Event Arguments** `(Operators: =, !=. Prefix/Suffix: *)` - - ```text - 1) --events openat --events openat.args.pathname=/etc/shadow - 2) --events openat --events openat.args.pathname='/tmp*' - 3) --events openat --events openat.args.pathname!=/tmp/1,/bin/ls - ``` - - !!! Note - Multiple values are ORed if used with = operator - But ANDed if used with any other operator. - !!! Tip - As a syntax sugar, the event options filter can be set without the `--events openat`, - since by `--events openat.args.pathname=/etc/shadow` tracee infers that openat must be - filtered. - -1. **Event Return Code** `(Operators: =, !=, <, >)` - - ```text - 1) --events openat.args.pathname=/etc/shadow --events 'openat.retval>0' - 2) --events openat.args.pathname=/etc/shadow --events 'openat.retval<0' - ``` - - !!! Tip - Try `cat /etc/shadow` as a regular use and filter for `retval<0`. - -1. **Event Context** `(Operators: vary by field)` - - ```text - 1) --events openat.context.container --events openat.args.pathname=/etc/shadow - ``` - - !!! Note - The following is a list of available context fields: - 1) "timestamp" - 2) "processorId" - 3) "p", "pid", "processId" - 4) "tid", "threadId" - 5) "ppid", "parentProcessId" - 6) "hostTid", "hostThreadId" - 7) "hostPid", "hostParentProcessId" - 8) "uid", "userId" - 9) "mntns", "mountNamespace" - 10) "pidns", "pidNamespace" - 11) "processName", "comm" - 12) "hostName" - 13) "cgroupId" - 14) "host" (inversion of "container") - 15) "container" - 16) "containerId" - 17) "containerImage" - 18) "containerName" - 19) "podName" - 20) "podNamespace" - 21) "podUid" - 22) "syscall" - !!! Tip - Open a container and try `cat /etc/shadow`. - -1. **Event Sets** - - ```text - 1) --events fs - 2) --events lsm_hooks,network_events - ``` - - !!! Note - Selects a set of events to tracee according to pre-defined sets which - can be listed by using `list` command line argument. - -1. **Container** `(Operators: =, != and "new". Boolean)` - - ```text - 1) --scope container # all container events - 2) --scope not-container # events from the host only - 3) --scope container=new # containers created after tracee-ebf execution - 4) --scope container=3f93da58be3c --events openat - 5) --scope container=new --events openat.args.pathname=/etc/shadow - ``` - - !!! Note - The **new** flag allows to filter newly created containers only. - -1. **Command** `(Operators: =, !=)` - - ```text - 1) --scope comm=cat,vim,ping - 2) --scope comm!=ping - ``` - - !!! Note - Do not use given command prefix for these examples as they're filtering - by command name as well. - -1. **Executable Path** `(Operators: =, !=)` - - ```text - 1) --scope executable=/usr/bin/ls - 2) --scope executable=host:/usr/bin/ls - 3) --scope executable=4026532448:/usr/bin/ls - ``` - - !!! Note - 1. Mount namespace id or the special "host:" prefix can be used for finer filtering - 2. Given path must be absolute; i.e starts with "/" - 3. Symbolic link paths are not supported - -1. **PID** `(Operators: =, !=, <, > and "new")` - - ```text - 1) --scope pid=new # newly created events (after tracee execution) - 2) --scope pid=510,1709 # # pids 510 and 1709 - 3) --scope 'pid>0' --scope pid 'pid<1000' - 4) --scope pid=2578238 --scope follow --events openat.args.pathname=/etc/shadow - ``` - - !!! Note - This filter can be used to filter a specific process or thread: - 1. Providing a tgid (aka pid) will filter all threads of the process. - 2. Providing a tid (where tid != tgid) will only filter the specific thread. - -1. **Process Tree** - - ```text - 1) --scope tree=476165 # events descending from process 476165 - 2) --scope tree!=5023 # events that do not descend from process 5023 - ``` - -1. **UID** `(Operators: =, !=, <, >)` - - ```text - 1) --scope uid=0 - 2) --scope 'uid>0' - 3) --scope 'uid>0' --scope uid!=1000 # do not filter root and uid=1000 - ``` - -1. **UTS Namespace (hostnames)** `(Operators: =, !=)` - - ```text - 1) --scope uts!=ab356bc4dd554 - ``` - -1. **PID Namespace** `(Operators: =, !=)` - - ```text - 1) --scope pidns!=4026531836 - ``` - -1. **MOUNT Namespace** `(Operators: =, !=)` - - ```text - 1) --scope mntns=4026531840 - ``` diff --git a/docs/docs/flags/config.1.md b/docs/docs/flags/config.1.md index c696f8fdf9ad..7164c2ed4243 100644 --- a/docs/docs/flags/config.1.md +++ b/docs/docs/flags/config.1.md @@ -15,7 +15,7 @@ tracee **\-\-config** ## DESCRIPTION -The **\-\-config** flag allows you to define global configuration options (flags) for tracee. It expects a file in YAML or JSON format, among others (see [documentation](../config/overview.md)). +The **\-\-config** flag allows you to define global configuration options (flags) for tracee. It expects a file in YAML or JSON format, among others (see [documentation](../config/index.md)). All flags can be set in the config file, except for the following, which are reserved only for the CLI: @@ -25,4 +25,4 @@ All flags can be set in the config file, except for the following, which are res - **\-\-scope** - **\-\-event** -Please refer to the [documentation](../config/overview.md) for more information on the file format and available configuration options. +Please refer to the [documentation](../config/index.md) for more information on the file format and available configuration options. diff --git a/docs/docs/flags/containers.1.md b/docs/docs/flags/containers.1.md index 3a63de5492ed..d089733602c3 100644 --- a/docs/docs/flags/containers.1.md +++ b/docs/docs/flags/containers.1.md @@ -39,4 +39,4 @@ Supported runtimes are: --cri crio:/var/run/crio/crio.sock ``` -Please refer to the [documentation](../integrating/container-engines.md) for more information on container events enrichment. +Please refer to the [documentation](../install/container-engines.md) for more information on container events enrichment. diff --git a/docs/docs/install/config/cli.md b/docs/docs/install/config/cli.md new file mode 100644 index 000000000000..f39712add4b5 --- /dev/null +++ b/docs/docs/install/config/cli.md @@ -0,0 +1,28 @@ +# Configuring Tracee through the CLI + + +The `--config` flag allows you to specify global configuration options for Tracee by providing a configuration file in YAML or JSON format, among other supported formats. The `--config` flag can be used to set any flag that is available through the command line interface (CLI), except for a few reserved flags. + +## Usage + +To use the `--config` flag, you need to provide the path to the configuration file. For example, if you have a YAML configuration file located at /path/to/tracee-config.yaml, you can load it with the following command: + +```console +tracee --config /path/to/tracee-config.yaml +``` + +## Example Configuration Files + +The configuration file should contain a mapping in YAML format of configuration options to their values. To help you get started with configuring Tracee using the `--config` flag, we've provided two example configuration files in the `examples/config` directory of the Tracee repository: + +- `examples/config/global_config.yaml`: This file contains the same example configuration as global_config.json, but in YAML format. + +These example files demonstrate how you can set various configuration options using the `--config` flag. You can use these files as a starting point for your own configuration, or as a reference for the available configuration options. + +To use one of the example configuration files with Tracee, simply pass the path to the file as an argument to the -`-config` flag. For example, to use the YAML configuration file, you could run the following command: + +```console +tracee --config examples/config/global_config.yaml +``` + +By starting with one of these example files and modifying it to suit your needs, you can quickly get up and running with Tracee's configuration options. \ No newline at end of file diff --git a/docs/docs/config/kubernetes.md b/docs/docs/install/config/kubernetes.md similarity index 78% rename from docs/docs/config/kubernetes.md rename to docs/docs/install/config/kubernetes.md index 82e3699aa5fd..cb4b8ad65ee1 100644 --- a/docs/docs/config/kubernetes.md +++ b/docs/docs/install/config/kubernetes.md @@ -17,22 +17,20 @@ metadata: data: config.yaml: |- cache: - type: mem - size: 512 + - cache-type=mem + - mem-cache-size=512 perf-buffer-size: 1024 + containers: true healthz: false metrics: true pprof: false pyroscope: false listen-addr: :3366 log: - level: info + - info output: - options: - parse-arguments: true - json: - files: - - stdout + - json + - option:parse-arguments ``` ## Customizing @@ -49,8 +47,8 @@ helm install tracee aqua/tracee \ # setting a different output helm install tracee aqua/tracee \ --namespace tracee-system --create-namespace \ - --set config.output[0]=table - --set config.output[1]=option:parse-arguments + --set config.output[0]=table \ + --set config.output[1]=option:parse-arguments ``` Or you can pass a config file directly: @@ -58,5 +56,5 @@ Or you can pass a config file directly: ``` helm install tracee aqua/tracee \ --namespace tracee-system --create-namespace \ - --set-file traceeConfig= + --set-file traceeConfig= ``` diff --git a/docs/docs/integrating/container-engines.md b/docs/docs/install/container-engines.md similarity index 100% rename from docs/docs/integrating/container-engines.md rename to docs/docs/install/container-engines.md diff --git a/docs/docs/install/docker.md b/docs/docs/install/docker.md index 50204d53eea2..cf411f2e3230 100644 --- a/docs/docs/install/docker.md +++ b/docs/docs/install/docker.md @@ -8,46 +8,17 @@ This guide will help you get started with running Tracee as a container. - If you are an Apple Mac user, please read [the Mac FAQ](../deep-dive/apple.md) - Ensure that you have Docker or a compatible container runtime -## Tracee container image +## Run the Tracee container images -Tracee container image is available in Docker Hub as [aquasec/tracee](https://hub.docker.com/r/aquasec/tracee). +All of the Tracee container images are stored in a public registry on [Docker Hub.](https://hub.docker.com/r/aquasec/tracee) +You can easily start experimenting with Tracee using the Docker image. -- You can use the `latest` tag or a named version version e.g `aquasec/tracee:{{ git.tag }}`. -- If you are trying the most cutting edge features, there is also a `dev` tag which is built nightly from source. -- The Tracee image is a [Multi-platform](https://docs.docker.com/build/building/multi-platform/) image that includes a x86 and arm64 flavors. You can also access the platform-specific images directly with the `aarch64` and `x86_64` tags for the latest version or `aarch64-` and `x86_64-` for a specific version. -- For most first time users, just use `aquasec/tracee`! +### On x86 architecture, please run the following command -## Running Tracee container - -Here is the docker run command, we will analyze it next: - -```shell +```console docker run \ --name tracee --rm -it \ --pid=host --cgroupns=host --privileged \ -v /etc/os-release:/etc/os-release-host:ro \ aquasec/tracee:latest -``` - -1. Docker general flags: - 1.1 `--name` - name our container so that we can interact with it easily. - 1.2. `--rm` - remove the container one it exits, assuming this is an interactive trial of Tracee. - 1.3. `-it` - allow the container to interact with your terminal. -2. Since Tracee runs in a container but is instrumenting the host, it will need access to some resources from the host: - 2.2 `--pid=host` - share the host's [process namespace]() with Tracee's container. - 2.3 `--cgroupns-host` - share the host's [cgroup namespace]() with Tracee's container. - 2.4 `--privileged` - run the Tracee container as root so it has all the [required capabilities](./prerequisites.md#process-capabilities). - 2.5 `-v /etc/os-release:/etc/os-release-host:ro` - share the host's [OS information file](./prerequisites.md#os-information) with the Tracee container. - -After running this command, you should start seeing a stream of events that Tracee is emitting. - -For next steps, please read about Tracee [Policies](../policies/index.md) - -## Installing Tracee - -If you are looking to permanently install Tracee, you would probably do the following: - -1. Remove interactive flags `-it` and replace with daemon flag `-d` -2. Consider how to collect events from the container. - -Or you can follow the [Kubernetes guide](./kubernetes.md) which addresses these concerns. +``` \ No newline at end of file diff --git a/docs/docs/integrating/healthz.md b/docs/docs/install/healthz.md similarity index 100% rename from docs/docs/integrating/healthz.md rename to docs/docs/install/healthz.md diff --git a/docs/docs/install/kubernetes.md b/docs/docs/install/kubernetes.md index f02a496c3a4d..58af11b4950a 100644 --- a/docs/docs/install/kubernetes.md +++ b/docs/docs/install/kubernetes.md @@ -191,9 +191,9 @@ kubectl -n tracee-system logs -f ds/tracee | grep fileless_execution ## Next steps -Familiarize with the different events, filters, and configuration options in the [documentation](./../docs/overview.md). +Familiarize with the different events, filters, and configuration options in the [documentation](../overview.md). -Read other [tutorials](./../tutorials/overview.md). +Read other [tutorials](../../tutorials/overview.md). For help and support, feel free to use [GitHub Discussions](https://github.com/aquasecurity/tracee/discussions). @@ -204,4 +204,4 @@ If you prefer a video version of the Kubernetes installation guide, have a look Getting started with eBPF in Kubernetes - Tracee Installation Guide - [![Watch the video](../images/ebpftraceehelminstall.png)](https://youtu.be/YQdEvf2IS9k?si=LhQM0CI8_QKvOCeK) + [![Watch the video](../../images/ebpftraceehelminstall.png)](https://youtu.be/YQdEvf2IS9k?si=LhQM0CI8_QKvOCeK) diff --git a/docs/docs/integrating/prometheus.md b/docs/docs/install/prometheus.md similarity index 100% rename from docs/docs/integrating/prometheus.md rename to docs/docs/install/prometheus.md diff --git a/docs/docs/outputs/index.md b/docs/docs/outputs/index.md new file mode 100644 index 000000000000..616f5af70553 --- /dev/null +++ b/docs/docs/outputs/index.md @@ -0,0 +1,23 @@ +# Output Formats and Logs + +It is possible to manage the events gathered in Tracee logs through the CLI using the `--output` and `--log` flag. Users can control where and how to output events by specifying `--output :`. The `--output` flag can be used multiple times to output events. + +Furthermore, the `--log` flag can be used to define what components of the gathered events should be appended to the Tracee output. However, for more fine-grained filters, please take a look at the [scope section](../policies/scopes.md) + +**The following output formats are supported:** + +- `table[:/path/to/file]` - output events in table format (default). The default path to file is stdout. +- `table-verbose[:/path/to/file]` - output events in table format with extra fields per event. The default path to file is stdout. +- `json[:/path/to/file]` - output events in json format. The default path to file is stdout. +- `gob[:/path/to/file]` - output events in gob format. The default path to file is stdout. +- `gotemplate=/path/to/template[:/path/to/file]` - output events formatted using a given gotemplate file. The default path to file is stdout. +- `forward:http://url/fluent` - send events in json format using the Forward protocol to a Fluent receiver +- `webhook:http://url/webhook` - send events in json format to the webhook url +- `none` - ignore stream of events output, usually used with --capture + +**For more information, have a look at the following sections:** + +* Output [formats.](./output-options.md) +* Output [options](./output-options.md) +* Logging [options](./logging.md) + diff --git a/docs/docs/outputs/logging.md b/docs/docs/outputs/logging.md index 4d25cb302a25..0009443704ce 100644 --- a/docs/docs/outputs/logging.md +++ b/docs/docs/outputs/logging.md @@ -1,3 +1,5 @@ +# Tracee Logging Examples + Configure log severity: ```console diff --git a/docs/docs/outputs/output-formats.md b/docs/docs/outputs/output-formats.md index 3fd85293b8d3..35d845374976 100644 --- a/docs/docs/outputs/output-formats.md +++ b/docs/docs/outputs/output-formats.md @@ -1,20 +1,4 @@ -# Tracing Output Formats - - -The `--output` flag controls where and how Tracee will output events, by specifying `--output :`. You can use the `--output` flag multiple times to output events in multiple ways. - -The following output formats are supported: - -- `table[:/path/to/file]` - output events in table format (default). The default path to file is stdout. -- `table-verbose[:/path/to/file]` - output events in table format with extra fields per event. The default path to file is stdout. -- `json[:/path/to/file]` - output events in json format. The default path to file is stdout. -- `gob[:/path/to/file]` - output events in gob format. The default path to file is stdout. -- `gotemplate=/path/to/template[:/path/to/file]` - output events formatted using a given gotemplate file. The default path to file is stdout. -- `forward:http://url/fluent` - send events in json format using the Forward protocol to a Fluent receiver -- `webhook:http://url/webhook` - send events in json format to the webhook url -- `none` - ignore stream of events output, usually used with --capture - -## Examples +# Output Formats ### Table diff --git a/docs/docs/outputs/output-options.md b/docs/docs/outputs/output-options.md index 058d1b70ea00..d750a3cfea8d 100644 --- a/docs/docs/outputs/output-options.md +++ b/docs/docs/outputs/output-options.md @@ -1,4 +1,4 @@ -# Tracing Output Options +# Output Options Tracee supports different output options for customizing the way events are printed. For a complete list of available options. diff --git a/docs/docs/overview.md b/docs/docs/overview.md index 939a67feaa21..ab7b43d1cbdf 100644 --- a/docs/docs/overview.md +++ b/docs/docs/overview.md @@ -3,6 +3,6 @@ In this section you can find the complete reference documentation for all of the different features and settings that Tracee has to offer. !!! Note -We have recently transitioned to a new architecture and user-experience, as detailed [here](https://github.com/aquasecurity/tracee/discussions/2499), and the documentation has been updated accordingly. + We have recently transitioned to a new architecture and user-experience, as detailed [here](https://github.com/aquasecurity/tracee/discussions/2499), and the documentation has been updated accordingly. 👈 Please use the side-navigation on the left in order to browse the different topics. diff --git a/docs/docs/policies/index.md b/docs/docs/policies/index.md index d49a89cec6f9..3fc717136a30 100644 --- a/docs/docs/policies/index.md +++ b/docs/docs/policies/index.md @@ -1,13 +1,10 @@ -In this section you can find the reference documentation for Tracee's policies. +# Policies -Policies are YAML manifests that allow you to define how Tracee should respond to different events. This is done through rules in the policy. A rule takes in one or several events. Additionally, events can be filtered to specific resources. If Tracee detects the event, it will respond with an action. -The default action for Tracee is to log the detected events. +Policies allow users to specify which [events](../events/index.md) to trace in which workloads. The policy `scope` defines which workloads this policy is limited to. The policy can define multiple `rules` that specify the events to trace. Policies are used both for the [Tracee CLI](./usage/cli.md) and for the [Tracee Kubernetes](./usage/kubernetes.md) installaction. This makes it easier to share policies across use cases and environments. -Lastly, policies require a scope. The scope details which resources the policy applies to. +It is possible to load up to 64 policies into Tracee. -You can load multiple (up to 64) policies into Tracee using the --policy flag providing a path to the policy file. - -Following is a sample policy: +Here is an example policy: ```yaml apiVersion: tracee.aquasec.com/v1beta1 @@ -24,31 +21,16 @@ spec: - event: security_file_open filters: - args.pathname=/tmp/* - - event: sched_process_exec - filters: - - uid=0 - - event: close - filters: - - retval!=0 ``` -This policy applies to any workload (global) and will log the dropped_executable, security_file_open, sched_process_exec and close events. Several filters are set to log only specific events: +This policy applies to any workload (`global`) and will log the `dropped_executable`, and `security_file_open` events. An argument filter (`args.pathname`) is set on the `security_file_open` event to log only files which were opened from the `/tmp` directory. -1. An argument filter (args.pathname) is set on the security_file_open event to log only files which were opened from the /tmp directory +!!! Note TODO + Note that currently each event type can only be defined once in a policy -2. A context filter (uid) is set on the sched_process_exec event to log only processes executed by the root user (uid 0) +There are many ways to fine tune the scope and filters. For further information on the details, have a look at the respective sections: -3. A return value filter (retval) is set on the close event to log only failed close syscalls +* [Specify the Policy scope](./scopes.md) +* [Filter events in the rules section](./rules.md) While specifying event filters is optional, policies must have the `name`, `description`, `scope` and `rules` fields. - -!!! Note - Note that currently only one rule can be defined per any event type in a policy - -More information about defining a scope and the available filters can be found in the next sections. - -## Video Content - - Tracking Kubernetes activity with eBPF and Tracee Policies - - [![Watch the video](../../images/traceepolicies.png)](https://youtu.be/VneWxs9Jpu0?si=eAnRDJVZShhg_td0) diff --git a/docs/docs/policies/rules.md b/docs/docs/policies/rules.md index d905de0382c5..83abe55cac53 100644 --- a/docs/docs/policies/rules.md +++ b/docs/docs/policies/rules.md @@ -1,16 +1,15 @@ # Rules -Rules determine which events a policy should trace. +Rules are part of the Tracee Policy, which defines which events to trace. The events that are part of a specific policy are recorded in the `rules` section of the Tracee Policy. It is possible to define multiple events within each policy. The [events](../events/index.md) section provides further information on the type of events that Tracee can track. + +Below are several examples on configuring events in the Tracee Policy. ## Events -An event can match all occurrences of events for a specific scope, or specific events depending on its filters. -Events support three types of filters: `context`, `arguments` and `return value`. +Every event that is specified within the `rules` section supports three types of filters: `context`, `arguments` and `return value`. ### Type of Events -You can add events as either of the following: - **[A syscall](../events/builtin/syscalls/index.md)** Example Scope Section referencing the `open` syscall: @@ -25,7 +24,7 @@ spec: The name of the syscall is going to be the name of the event. -**[Network Events](../events/builtin/network.md)** +**[Network Events](../events/builtin/network/index.md)** Network Events can be specified from the list of `Available network events`. diff --git a/docs/docs/policies/scopes.md b/docs/docs/policies/scopes.md index 3512251d373a..aa1c87abe122 100644 --- a/docs/docs/policies/scopes.md +++ b/docs/docs/policies/scopes.md @@ -1,6 +1,8 @@ # Scopes -Scope defines the workload a policy will be observing. The supported scopes are: +Scope defines the workload a policy will be observing. + +The supported scopes are listed below. ### global diff --git a/docs/docs/policies/usage/cli.md b/docs/docs/policies/usage/cli.md new file mode 100644 index 000000000000..a503e417fa8f --- /dev/null +++ b/docs/docs/policies/usage/cli.md @@ -0,0 +1,27 @@ +# CLI Usage + +This section details how to use the flags in the Tracee CLI. + +## Applying Tracee Polcies + +A [policy file](../index.md) can be applied in the Tracee command using the `--policy` flag and providing a path to the location of the policy file. + +```console +tracee --policy ./policy.yml +``` + +## Using multiple policies + +To specify multiple policies, users can either specify the directory, which contains all of the policies that they would like to load into Tracee, or by specifying the policies one by one. + +Through a directory: + +```console +tracee --policy ./policy-directory +``` + +By specifying individual policies: + +```console +tracee --policy ./policy-one.yaml --policy ./policy-two.yaml +``` \ No newline at end of file diff --git a/docs/docs/policies/usage/kubernetes.md b/docs/docs/policies/usage/kubernetes.md new file mode 100644 index 000000000000..61079204d0c8 --- /dev/null +++ b/docs/docs/policies/usage/kubernetes.md @@ -0,0 +1,10 @@ +# Kubernetes Tracee Usage + + + + +## Video Content + + Tracking Kubernetes activity with eBPF and Tracee Policies + + [![Watch the video](../../../images/traceepolicies.png)](https://youtu.be/VneWxs9Jpu0?si=eAnRDJVZShhg_td0) \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 03c76c1e992c..e325c31d688a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,9 +12,9 @@ hide: - In the [Contributing](./contributing/overview) section you can find technical developer documentation and contribution guidelines. -[installation]:./docs/install/ -[docker-guide]:./docker.md -[kubernetes-guide]:./kubernetes.md +[installation]:./docs/install/index.md +[docker-guide]:./docs/install/docker.md +[kubernetes-guide]:./docs/install/kubernetes.md [prereqs]:./docs/install/prerequisites.md [macfaq]:./docs/deep-dive/mac.md diff --git a/docs/man/containers.1 b/docs/man/containers.1 index 94cc72518d8a..cb6a174e3c44 100644 --- a/docs/man/containers.1 +++ b/docs/man/containers.1 @@ -66,4 +66,4 @@ To connect to CRI-O using the socket file path .RE .PP Please refer to the documentation for more information on container -events enrichment. +events enrichment. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index e1301dca820c..f9fca2bcdc44 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -18,17 +18,18 @@ nav: - Docs: - Overview: docs/overview.md - Installation: - - Overview: docs/install/overview.md + - Overview: docs/install/index.md - Prerequisites: docs/install/prerequisites.md - Docker: docs/install/docker.md - Kubernetes: docs/install/kubernetes.md - - Override OS files: docs/install/override-os-files.md - - Packages: - - Ubuntu: docs/install/distros/ubuntu.md - - Fedora: docs/install/distros/fedora.md - - NixOS: docs/install/distros/nix-nixos.md + - Container Engines: docs/install/container-engines.md + - Prometheus: docs/install/prometheus.md + - Healthz: docs/install/healthz.md + - Configure Tracee: + - CLI: docs/install/config/cli.md + - Kubernetes: docs/install/config/kubernetes.md - Events: - - Overview: docs/events/overview.md + - Overview: docs/events/index.md - Built-in Events: - Security Events: - Overview: docs/events/builtin/signatures/index.md @@ -43,6 +44,7 @@ nav: - Dropped Executable: docs/events/builtin/signatures/dropped_executable.md - Dynamic Code Loading: docs/events/builtin/signatures/dynamic_code_loading.md - Fileless Execution: docs/events/builtin/signatures/fileless_execution.md + - Format: docs/events/builtin/signatures/format.md - Hidden File Created: docs/events/builtin/signatures/hidden_file_created.md - Illegitimate Shell: docs/events/builtin/signatures/illegitimate_shell.md - K8S API Connection: docs/events/builtin/signatures/kubernetes_api_connection.md @@ -84,9 +86,10 @@ nav: - container_remove: docs/events/builtin/extra/container_remove.md - do_sigaction: docs/events/builtin/extra/do_sigaction.md - file_modification: docs/events/builtin/extra/file_modification.md + - format: docs/events/builtin/extra/format.md - ftrace_hook: docs/events/builtin/extra/ftrace_hook.md - hidden_kernel_module: docs/events/builtin/extra/hidden_kernel_module.md - - hooked_syscalls: docs/events/builtin/extra/hooked_syscalls.md + - hooked_syscall: docs/events/builtin/extra/hooked_syscall.md - kallsysm_lookup_name: docs/events/builtin/extra/kallsyms_lookup_name.md - magic_write: docs/events/builtin/extra/magic_write.md - mem_prot_alert: docs/events/builtin/extra/mem_prot_alert.md @@ -558,37 +561,20 @@ nav: - Overview: docs/events/custom/overview.md - Go: docs/events/custom/golang.md - Rego: docs/events/custom/rego.md - - Analyze: docs/events/custom/analyze.md - Policies: - Overview: docs/policies/index.md - Scopes: docs/policies/scopes.md - Rules: docs/policies/rules.md - - Filters: - - Filtering: docs/filters/filtering.md - - Flags Manuals: - - scope: docs/flags/scope.1.md - - events: docs/flags/events.1.md - - output: docs/flags/output.1.md - - capture: docs/flags/capture.1.md - - config: docs/flags/config.1.md - - cri: docs/flags/containers.1.md - - rego: docs/flags/rego.1.md - - cache: docs/flags/cache.1.md - - capabilities: docs/flags/capabilities.1.md - - log: docs/flags/log.1.md + - Usage: + - CLI: docs/policies/usage/cli.md + - Kubernetes: docs/policies/usage/kubernetes.md - Outputs: + - Overview: docs/outputs/index.md - Output Formats: docs/outputs/output-formats.md - Output Options: docs/outputs/output-options.md - Logging: docs/outputs/logging.md - - Config: - - Overview: docs/config/overview.md - - Kubernetes: docs/config/kubernetes.md - Forensics: - - Getting Started: docs/forensics/index.md - - Integrations: - - Container Engines: docs/integrating/container-engines.md - - Prometheus: docs/integrating/prometheus.md - - Healthz: docs/integrating/healthz.md + - Overview: docs/forensics/index.md - Data Sources: - Overview: docs/data-sources/overview.md - Containers: docs/data-sources/containers.md @@ -599,17 +585,27 @@ nav: - Dropping Capabilities: docs/deep-dive/dropping-capabilities.md - Kernel Symbols: docs/deep-dive/ksyms.md - Secure Tracing: docs/deep-dive/secure-tracing.md + - OS Info: docs/deep-dive/os-info.md + - CLI Flags: + - scope: docs/flags/scope.1.md + - events: docs/flags/events.1.md + - output: docs/flags/output.1.md + - capture: docs/flags/capture.1.md + - config: docs/flags/config.1.md + - crs: docs/flags/containers.1.md + - rego: docs/flags/rego.1.md + - cache: docs/flags/cache.1.md + - capabilities: docs/flags/capabilities.1.md + - log: docs/flags/log.1.md - Contributing: - Overview: contributing/overview.md - Documentation: contributing/documentation.md - Source Code Guidelines: contributing/guidelines.md - - Architecture: contributing/architecture.md - Setup Development Machine with Vagrant: contributing/setup-development-machine-with-vagrant.md - Building: - Building Tracee: contributing/building/building.md - Building Environment: contributing/building/environment.md - Building Containers: contributing/building/containers.md - - OS Packaging: contributing/building/packaging.md theme: name: material language: "en"