From 52249d517714a6d18d52facdbfaca961da2f376e Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Wed, 4 Sep 2024 13:30:57 +0000 Subject: [PATCH 01/28] change the documentation for how to run tracee with config file, added an exemple for json over the yaml file, also add a note for where to find exemple file --- docs/docs/install/config/cli.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/docs/install/config/cli.md b/docs/docs/install/config/cli.md index 87bfe5910c80..89abf84be9a0 100644 --- a/docs/docs/install/config/cli.md +++ b/docs/docs/install/config/cli.md @@ -7,5 +7,12 @@ The `--config` flag allows you to specify global configuration options for Trace 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 +sudo ./dist/tracee --config /path/to/tracee-config.yaml ``` + +__OR__ + +```console +sudo ./dist/tracee --config /path/to/tracee-config.json +``` +__NOTE:__ you can find an exemple config file in [tracee/examples/config/](/examples/config/) \ No newline at end of file From a7b12aa931e25fb4682e818de756fa812ec0b208 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Wed, 4 Sep 2024 13:47:43 +0000 Subject: [PATCH 02/28] added a file for the futer to write a documentation on how to write a config file --- docs/docs/install/config/custom_configure.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/docs/install/config/custom_configure.md diff --git a/docs/docs/install/config/custom_configure.md b/docs/docs/install/config/custom_configure.md new file mode 100644 index 000000000000..e69de29bb2d1 From f5f1e1acb36e725782910a061aa779f5a9dda905 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Thu, 5 Sep 2024 17:11:55 +0000 Subject: [PATCH 03/28] changed the docs and tutorials palce, and added custom configure to config install --- mkdocs.yml | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 66dad103572b..71b9d53e2f04 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,14 +8,6 @@ edit_uri: "" nav: - Home: index.md - - Tutorials: - - Overview: tutorials/overview.md - - Cosign - verify Tracee signature: tutorials/verify-tracee-signature.md - - Access Tracee Metrics in Grafana and Prometheus: tutorials/deploy-grafana-dashboard.md - - Using Tracee Container Image with Vagrant on Mac: tutorials/tracee-vagrant.md - - Working with Tracee's Policies on Kubernetes: tutorials/k8s-policies.md - - Accessing Tracee Logs through Promtail and Loki: tutorials/promtail.md - - Additional Resources: tutorials/additional-resources.md - Docs: - Overview: docs/overview.md - Installation: @@ -29,6 +21,7 @@ nav: - Configure Tracee: - Overview: docs/install/config/index.md - CLI: docs/install/config/cli.md + - Custom Configure: docs/install/config/custom_config.md - Kubernetes: docs/install/config/kubernetes.md - Events: - Overview: docs/events/index.md @@ -607,6 +600,14 @@ nav: - cache: docs/flags/cache.1.md - capabilities: docs/flags/capabilities.1.md - log: docs/flags/log.1.md + - Tutorials: + - Overview: tutorials/overview.md + - Cosign - verify Tracee signature: tutorials/verify-tracee-signature.md + - Access Tracee Metrics in Grafana and Prometheus: tutorials/deploy-grafana-dashboard.md + - Using Tracee Container Image with Vagrant on Mac: tutorials/tracee-vagrant.md + - Working with Tracee's Policies on Kubernetes: tutorials/k8s-policies.md + - Accessing Tracee Logs through Promtail and Loki: tutorials/promtail.md + - Additional Resources: tutorials/additional-resources.md - Contributing: - Overview: contributing/overview.md - Documentation: contributing/documentation.md From aa3f1c1c75ffeca72cdbdd02567b299f2e805145 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Sun, 8 Sep 2024 15:02:12 +0000 Subject: [PATCH 04/28] added the option to view the custom configurtion of config file --- docs/docs/install/config/index.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/docs/install/config/index.md b/docs/docs/install/config/index.md index 318d1fdf7b0b..ddeb3b6bbaf4 100644 --- a/docs/docs/install/config/index.md +++ b/docs/docs/install/config/index.md @@ -16,6 +16,9 @@ proctree: cache: process: 8192 thread: 4096 + cache-ttl: + process: 60 + thread: 60 capabilities: bypass: false From feec69737b5b48b690ba4f36976a10765fed408b Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Sun, 8 Sep 2024 16:19:41 +0000 Subject: [PATCH 05/28] fixed spelling issue --- docs/docs/install/config/cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/install/config/cli.md b/docs/docs/install/config/cli.md index 89abf84be9a0..ac2269e6870d 100644 --- a/docs/docs/install/config/cli.md +++ b/docs/docs/install/config/cli.md @@ -15,4 +15,4 @@ __OR__ ```console sudo ./dist/tracee --config /path/to/tracee-config.json ``` -__NOTE:__ you can find an exemple config file in [tracee/examples/config/](/examples/config/) \ No newline at end of file +__NOTE:__ you can find an example config file in [here](/examples/config/) \ No newline at end of file From f9be897cb7f7bf8c9016b6db59cb66d93d2f4966 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Sun, 8 Sep 2024 16:21:17 +0000 Subject: [PATCH 06/28] added the finel version of custom configuration to docs section also changed the overview file content to olny review the custom config, cli, and kubernatics sections --- docs/docs/install/config/custom_configure.md | 492 +++++++++++++++++++ 1 file changed, 492 insertions(+) diff --git a/docs/docs/install/config/custom_configure.md b/docs/docs/install/config/custom_configure.md index e69de29bb2d1..3e713a3500cd 100644 --- a/docs/docs/install/config/custom_configure.md +++ b/docs/docs/install/config/custom_configure.md @@ -0,0 +1,492 @@ +# Tracee Configuration file + +Below are the configurable flags and their options for Tracee. You can set these flags directly when running Tracee or through a configuration file (YAML or JSON). + +### Scope Flags + +- **`--scope` (`-s`)**: Defines which workloads to trace by specifying filter expressions. + + Example usage: + ```bash + tracee --scope uid=1000,1001 + ``` + + YAML: + ```yaml + scope: + - uid=1000,1001 + ``` + + JSON: + ```json + { + "scope": ["uid=1000,1001"] + } + ``` + +### Event Flags + +- **`--events` (`-e`)**: Selects specific events to trace, and allows filtering by event attributes. + + Example usage: + ```bash + tracee --events name=open,execve + ``` + + YAML: + ```yaml + events: + - open + - execve + ``` + + JSON: + ```json + { + "events": ["open", "execve"] + } + ``` + __NOTE__: you can view all compatible events in the [event section](../../events/index.md) + +### Policy Flags + +- **`--policy` (`-p`)**: Specifies a policy file or directory of policies that define what to trace. + + Example usage: + ```bash + tracee --policy` /path/to/policy.yaml + ``` + + YAML: + ```yaml + policy: + - /path/to/policy.yaml + ``` + + JSON: + ```json + { + "policy": ["/path/to/policy.yaml"] + } + ``` + __NOTE__: you can view policies in the [policy section](../../policies/index.md) + +### Output Flags + +- **`--output` (`-o`)**: Controls how and where the output is printed. + + Supported options: `json`, `none`, `webhook`, `table`(default) + + Example usage: + ```bash + tracee --output json + ``` + + YAML: + ```yaml + output: + - json + ``` + + JSON: + ```json + { + "output": ["json"] + } + ``` + __NOTE__: you can view all outputs in the [output section](../../outputs/index.md) + +### Capture Flags + +- **`--capture` (`-c`)**: Captures artifacts such as files or network packets that are written or executed. + + Supported options: `write` , `exec` , `network` + + Example usage: + ```bash + tracee --capture write + ``` + + YAML: + ```yaml + capture: + - write + ``` + + JSON: + ```json + { + "capture": ["write"] + } + ``` + +### Container Flags + +- **`--no-containers`**: Disables container information enrichment in events. + + Example usage: + ```bash + tracee --no-containers + ``` + + YAML: + ```yaml + no-containers: true + ``` + + JSON: + ```json + { + "no-containers": true + } + ``` + +- **`--cri`**: Defines connected container runtimes in the format ``. + + Example usage: + ```bash + tracee --cri docker:/var/run/docker.sock + ``` + + YAML: + ```yaml + cri: + - docker:/var/run/docker.sock + ``` + + JSON: + ```json + { + "cri": ["docker:/var/run/docker.sock"] + } + ``` + +### Signature Flags + +- **`--signatures-dir`**: Specifies directories to search for signatures in OPA (`.rego`) or Go plugin (`.so`) formats. + + Example usage: + ```bash + tracee --signatures-dir /path/to/signatures + ``` + + YAML: + ```yaml + signatures-dir: + - /path/to/signatures + ``` + + JSON: + ```json + { + "signatures-dir": ["/path/to/signatures"] + } + ``` + +- **`--rego`**: Controls Rego signature evaluation settings. + + Example usage: + ```bash + tracee --rego aio + ``` + + YAML: + ```yaml + rego: + - aio + ``` + + JSON: + ```json + { + "rego": ["aio"] + } + ``` + +### Buffer and Cache Flags + +- **`--perf-buffer-size` (`-b`)**: Specifies the size of the internal perf ring buffer in pages. + + Default: `1024` (4 MB) + + Example usage: + ```bash + tracee --perf-buffer-size 2048 + ``` + + YAML: + ```yaml + perf-buffer-size: 2048 + ``` + + JSON: + ```json + { + "perf-buffer-size": 2048 + } + ``` +- **`--blob-perf-buffer-size`**: Specifies the size of the internal perf ring buffer used to send blobs from the kernel. + + Default: `1024` (4 MB) + + Example usage: + ```bash + tracee --blob-perf-buffer-size 2048 + ``` + + YAML: + ```yaml + blob-perf-buffer-size: 2048 + ``` + + JSON: + ```json + { + "blob-perf-buffer-size": 2048 + } + ``` +- **`--pipeline-channel-size`**: Specifies the size of each pipeline stage's output channel. + Default: `10000` + + Example usage: + ```bash + tracee --pipeline-channel-size 2048 + ``` + + YAML: + ```yaml + pipeline-channel-size: 2048 + ``` + + JSON: + ```json + { + "pipeline-channel-size": 2048 + } + ``` + +- **`--cache` (`-a`)**: Controls event caching options. + + Example usage: + ```bash + tracee --cache mem-cache-size=512 + ``` + + YAML: + ```yaml + cache: + - mem-cache-size=512 + ``` + + JSON: + ```json + { + "cache": ["mem-cache-size=512"] + } + ``` + +### Process Tree Flags + +- **`--proctree` (`-t`)**: Controls process tree options. + + Example usage: + ```bash + tracee --proctree process + ``` + + YAML: + ```yaml + proctree: + - process + ``` + + JSON: + ```json + { + "proctree": ["process"] + } + ``` + +### DNS Cache + +- **`--dnscache`**: Enables DNS caching in Tracee. + + Example usage: + ```bash + tracee --dnscache + ``` + + YAML: + ```yaml + dnscache: enable + ``` + + JSON: + ```json + { + "dnscache": enable + } + ``` + +### Server Flags + +- **`--metrics-endpoint`**: Enables the metrics endpoint. + + Example usage: + ```bash + tracee --metrics-endpoint + ``` + + YAML: + ```yaml + metrics-endpoint: true + ``` + + JSON: + ```json + { + "metrics-endpoint": true + } + ``` + +- **`--grpc-listen-addr`**: Specifies the address for the gRPC server. + Example usage: + ```bash + tracee --grpc-listen-addr tcp:0.0.0.0:50051 + ``` + + YAML: + ```yaml + grpc-listen-addr: tcp:0.0.0.0:50051 + ``` + + JSON: + ```json + { + "grpc-listen-addr": "tcp:0.0.0.0:50051" + } + ``` + + +### Capabilities Flags + +- **`--capabilities` (`-C`)**: Define specific capabilities for Tracee to run with. This allows you to either bypass, add, or drop certain capabilities based on your security and operational needs. + + Supported options: `bypass`, `add`, `drop` + + Example usage: + ```bash + tracee --capabilities add=CAP_SYS_ADMIN,drop=CAP_NET_RAW + ``` + + YAML: + ```yaml + capabilities: + - add: CAP_SYS_ADMIN + - drop: CAP_NET_RAW + ``` + + JSON: + ```json + { + "capabilities": [ + {"add": "CAP_SYS_ADMIN"}, + {"drop": "CAP_NET_RAW"} + ] + } + ``` + + __NOTE__: Capabilities are Linux-specific permissions that control which privileged operations a program can perform. Tracee can add or drop these capabilities based on your configuration. Using `bypass` allows Tracee to run without making any changes to its default capabilities. + +### Install Path Flag + +- **`--install-path`**: Specifies the directory where Tracee will install or look for its resources. If not specified, the default installation directory is `/tmp/tracee`. + + Example usage: + ```bash + tracee --install-path /opt/tracee + ``` + + YAML: + ```yaml + install-path: /opt/tracee + ``` + + JSON: + ```json + { + "install-path": "/opt/tracee" + } + ``` + + __NOTE__: This option is useful when running Tracee in environments where `/tmp` is not suitable or secure, allowing you to set a custom installation directory. + +### Log Flags + +- **`--log` (`-l`)**: Controls the verbosity level of Tracee's logging system. Multiple logging options can be defined to filter specific log levels. The default log level is `info`. + + Supported options: `debug`, `info`, `warn`, `error` + + Example usage: + ```bash + tracee --log debug,info + ``` + + YAML: + ```yaml + log: + - debug + - info + ``` + + JSON: + ```json + { + "log": ["debug", "info"] + } + ``` + + __NOTE__: Setting log levels is crucial for monitoring Tracee's behavior, especially in debugging and troubleshooting scenarios. The `debug` level provides the most detailed logging, while `info`, `warn`, and `error` reduce verbosity. + +## Full Example of a Configuration File + +Here’s a full example of what a configuration file might look like in YAML: + +```yaml +scope: + - uid=1000 +events: + - execve + - open +output: + - json +capture: + - write +cri: + - docker:/var/run/docker.sock +log: + - debug +``` + +And the equivalent in JSON: + +```json +{ + "scope": ["uid=1000"], + "events": ["execve", "open"], + "output": ["json"], + "capture": ["write"], + "cri": ["docker:/var/run/docker.sock"], + "log": ["debug"] +} +``` + +And the equivalent in CLI flags: +```bash +tracee --scope uid=1000 \ + --events name=execve,open \ + --output json \ + --capture write \ + --cri docker:/var/run/docker.sock \ + --log debug +``` \ No newline at end of file From 344a8374510abdcc3ab13e829a433ee14c933914 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Sun, 8 Sep 2024 16:22:04 +0000 Subject: [PATCH 07/28] change the mkdocs file to serve ass the new docs represantation of tracee --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 71b9d53e2f04..5741fd6b5b6c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -20,8 +20,8 @@ nav: - Healthz: docs/install/healthz.md - Configure Tracee: - Overview: docs/install/config/index.md + - Custom Configure: docs/install/config/custom_configure.md - CLI: docs/install/config/cli.md - - Custom Configure: docs/install/config/custom_config.md - Kubernetes: docs/install/config/kubernetes.md - Events: - Overview: docs/events/index.md From dd9e7f8d8810437250cc295acb3b4f2de96b9950 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Sun, 8 Sep 2024 16:51:31 +0000 Subject: [PATCH 08/28] added some changes to sutom config --- docs/docs/install/config/custom_configure.md | 21 ++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/docs/install/config/custom_configure.md b/docs/docs/install/config/custom_configure.md index 3e713a3500cd..e5f6d2d4f1e4 100644 --- a/docs/docs/install/config/custom_configure.md +++ b/docs/docs/install/config/custom_configure.md @@ -352,18 +352,18 @@ Below are the configurable flags and their options for Tracee. You can set these - **`--grpc-listen-addr`**: Specifies the address for the gRPC server. Example usage: ```bash - tracee --grpc-listen-addr tcp:0.0.0.0:50051 + tracee --grpc-listen-addr tcp:50051 ``` YAML: ```yaml - grpc-listen-addr: tcp:0.0.0.0:50051 + grpc-listen-addr: tcp:50051 ``` JSON: ```json { - "grpc-listen-addr": "tcp:0.0.0.0:50051" + "grpc-listen-addr": "tcp:50051" } ``` @@ -382,8 +382,10 @@ Below are the configurable flags and their options for Tracee. You can set these YAML: ```yaml capabilities: - - add: CAP_SYS_ADMIN - - drop: CAP_NET_RAW + - add: + - CAP_SYS_ADMIN + - drop: + - CAP_NET_RAW ``` JSON: @@ -425,8 +427,8 @@ Below are the configurable flags and their options for Tracee. You can set these - **`--log` (`-l`)**: Controls the verbosity level of Tracee's logging system. Multiple logging options can be defined to filter specific log levels. The default log level is `info`. - Supported options: `debug`, `info`, `warn`, `error` - + Supported level options: `debug`, `info`, `warn`, `error`, `panic` + __NOTE__: there is a lot about log so pleas visit the page about it [here](/docs/docs/outputs/logging.md) Example usage: ```bash tracee --log debug,info @@ -435,14 +437,13 @@ Below are the configurable flags and their options for Tracee. You can set these YAML: ```yaml log: - - debug - - info + - level: debug ``` JSON: ```json { - "log": ["debug", "info"] + "log": ["debug"] } ``` From 91330e28d4c2116c70882f96bb0d0fd221fa64a4 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Sun, 8 Sep 2024 16:52:01 +0000 Subject: [PATCH 09/28] added some missing flags in the yaml file --- examples/config/global_config.yaml | 43 ++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/examples/config/global_config.yaml b/examples/config/global_config.yaml index cdcdc6de0b71..37794fa97ab0 100644 --- a/examples/config/global_config.yaml +++ b/examples/config/global_config.yaml @@ -3,6 +3,15 @@ cache: type: none # size: 1024 +capture: + #- write + #- exec + #- network + +policy: + - /path/to/policy.yaml + #- /path/to/policy-directory + proctree: source: none # cache: @@ -17,6 +26,12 @@ capabilities: # drop: # - cap_chown +metrics-endpoint: true + +grpc-listen-addr: tcp:50051 + +dnscache: enable + cri: # - runtime: # name: containerd @@ -25,9 +40,18 @@ cri: # name: docker # socket: /var/run/docker.sock +events: + #- open + #- execve + +no-containers: true + healthz: false + install-path: /tmp/tracee + listen-addr: :3366 + log: level: info # file: "/path/to/log/file.log" @@ -64,7 +88,22 @@ log: # regex: # - ^excludedPattern +scope: + #- uid=1000 + #- global + #- pid=1000 + #- mntns=4026531840 + #- pidns=4026531836 + #- uts=ab356bc4dd554 + #- comm=uname + #- container + #- not-container + #- tree=1000 + #- executable=/usr/bin/dig + #- follow + metrics: false + output: json: files: @@ -127,9 +166,13 @@ output: # sort-events: false perf-buffer-size: 1024 + pprof: false + pyroscope: false + rego: # partial-eval: true # aio: true + signatures-dir: "" From fdbd94e0dac417d05e17a32a2393b11541fd0012 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Mon, 9 Sep 2024 12:56:03 +0000 Subject: [PATCH 10/28] deleted the custom configure file, marge it with the index, remove bash and json, add view mores to sections --- docs/docs/install/config/custom_configure.md | 493 ------------------- 1 file changed, 493 deletions(-) delete mode 100644 docs/docs/install/config/custom_configure.md diff --git a/docs/docs/install/config/custom_configure.md b/docs/docs/install/config/custom_configure.md deleted file mode 100644 index e5f6d2d4f1e4..000000000000 --- a/docs/docs/install/config/custom_configure.md +++ /dev/null @@ -1,493 +0,0 @@ -# Tracee Configuration file - -Below are the configurable flags and their options for Tracee. You can set these flags directly when running Tracee or through a configuration file (YAML or JSON). - -### Scope Flags - -- **`--scope` (`-s`)**: Defines which workloads to trace by specifying filter expressions. - - Example usage: - ```bash - tracee --scope uid=1000,1001 - ``` - - YAML: - ```yaml - scope: - - uid=1000,1001 - ``` - - JSON: - ```json - { - "scope": ["uid=1000,1001"] - } - ``` - -### Event Flags - -- **`--events` (`-e`)**: Selects specific events to trace, and allows filtering by event attributes. - - Example usage: - ```bash - tracee --events name=open,execve - ``` - - YAML: - ```yaml - events: - - open - - execve - ``` - - JSON: - ```json - { - "events": ["open", "execve"] - } - ``` - __NOTE__: you can view all compatible events in the [event section](../../events/index.md) - -### Policy Flags - -- **`--policy` (`-p`)**: Specifies a policy file or directory of policies that define what to trace. - - Example usage: - ```bash - tracee --policy` /path/to/policy.yaml - ``` - - YAML: - ```yaml - policy: - - /path/to/policy.yaml - ``` - - JSON: - ```json - { - "policy": ["/path/to/policy.yaml"] - } - ``` - __NOTE__: you can view policies in the [policy section](../../policies/index.md) - -### Output Flags - -- **`--output` (`-o`)**: Controls how and where the output is printed. - - Supported options: `json`, `none`, `webhook`, `table`(default) - - Example usage: - ```bash - tracee --output json - ``` - - YAML: - ```yaml - output: - - json - ``` - - JSON: - ```json - { - "output": ["json"] - } - ``` - __NOTE__: you can view all outputs in the [output section](../../outputs/index.md) - -### Capture Flags - -- **`--capture` (`-c`)**: Captures artifacts such as files or network packets that are written or executed. - - Supported options: `write` , `exec` , `network` - - Example usage: - ```bash - tracee --capture write - ``` - - YAML: - ```yaml - capture: - - write - ``` - - JSON: - ```json - { - "capture": ["write"] - } - ``` - -### Container Flags - -- **`--no-containers`**: Disables container information enrichment in events. - - Example usage: - ```bash - tracee --no-containers - ``` - - YAML: - ```yaml - no-containers: true - ``` - - JSON: - ```json - { - "no-containers": true - } - ``` - -- **`--cri`**: Defines connected container runtimes in the format ``. - - Example usage: - ```bash - tracee --cri docker:/var/run/docker.sock - ``` - - YAML: - ```yaml - cri: - - docker:/var/run/docker.sock - ``` - - JSON: - ```json - { - "cri": ["docker:/var/run/docker.sock"] - } - ``` - -### Signature Flags - -- **`--signatures-dir`**: Specifies directories to search for signatures in OPA (`.rego`) or Go plugin (`.so`) formats. - - Example usage: - ```bash - tracee --signatures-dir /path/to/signatures - ``` - - YAML: - ```yaml - signatures-dir: - - /path/to/signatures - ``` - - JSON: - ```json - { - "signatures-dir": ["/path/to/signatures"] - } - ``` - -- **`--rego`**: Controls Rego signature evaluation settings. - - Example usage: - ```bash - tracee --rego aio - ``` - - YAML: - ```yaml - rego: - - aio - ``` - - JSON: - ```json - { - "rego": ["aio"] - } - ``` - -### Buffer and Cache Flags - -- **`--perf-buffer-size` (`-b`)**: Specifies the size of the internal perf ring buffer in pages. - - Default: `1024` (4 MB) - - Example usage: - ```bash - tracee --perf-buffer-size 2048 - ``` - - YAML: - ```yaml - perf-buffer-size: 2048 - ``` - - JSON: - ```json - { - "perf-buffer-size": 2048 - } - ``` -- **`--blob-perf-buffer-size`**: Specifies the size of the internal perf ring buffer used to send blobs from the kernel. - - Default: `1024` (4 MB) - - Example usage: - ```bash - tracee --blob-perf-buffer-size 2048 - ``` - - YAML: - ```yaml - blob-perf-buffer-size: 2048 - ``` - - JSON: - ```json - { - "blob-perf-buffer-size": 2048 - } - ``` -- **`--pipeline-channel-size`**: Specifies the size of each pipeline stage's output channel. - Default: `10000` - - Example usage: - ```bash - tracee --pipeline-channel-size 2048 - ``` - - YAML: - ```yaml - pipeline-channel-size: 2048 - ``` - - JSON: - ```json - { - "pipeline-channel-size": 2048 - } - ``` - -- **`--cache` (`-a`)**: Controls event caching options. - - Example usage: - ```bash - tracee --cache mem-cache-size=512 - ``` - - YAML: - ```yaml - cache: - - mem-cache-size=512 - ``` - - JSON: - ```json - { - "cache": ["mem-cache-size=512"] - } - ``` - -### Process Tree Flags - -- **`--proctree` (`-t`)**: Controls process tree options. - - Example usage: - ```bash - tracee --proctree process - ``` - - YAML: - ```yaml - proctree: - - process - ``` - - JSON: - ```json - { - "proctree": ["process"] - } - ``` - -### DNS Cache - -- **`--dnscache`**: Enables DNS caching in Tracee. - - Example usage: - ```bash - tracee --dnscache - ``` - - YAML: - ```yaml - dnscache: enable - ``` - - JSON: - ```json - { - "dnscache": enable - } - ``` - -### Server Flags - -- **`--metrics-endpoint`**: Enables the metrics endpoint. - - Example usage: - ```bash - tracee --metrics-endpoint - ``` - - YAML: - ```yaml - metrics-endpoint: true - ``` - - JSON: - ```json - { - "metrics-endpoint": true - } - ``` - -- **`--grpc-listen-addr`**: Specifies the address for the gRPC server. - Example usage: - ```bash - tracee --grpc-listen-addr tcp:50051 - ``` - - YAML: - ```yaml - grpc-listen-addr: tcp:50051 - ``` - - JSON: - ```json - { - "grpc-listen-addr": "tcp:50051" - } - ``` - - -### Capabilities Flags - -- **`--capabilities` (`-C`)**: Define specific capabilities for Tracee to run with. This allows you to either bypass, add, or drop certain capabilities based on your security and operational needs. - - Supported options: `bypass`, `add`, `drop` - - Example usage: - ```bash - tracee --capabilities add=CAP_SYS_ADMIN,drop=CAP_NET_RAW - ``` - - YAML: - ```yaml - capabilities: - - add: - - CAP_SYS_ADMIN - - drop: - - CAP_NET_RAW - ``` - - JSON: - ```json - { - "capabilities": [ - {"add": "CAP_SYS_ADMIN"}, - {"drop": "CAP_NET_RAW"} - ] - } - ``` - - __NOTE__: Capabilities are Linux-specific permissions that control which privileged operations a program can perform. Tracee can add or drop these capabilities based on your configuration. Using `bypass` allows Tracee to run without making any changes to its default capabilities. - -### Install Path Flag - -- **`--install-path`**: Specifies the directory where Tracee will install or look for its resources. If not specified, the default installation directory is `/tmp/tracee`. - - Example usage: - ```bash - tracee --install-path /opt/tracee - ``` - - YAML: - ```yaml - install-path: /opt/tracee - ``` - - JSON: - ```json - { - "install-path": "/opt/tracee" - } - ``` - - __NOTE__: This option is useful when running Tracee in environments where `/tmp` is not suitable or secure, allowing you to set a custom installation directory. - -### Log Flags - -- **`--log` (`-l`)**: Controls the verbosity level of Tracee's logging system. Multiple logging options can be defined to filter specific log levels. The default log level is `info`. - - Supported level options: `debug`, `info`, `warn`, `error`, `panic` - __NOTE__: there is a lot about log so pleas visit the page about it [here](/docs/docs/outputs/logging.md) - Example usage: - ```bash - tracee --log debug,info - ``` - - YAML: - ```yaml - log: - - level: debug - ``` - - JSON: - ```json - { - "log": ["debug"] - } - ``` - - __NOTE__: Setting log levels is crucial for monitoring Tracee's behavior, especially in debugging and troubleshooting scenarios. The `debug` level provides the most detailed logging, while `info`, `warn`, and `error` reduce verbosity. - -## Full Example of a Configuration File - -Here’s a full example of what a configuration file might look like in YAML: - -```yaml -scope: - - uid=1000 -events: - - execve - - open -output: - - json -capture: - - write -cri: - - docker:/var/run/docker.sock -log: - - debug -``` - -And the equivalent in JSON: - -```json -{ - "scope": ["uid=1000"], - "events": ["execve", "open"], - "output": ["json"], - "capture": ["write"], - "cri": ["docker:/var/run/docker.sock"], - "log": ["debug"] -} -``` - -And the equivalent in CLI flags: -```bash -tracee --scope uid=1000 \ - --events name=execve,open \ - --output json \ - --capture write \ - --cri docker:/var/run/docker.sock \ - --log debug -``` \ No newline at end of file From 9558b88638ff40f0a161b22e30c357313256b9f6 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Mon, 9 Sep 2024 12:56:33 +0000 Subject: [PATCH 11/28] remove custom config from mkdocs --- mkdocs.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 5741fd6b5b6c..8bb193a824f1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -20,7 +20,6 @@ nav: - Healthz: docs/install/healthz.md - Configure Tracee: - Overview: docs/install/config/index.md - - Custom Configure: docs/install/config/custom_configure.md - CLI: docs/install/config/cli.md - Kubernetes: docs/install/config/kubernetes.md - Events: From ddf421c86aa61d857dcb93b49d48e00e99ccacae Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Tue, 10 Sep 2024 14:53:03 +0000 Subject: [PATCH 12/28] added things that was missing, changes and solved issues with files, add a material fetures for copy to clipboard --- mkdocs.yml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 8bb193a824f1..b041d8d334e1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -57,6 +57,7 @@ nav: - Sudoers Modification: docs/events/builtin/signatures/sudoers_modification.md - Syscall Table Hooking: docs/events/builtin/signatures/syscall_table_hooking.md - SysRQ Modification: docs/events/builtin/signatures/system_request_key_config_modification.md + - format: docs/events/builtin/signatures/format.md - Network Events: - Overview: docs/events/builtin/network/index.md - net_flow_tcp_begin: docs/events/builtin/network/net_flow_tcp_begin.md @@ -101,11 +102,14 @@ nav: - security_socket_bind: docs/events/builtin/extra/security_socket_bind.md - security_socket_connect: docs/events/builtin/extra/security_socket_connect.md - security_socket_setsockopt: docs/events/builtin/extra/security_socket_setsockopt.md - - security_settime64: docs/docs/events/builtin/extra/security_settime64.md + - security_settime64: docs/events/builtin/extra/security_settime64.md - symbols_collision: docs/events/builtin/extra/symbols_collision.md - symbols_loaded: docs/events/builtin/extra/symbols_loaded.md - vfs_read: docs/events/builtin/extra/vfs_read.md - vfs_readv: docs/events/builtin/extra/vfs_readv.md + - security_path_notify: docs/events/builtin/extra/security_path_notify.md + - set_fs_pwd: docs/events/builtin/extra/set_fs_pwd.md + - tracee_info: docs/events/builtin/extra/tracee_info.md - Syscalls: - Overview: docs/events/builtin/syscalls/index.md - syscalls: @@ -616,6 +620,7 @@ nav: - Building Tracee: contributing/building/building.md - Building Environment: contributing/building/environment.md - Building Containers: contributing/building/containers.md + theme: name: material language: "en" @@ -625,6 +630,7 @@ theme: - navigation.tabs.sticky - navigation.sections - content.tabs.link + - content.code.copy markdown_extensions: - pymdownx.highlight From d911b48e3679b02ef4cce8a4babf20b1878c575d Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Wed, 11 Sep 2024 07:55:29 +0000 Subject: [PATCH 13/28] change a bit the looks --- docs/docs/install/config/cli.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/docs/install/config/cli.md b/docs/docs/install/config/cli.md index ac2269e6870d..b8d626a43692 100644 --- a/docs/docs/install/config/cli.md +++ b/docs/docs/install/config/cli.md @@ -7,12 +7,6 @@ The `--config` flag allows you to specify global configuration options for Trace 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 -sudo ./dist/tracee --config /path/to/tracee-config.yaml -``` - -__OR__ - -```console -sudo ./dist/tracee --config /path/to/tracee-config.json +tracee --config /path/to/tracee-config.yaml ``` __NOTE:__ you can find an example config file in [here](/examples/config/) \ No newline at end of file From 6074dcdf4268f36b7152b32ba36581a1f28fb8b0 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Wed, 11 Sep 2024 09:33:46 +0000 Subject: [PATCH 14/28] added final changes --- docs/docs/install/config/index.md | 192 ++++++++++++++++++++++++- examples/config/global_config_cli.yaml | 21 --- 2 files changed, 191 insertions(+), 22 deletions(-) delete mode 100644 examples/config/global_config_cli.yaml diff --git a/docs/docs/install/config/index.md b/docs/docs/install/config/index.md index ddeb3b6bbaf4..4133a6a6d517 100644 --- a/docs/docs/install/config/index.md +++ b/docs/docs/install/config/index.md @@ -1,9 +1,11 @@ # Configuring Tracee Tracee has many different options and settings that control how Tracee operates. -This section presents available configuration options. To learn about how to apply configuration to Tracee, please refer to the [CLI](./cli.md) or [Kubernetes](./kubernetes.md) specific guides. A complete config file with all available options can be found [here](https://github.com/aquasecurity/tracee/blob/main/examples/config/global_config.yaml). Most of the options are documented in different sections in the documentation. +To learn about all available configuration options please see [this document](https://github.com/aquasecurity/tracee/blob/main/examples/config/global_config.yaml). + +This section includes detailed description of the common configurable options. ```yaml blob-perf-buffer-size: 1024 @@ -145,3 +147,191 @@ rego: aio: true signatures-dir: "" ``` + +To learn about how to apply configuration to Tracee, please refer to the [CLI](./cli.md) or [Kubernetes](./kubernetes.md) specific guides, depending on how you deploy Tracee. + + - __NOTE__: The YAML examples can be translated to JSON as well + +## Common configurations + +### Policy + +- **`--policy` (`-p`)**: Specifies a policy file or directory of policies that define what to trace. + + __NOTE__: You can view more in the [policy section](../../policies/index.md). + + YAML: + ```yaml + policy: + - /path/to/policy.yaml + ``` + + +### Output + +- **`--output` (`-o`)**: Controls how and where the output is printed. + + __NOTE__: You can view more in the [output section](../../outputs/index.md). + + YAML: + ```yaml + output: + - json + ``` + + +### Server + + +- **`--metrics-endpoint`**: Enables the metrics endpoint. + + __NOTE__: You can view more in the [Prometheus section](../prometheus.md). + + YAML: + ```yaml + metrics-endpoint: true + ``` + +- **`--grpc-listen-addr`**: Specifies the address for the gRPC server. + + YAML: + ```yaml + grpc-listen-addr: tcp:50051 + ``` + + +### Process Tree + +- **`--proctree` (`-t`)**: Controls process tree options. + + + __NOTE__: You can view more in the [Process Tree section](../../advanced/data-sources/builtin/process-tree.md). + + YAML: + ```yaml + proctree: + - process + ``` + +### Install Path + +- **`--install-path`**: Specifies the directory where Tracee will install or look for its resources. If not specified, the default installation directory is `/tmp/tracee`. + + YAML: + ```yaml + install-path: /opt/tracee + ``` + + __NOTE__: This option is useful when running Tracee in environments where `/tmp` is not suitable or secure. + +### Log + +- **`--log` (`-l`)**: Controls the verbosity level of Tracee's logging system. The default log level is `info`. + + + __NOTE__: You can view more in the [Tracee Logs section](../../outputs/logging.md). + + YAML: + ```yaml + log: + - level: debug + ``` + +### Container + +- **`--no-containers`**: Disables container information enrichment in events. + + YAML: + ```yaml + no-containers: true + ``` + + __NOTE__: You can view more in the [cri section](../../flags/containers.1.md). + +- **`--cri`**: Defines connected container runtimes in the format ``. + + YAML: + ```yaml + cri: + - docker:/var/run/docker.sock + ``` + +### DNS Cache + +- **`--dnscache`**: Enables DNS caching in Tracee. + + __NOTE__: You can view more in the [DNS Cache section](../../advanced/data-sources/builtin/dns.md). + + YAML: + ```yaml + dnscache: enable + ``` + +### Capabilities + +- **`--capabilities` (`-C`)**: Define specific capabilities for Tracee to run with. This allows you to either bypass, add, or drop certain capabilities based on your security and operational needs. + + + __NOTE__: You can view more in the [Tracee Capabilities section](../../flags/capabilities.1.md) + + YAML: + ```yaml + capabilities: + - add: + - CAP_SYS_ADMIN + - drop: + - CAP_NET_RAW + ``` + + __NOTE__: Capabilities are Linux-specific permissions that control which privileged operations a program can perform. + + +### Capture + +- **`--capture` (`-c`)**: Captures artifacts such as files or network packets that are written or executed. + + + __NOTE__: You can view more in the [Capture section](../../flags/capture.1.md). + + YAML: + ```yaml + capture: + - write + ``` + +### Buffer and Cache + +- **`--perf-buffer-size` (`-b`)**: Specifies the size of the internal perf ring buffer in pages. + + Default: `1024` (4 MB) + + YAML: + ```yaml + perf-buffer-size: 2048 + ``` + +- **`--blob-perf-buffer-size`**: Specifies the size of the internal perf ring buffer used to send blobs from the kernel. + + Default: `1024` (4 MB) + + YAML: + ```yaml + blob-perf-buffer-size: 2048 + ``` + +- **`--pipeline-channel-size`**: Specifies the size of each pipeline stage's output channel. + + Default: `10000` + + YAML: + ```yaml + pipeline-channel-size: 2048 + ``` + +- **`--cache` (`-a`)**: Controls event caching options. + + YAML: + ```yaml + cache: + - mem-cache-size=512 + ``` diff --git a/examples/config/global_config_cli.yaml b/examples/config/global_config_cli.yaml deleted file mode 100644 index c82edee1c8df..000000000000 --- a/examples/config/global_config_cli.yaml +++ /dev/null @@ -1,21 +0,0 @@ -blob-perf-buffer-size: 1024 -cache: - - none -proctree: - - none -capabilities: [] -containers: false -cri: [] -healthz: false -install-path: /tmp/tracee -listen-addr: :3366 -log: - - info -metrics: false -output: - - json -perf-buffer-size: 1024 -pprof: false -pyroscope: false -rego: [] -signatures-dir: "" From 589d058778038be6ee58616fb357dba7af1f2a87 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Thu, 12 Sep 2024 15:43:43 +0000 Subject: [PATCH 15/28] removed wild card option for scope --- docs/docs/flags/scope.1.md | 4 +--- docs/man/scope.1 | 5 ----- 2 files changed, 1 insertion(+), 8 deletions(-) diff --git a/docs/docs/flags/scope.1.md b/docs/docs/flags/scope.1.md index a8a79a63f936..5c7bfc89e35b 100644 --- a/docs/docs/flags/scope.1.md +++ b/docs/docs/flags/scope.1.md @@ -2,7 +2,7 @@ title: TRACEE-SCOPE section: 1 header: Tracee Scope Flag Manual -date: 2024/06 +date: 2024/09 ... ## NAME @@ -49,9 +49,7 @@ Available for the following string fields: - container: Select events from specific container IDs. - executable: Select events based on the executable path. -Strings can be compared as a prefix if ending with '\*', or as a suffix if starting with '\*'. -NOTE: Expressions containing '\*' token must be escaped! ### BOOLEAN OPERATOR (PREPENDED) diff --git a/docs/man/scope.1 b/docs/man/scope.1 index 67b394a96bb9..77b537465433 100644 --- a/docs/man/scope.1 +++ b/docs/man/scope.1 @@ -51,11 +51,6 @@ comm: Select events based on process command names. container: Select events from specific container IDs. .IP \[bu] 2 executable: Select events based on the executable path. -.PP -Strings can be compared as a prefix if ending with `*', or as a suffix -if starting with `*'. -.PP -NOTE: Expressions containing `*' token must be escaped! .SS BOOLEAN OPERATOR (PREPENDED) `!' .PP From 92fa3a60953a47a9a3391b676ac0d48c8ab7b872 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Thu, 12 Sep 2024 16:10:04 +0000 Subject: [PATCH 16/28] changed Scope filters to Rules filter - need further changes on Events under rules --- docs/docs/policies/rules.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/docs/policies/rules.md b/docs/docs/policies/rules.md index 2df8622f2839..7baad8a90cb1 100644 --- a/docs/docs/policies/rules.md +++ b/docs/docs/policies/rules.md @@ -64,27 +64,28 @@ spec: event: do_sigaction ``` -## Scope filters +## Rules filters -Further refinement of the policy's scope is achievable through the application of scope filters: +Further refinement of the policy's scope is achievable through the application of rules filters: ```yaml apiVersion: tracee.aquasec.com/v1beta1 kind: Policy metadata: - name: sample-scope-filter + name: sample-rules-filter annotations: - description: sample scope filter + description: sample rules filter spec: scope: - global - rules: + + rules: event: sched_process_exec filters: - pid=1000 ``` -The scope filters supported are: +The rules filters supported are: #### p, pid, processId From 221c86cd5fc367adebb8b4422c2a5434603e9968 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Thu, 12 Sep 2024 16:11:32 +0000 Subject: [PATCH 17/28] added a modified description of scope to the scope section under config, take most of it from the cli flags section --- docs/docs/policies/scopes.md | 55 +++++++++++++++++++++++++++++++++++- 1 file changed, 54 insertions(+), 1 deletion(-) diff --git a/docs/docs/policies/scopes.md b/docs/docs/policies/scopes.md index aa1c87abe122..0b87538e648b 100644 --- a/docs/docs/policies/scopes.md +++ b/docs/docs/policies/scopes.md @@ -1,7 +1,60 @@ # Scopes +```yaml + scope: # Select the scope for tracing events +``` + +## DESCRIPTION + +**scope** allows you to select the scope for tracing events by defining filters. + +## FILTER EXPRESSION + +Filter expressions can be defined to operate on scope options or process metadata. Only events that match all filter expressions will be traced. + +Multiple flags are combined with AND logic, while multiple values within a single flag are combined with OR logic when using the equals operator '='. Multiple values can be specified using ','. + +### NUMERICAL EXPRESSION OPERATORS + +The following numerical fields support the operators '=', '!=', '<', '>', '<=', '>=': + +- uid: Select events from specific user IDs. +- pid: Select events from specific process IDs. + +The following numerical fields only support the operators '=' and '!=': + +- mntns: Select events from specific mount namespace IDs. +- pidns: Select events from specific process namespace IDs. +- tree: Select events that descend from specific process IDs. + +NOTE: Expressions containing '<' or '\>' tokens must be escaped! + +### STRING EXPRESSION OPERATORS + +'=', '!=' + +Available for the following string fields: + +- uts: Select events based on UTS (Unix Timesharing System) names. +- comm: Select events based on process command names. +- container: Select events from specific container IDs. +- executable: Select events based on the executable path. + + + +### BOOLEAN OPERATOR (PREPENDED) + +'!' + +Available for the following boolean field: + +- container: Select events based on whether they originate from a container or not. + +## SPECIAL FILTERS -Scope defines the workload a policy will be observing. +The following special filters can be used within the scope filter expressions: +- new: Select newly created containers or process IDs. +- follow: Select events from the processes that match the criteria and their descendants. The supported scopes are listed below. ### global From 32e80300193a64d421f5af2644474c9cc17566c8 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Mon, 16 Sep 2024 06:51:59 +0000 Subject: [PATCH 18/28] modified rules section under policy because scope filter was confusing, also change a bit the discription of other section --- docs/docs/policies/rules.md | 97 +++++++------------------------------ 1 file changed, 17 insertions(+), 80 deletions(-) diff --git a/docs/docs/policies/rules.md b/docs/docs/policies/rules.md index 7baad8a90cb1..31c9b5fe3e80 100644 --- a/docs/docs/policies/rules.md +++ b/docs/docs/policies/rules.md @@ -1,80 +1,39 @@ # Rules -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. +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. Below are several examples on configuring events in the Tracee Policy. ## Events -Every event that is specified within the `rules` section supports three types of filters: `scope`, `data` and `return value`. +Every event that is specified within the `rules` section supports three types of filters: `process`, `data` and `return value`. ### Type of Events + +The [events](../events/index.md) section provides further information on the type of events that Tracee can track. -**[A syscall](../events/builtin/syscalls/index.md)** +__rules support:__ -Example Scope Section referencing the `open` syscall: +* [Syscall events](../events/builtin/syscalls/index.md) -```bash -spec: - scope: - - global - rules: - event: open -``` - -The name of the syscall is going to be the name of the event. +* [Network events](../events/builtin/network/index.md) -**[Network Events](../events/builtin/network/index.md)** +* [Signatures events](../events/builtin/signatures/index.md) -Network Events can be specified from the list of `Available network events`. +* [Extra events like "bpf_attach"](../events/builtin/extra/bpf_attach.md) -For example: - -```bash -spec: - scope: - - global - rules: - event: net_packet_ipv4 -``` -**[A behavioural Signature](../events/builtin/signatures/index.md)** +## Process filters -To specify one of the behavioral signatures as an event, use the name of the signature from the table in the documentation as the event name: - -```bash -spec: - scope: - - global - rules: - event: anti_debugging -``` - -**[Any of our extra events](../events/builtin/extra/bpf_attach.md)** - -Any of the extra events listed in the Tracee documentation can be listed in the Tracee Policy. - -For instance, to specify the [do_sigaction](../events/builtin/extra/do_sigaction.md) event, provide the name in the YAML manifest: - -```bash -spec: - scope: - - global - rules: - event: do_sigaction -``` - -## Rules filters - -Further refinement of the policy's scope is achievable through the application of rules filters: +Further refinement of the policy's scope is achievable through the application of process filters: ```yaml apiVersion: tracee.aquasec.com/v1beta1 kind: Policy metadata: - name: sample-rules-filter + name: sample-process-filter annotations: - description: sample rules filter + description: sample process filter spec: scope: - global @@ -85,7 +44,7 @@ spec: - pid=1000 ``` -The rules filters supported are: +There are many process filters that are supported. This section includes detailed description of the common process filters options #### p, pid, processId @@ -127,14 +86,6 @@ filters: - hostPid=1000 ``` -#### hostParentProcessId - -```yaml -event: sched_process_exec -filters: - - hostParentProcessId=1 -``` - #### uid, userId ```yaml @@ -143,22 +94,6 @@ filters: - uid=0 ``` -#### mntns, mountNamespace - -```yaml -event: sched_process_exec -filters: - - mntns=4026531840 -``` - -#### pidns, pidNamespace - -```yaml -event: sched_process_exec -filters: - - pidns=4026531836 -``` - #### comm, processName ```yaml @@ -242,7 +177,9 @@ filters: ## Data filter -Events contain data that can be filtered. +Every event contain data that can be filtered. + +For example: ```yaml apiVersion: tracee.aquasec.com/v1beta1 From 18738f9287cb090ac5dbce74a711467c897ec5bb Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Tue, 17 Sep 2024 12:38:25 +0000 Subject: [PATCH 19/28] modify rules and scope sections --- docs/docs/policies/rules.md | 82 ++++++++++++++++++++++++++---------- docs/docs/policies/scopes.md | 15 +------ 2 files changed, 61 insertions(+), 36 deletions(-) diff --git a/docs/docs/policies/rules.md b/docs/docs/policies/rules.md index 31c9b5fe3e80..b6aec594f9a5 100644 --- a/docs/docs/policies/rules.md +++ b/docs/docs/policies/rules.md @@ -1,29 +1,44 @@ # Rules -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. - -Below are several examples on configuring events in the Tracee Policy. +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.`rules` section include: +- events +- filters +Below are an example show casing a policy: +```yaml +apiVersion: tracee.aquasec.com/v1beta1 +kind: Policy +metadata: + name: sample-scope-filter + annotations: + description: sample scope filter +spec: + scope: + - global + rules: + event: openat + filters: + - uid=1000 +``` ## Events -Every event that is specified within the `rules` section supports three types of filters: `process`, `data` and `return value`. - ### Type of Events - -The [events](../events/index.md) section provides further information on the type of events that Tracee can track. +The value of an `event` it's the event name from the supported events. -__rules support:__ +For example: `syscall` event would be the `syscall` name. -* [Syscall events](../events/builtin/syscalls/index.md) +The [events](../events/index.md) section provides further information on the type of events that Tracee can track. -* [Network events](../events/builtin/network/index.md) -* [Signatures events](../events/builtin/signatures/index.md) +## Filters -* [Extra events like "bpf_attach"](../events/builtin/extra/bpf_attach.md) +Filters enable you to refine the policy's scope by specifying conditions for particular events. This allows you to narrow down the criteria to precisely target the events you're interested in, ensuring that the policy applies only under specific circumstances. +Every `event` that is specified within the `rules` section supports three types of filters: `process`, `data` and `return value`. -## Process filters +### Process filters Further refinement of the policy's scope is achievable through the application of process filters: @@ -31,20 +46,19 @@ Further refinement of the policy's scope is achievable through the application o apiVersion: tracee.aquasec.com/v1beta1 kind: Policy metadata: - name: sample-process-filter + name: sample-scope-filter annotations: - description: sample process filter + description: sample scope filter spec: scope: - global - - rules: + rules: event: sched_process_exec filters: - pid=1000 ``` -There are many process filters that are supported. This section includes detailed description of the common process filters options +The scope filters supported are: #### p, pid, processId @@ -86,6 +100,14 @@ filters: - hostPid=1000 ``` +#### hostParentProcessId + +```yaml +event: sched_process_exec +filters: + - hostParentProcessId=1 +``` + #### uid, userId ```yaml @@ -94,6 +116,22 @@ filters: - uid=0 ``` +#### mntns, mountNamespace + +```yaml +event: sched_process_exec +filters: + - mntns=4026531840 +``` + +#### pidns, pidNamespace + +```yaml +event: sched_process_exec +filters: + - pidns=4026531836 +``` + #### comm, processName ```yaml @@ -175,11 +213,9 @@ filters: ``` -## Data filter +### Data filter -Every event contain data that can be filtered. - -For example: +Events contain data that can be filtered. ```yaml apiVersion: tracee.aquasec.com/v1beta1 @@ -209,7 +245,7 @@ tracee -e security_file_open --output json {"timestamp":1680182976364916505,"threadStartTime":1680179107675006774,"processorId":0,"processId":676,"cgroupId":5247,"threadId":676,"parentProcessId":1,"hostProcessId":676,"hostThreadId":676,"hostParentProcessId":1,"userId":131,"mountNamespace":4026532574,"pidNamespace":4026531836,"processName":"systemd-oomd","hostName":"josedonizetti-x","container":{},"kubernetes":{},"eventId":"730","eventName":"security_file_open","matchedPolicies":[""],"argsNum":6,"returnValue":0,"syscall":"openat","stackAddresses":null,"contextFlags":{"containerStarted":false,"isCompat":false},"args":[{"name":"pathname","type":"const char*","value":"/proc/meminfo"},{"name":"flags","type":"string","value":"O_RDONLY|O_LARGEFILE"},{"name":"dev","type":"dev_t","value":45},{"name":"inode","type":"unsigned long","value":4026532041},{"name":"ctime","type":"unsigned long","value":1680179108391999988},{"name":"syscall_pathname","type":"const char*","value":"/proc/meminfo"}]} ``` -## Return value filter +### Return value filter Return values can also be filtered. diff --git a/docs/docs/policies/scopes.md b/docs/docs/policies/scopes.md index 0b87538e648b..3dadd96b11fd 100644 --- a/docs/docs/policies/scopes.md +++ b/docs/docs/policies/scopes.md @@ -1,11 +1,6 @@ # Scopes -```yaml - scope: # Select the scope for tracing events -``` - -## DESCRIPTION -**scope** allows you to select the scope for tracing events by defining filters. +`scope` allows you to select the scope for tracing events by defining filters. ## FILTER EXPRESSION @@ -49,13 +44,7 @@ Available for the following boolean field: - container: Select events based on whether they originate from a container or not. -## SPECIAL FILTERS - -The following special filters can be used within the scope filter expressions: - -- new: Select newly created containers or process IDs. -- follow: Select events from the processes that match the criteria and their descendants. -The supported scopes are listed below. +## Supported Scopes ### global From 849ccf2ecbf8625f174d761f83c04b56473da6b7 Mon Sep 17 00:00:00 2001 From: Shoham Yosef Bitton <141840572+ShohamBit@users.noreply.github.com> Date: Wed, 18 Sep 2024 14:20:20 +0300 Subject: [PATCH 20/28] Update docs/docs/install/config/index.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gregório G. --- docs/docs/install/config/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/install/config/index.md b/docs/docs/install/config/index.md index 4133a6a6d517..40479a1e121c 100644 --- a/docs/docs/install/config/index.md +++ b/docs/docs/install/config/index.md @@ -150,7 +150,7 @@ signatures-dir: "" To learn about how to apply configuration to Tracee, please refer to the [CLI](./cli.md) or [Kubernetes](./kubernetes.md) specific guides, depending on how you deploy Tracee. - - __NOTE__: The YAML examples can be translated to JSON as well + - __NOTE__: The YAML examples can be translated to JSON as well. ## Common configurations From 4418b27cd4912e6c2e54f28c87a94cfe333de51f Mon Sep 17 00:00:00 2001 From: Shoham Yosef Bitton <141840572+ShohamBit@users.noreply.github.com> Date: Wed, 18 Sep 2024 14:20:37 +0300 Subject: [PATCH 21/28] Update docs/docs/install/config/cli.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gregório G. --- docs/docs/install/config/cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/install/config/cli.md b/docs/docs/install/config/cli.md index b8d626a43692..f9e5bef8e9f6 100644 --- a/docs/docs/install/config/cli.md +++ b/docs/docs/install/config/cli.md @@ -9,4 +9,4 @@ To use the `--config` flag, you need to provide the path to the configuration fi ```console tracee --config /path/to/tracee-config.yaml ``` -__NOTE:__ you can find an example config file in [here](/examples/config/) \ No newline at end of file +__NOTE:__ you can find an example config file in [here](/examples/config/). \ No newline at end of file From 1e02ab462091b18283d804373fe155f60f2f7e39 Mon Sep 17 00:00:00 2001 From: Shoham Yosef Bitton <141840572+ShohamBit@users.noreply.github.com> Date: Wed, 18 Sep 2024 14:20:51 +0300 Subject: [PATCH 22/28] Update docs/docs/policies/rules.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gregório G. --- docs/docs/policies/rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/policies/rules.md b/docs/docs/policies/rules.md index b6aec594f9a5..3c675282b4bf 100644 --- a/docs/docs/policies/rules.md +++ b/docs/docs/policies/rules.md @@ -6,7 +6,7 @@ It is possible to define multiple events within each policy.`rules` section incl - events - filters -Below are an example show casing a policy: +Below is an example showcasing a policy: ```yaml apiVersion: tracee.aquasec.com/v1beta1 kind: Policy From 3aeaf76b9454d962f9c298cee9cc1d9aa26327b9 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Wed, 18 Sep 2024 11:52:27 +0000 Subject: [PATCH 23/28] resolve changes --- docs/docs/flags/scope.1.md | 4 + docs/docs/install/config/index.md | 147 +----------------------------- docs/docs/policies/rules.md | 14 ++- docs/man/scope.1 | 9 +- 4 files changed, 23 insertions(+), 151 deletions(-) diff --git a/docs/docs/flags/scope.1.md b/docs/docs/flags/scope.1.md index 5c7bfc89e35b..b64560a5e54b 100644 --- a/docs/docs/flags/scope.1.md +++ b/docs/docs/flags/scope.1.md @@ -49,7 +49,11 @@ Available for the following string fields: - container: Select events from specific container IDs. - executable: Select events based on the executable path. +Strings can be compared as a prefix if ending with '\*', or as a suffix if starting with '\*'. +NOTE: Expressions containing '\*' token must be escaped! + +you can learn more about the wildcard in the [`event` section](./events.1.md) ### BOOLEAN OPERATOR (PREPENDED) diff --git a/docs/docs/install/config/index.md b/docs/docs/install/config/index.md index 4133a6a6d517..f01134e1c341 100644 --- a/docs/docs/install/config/index.md +++ b/docs/docs/install/config/index.md @@ -2,154 +2,11 @@ Tracee has many different options and settings that control how Tracee operates. -A complete config file with all available options can be found [here](https://github.com/aquasecurity/tracee/blob/main/examples/config/global_config.yaml). Most of the options are documented in different sections in the documentation. -To learn about all available configuration options please see [this document](https://github.com/aquasecurity/tracee/blob/main/examples/config/global_config.yaml). - -This section includes detailed description of the common configurable options. - -```yaml -blob-perf-buffer-size: 1024 -cache: - type: none - size: 1024 - -proctree: - source: none - cache: - process: 8192 - thread: 4096 - cache-ttl: - process: 60 - thread: 60 - -capabilities: - bypass: false - add: - - cap_sys_admin - - cap_syslog - drop: - - cap_chown - -cri: - - runtime: - name: containerd - socket: /var/run/containerd/containerd.sock - - runtime: - name: docker - socket: /var/run/docker.sock - -healthz: false -install-path: /tmp/tracee -listen-addr: :3366 -log: - level: info - file: "/path/to/log/file.log" - aggregate: - enabled: true - flush-interval: "5s" - filters: - libbpf: false - in: - msg: - - SampleMessage1 - - SampleMessage2 - pkg: - - package1 - - package2 - file: - - file1.go - - file2.go - level: - - warn - - error - regex: - - ^pattern1 - - ^pattern2 - out: - msg: - - ExcludedMessage1 - pkg: - - excludedPackage - file: - - excludedFile.go - level: - - debug - regex: - - ^excludedPattern - -metrics: false -output: - json: - files: - - stdout - - table: - files: - - /path/to/table1.out - - /path/to/table2.out - - table-verbose: - files: - - stdout - - gotemplate: - template: /path/to/my_template1.tmpl - files: - - /path/to/output1.out - - /path/to/output2.out - - forward: - - forward1: - protocol: tcp - user: user - password: pass - host: 127.0.0.1 - port: 24224 - tag: tracee1 - - forward2: - protocol: udp - user: user - password: pass - host: 127.0.0.1 - port: 24225 - tag: tracee2 - - webhook: - - webhook1: - protocol: http - host: localhost - port: 8000 - timeout: 5s - gotemplate: /path/to/template/test.tmpl - content-type: application/json - - webhook2: - protocol: http - host: localhost - port: 9000 - timeout: 3s - gotemplate: /path/to/template/test.tmpl - content-type: application/json - - options: - none: false - stack-addresses: true - exec-env: false - relative-time: true - exec-hash: dev-inode - parse-arguments: true - sort-events: false - -perf-buffer-size: 1024 -pprof: false -pyroscope: false -rego: - partial-eval: true - aio: true -signatures-dir: "" -``` To learn about how to apply configuration to Tracee, please refer to the [CLI](./cli.md) or [Kubernetes](./kubernetes.md) specific guides, depending on how you deploy Tracee. +A complete config file with all available options can be found [here](https://github.com/aquasecurity/tracee/blob/main/examples/config/global_config.yaml). Most of the options are documented in different sections in the documentation. + - __NOTE__: The YAML examples can be translated to JSON as well ## Common configurations diff --git a/docs/docs/policies/rules.md b/docs/docs/policies/rules.md index b6aec594f9a5..5144e4107914 100644 --- a/docs/docs/policies/rules.md +++ b/docs/docs/policies/rules.md @@ -1,10 +1,14 @@ # Rules -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.`rules` section include: -- events -- filters +Rules are part of the Tracee Policy, `rules` let you define which events to trace. + +`rules` have 2 sections: +- events: let you define which events you wan to trace +- filters: enable you to refine the policy's scope + +Tracee support many kind of events to tracee you can find which events you can trace in [Events section](/docs/docs/events/index.md) + +- **NOTE:** It is possible to define multiple events within each policy. Below are an example show casing a policy: ```yaml diff --git a/docs/man/scope.1 b/docs/man/scope.1 index 77b537465433..641f51bfc36e 100644 --- a/docs/man/scope.1 +++ b/docs/man/scope.1 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 3.2 .\" -.TH "TRACEE\-SCOPE" "1" "2024/06" "" "Tracee Scope Flag Manual" +.TH "TRACEE\-SCOPE" "1" "2024/09" "" "Tracee Scope Flag Manual" .SS NAME tracee \f[B]\-\-scope\f[R] \- Select the scope for tracing events .SS SYNOPSIS @@ -51,6 +51,13 @@ comm: Select events based on process command names. container: Select events from specific container IDs. .IP \[bu] 2 executable: Select events based on the executable path. +.PP +Strings can be compared as a prefix if ending with `*', or as a suffix +if starting with `*'. +.PP +NOTE: Expressions containing `*' token must be escaped! +.PP +you can learn more about the wildcard in the \f[CR]event\f[R] section .SS BOOLEAN OPERATOR (PREPENDED) `!' .PP From f203f87849dbd443f8c3afab31c9c3bfdd3ad7a6 Mon Sep 17 00:00:00 2001 From: Shoham Yosef Bitton <141840572+ShohamBit@users.noreply.github.com> Date: Sun, 22 Sep 2024 20:50:23 +0300 Subject: [PATCH 24/28] Update docs/docs/flags/scope.1.md --- docs/docs/flags/scope.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/flags/scope.1.md b/docs/docs/flags/scope.1.md index b64560a5e54b..b7f9c9675d55 100644 --- a/docs/docs/flags/scope.1.md +++ b/docs/docs/flags/scope.1.md @@ -53,7 +53,7 @@ Strings can be compared as a prefix if ending with '\*', or as a suffix if start NOTE: Expressions containing '\*' token must be escaped! -you can learn more about the wildcard in the [`event` section](./events.1.md) +you can learn more about the wildcard in the [`event` section](./events.1.md). ### BOOLEAN OPERATOR (PREPENDED) From 356dedc904cacec950e1be47f5418227fbf42167 Mon Sep 17 00:00:00 2001 From: Shoham Yosef Bitton <141840572+ShohamBit@users.noreply.github.com> Date: Sun, 22 Sep 2024 20:50:40 +0300 Subject: [PATCH 25/28] Update docs/docs/policies/rules.md --- docs/docs/policies/rules.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/policies/rules.md b/docs/docs/policies/rules.md index 95abc0768709..a58474021d4d 100644 --- a/docs/docs/policies/rules.md +++ b/docs/docs/policies/rules.md @@ -3,8 +3,8 @@ Rules are part of the Tracee Policy, `rules` let you define which events to trace. `rules` have 2 sections: -- events: let you define which events you wan to trace -- filters: enable you to refine the policy's scope +- events: let you define which events you want to trace. +- filters: enable you to refine the policy's scope. Tracee support many kind of events to tracee you can find which events you can trace in [Events section](/docs/docs/events/index.md) From ee2d539439d4ed12465f1fa6065f2124d613f067 Mon Sep 17 00:00:00 2001 From: Shoham Yosef Bitton <141840572+ShohamBit@users.noreply.github.com> Date: Sun, 22 Sep 2024 20:50:49 +0300 Subject: [PATCH 26/28] Update docs/docs/policies/rules.md --- docs/docs/policies/rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/policies/rules.md b/docs/docs/policies/rules.md index a58474021d4d..3d79262ad8e7 100644 --- a/docs/docs/policies/rules.md +++ b/docs/docs/policies/rules.md @@ -6,7 +6,7 @@ Rules are part of the Tracee Policy, `rules` let you define which events to trac - events: let you define which events you want to trace. - filters: enable you to refine the policy's scope. -Tracee support many kind of events to tracee you can find which events you can trace in [Events section](/docs/docs/events/index.md) +Tracee support many kind of events to tracee you can find which events you can trace in [Events section](/docs/docs/events/index.md). - **NOTE:** It is possible to define multiple events within each policy. From 65952c702b159b03e2668633db5112bceefd10b7 Mon Sep 17 00:00:00 2001 From: Shoham Yosef Bitton <141840572+ShohamBit@users.noreply.github.com> Date: Sun, 22 Sep 2024 20:50:57 +0300 Subject: [PATCH 27/28] Update docs/docs/policies/rules.md --- docs/docs/policies/rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/policies/rules.md b/docs/docs/policies/rules.md index 3d79262ad8e7..3561feb31e93 100644 --- a/docs/docs/policies/rules.md +++ b/docs/docs/policies/rules.md @@ -31,7 +31,7 @@ spec: ### Type of Events The value of an `event` it's the event name from the supported events. -For example: `syscall` event would be the `syscall` name. +For example: `syscall` event would be the `syscall` event name. The [events](../events/index.md) section provides further information on the type of events that Tracee can track. From f9667c2f26a74630135d8544e0793ed888d32268 Mon Sep 17 00:00:00 2001 From: Shoham Yosef Bitton <141840572+ShohamBit@users.noreply.github.com> Date: Sun, 22 Sep 2024 20:51:08 +0300 Subject: [PATCH 28/28] Update docs/docs/policies/rules.md --- docs/docs/policies/rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/policies/rules.md b/docs/docs/policies/rules.md index 3561feb31e93..942de4a70fa4 100644 --- a/docs/docs/policies/rules.md +++ b/docs/docs/policies/rules.md @@ -33,7 +33,7 @@ The value of an `event` it's the event name from the supported events. For example: `syscall` event would be the `syscall` event name. -The [events](../events/index.md) section provides further information on the type of events that Tracee can track. +The [events](../events/index.md) section provides further information on the type of events that Tracee can trace. ## Filters