docs: fixes and changes after #3641 (#3655)

* rename deep-dive to advanced

* move forensics

* move data sources

* redo config section

* healthz

* redo container engines

Readme.md

@@ -5,7 +5,7 @@
 [docker-guide]:https://aquasecurity.github.io/tracee/latest/docker.md
 [kubernetes-guide]:https://aquasecurity.github.io/tracee/latest/kubernetes.md
 [prereqs]:https://aquasecurity.github.io/tracee/latest/docs/install/prerequisites.md
-[macfaq]:https://aquasecurity.github.io/tracee/latest/docs/deep-dive/mac.md
+[macfaq]:https://aquasecurity.github.io/tracee/latest/docs/advanced/mac.md
 Before moving on, please consider giving us a GitHub star ⭐️. Thank you!
 
 ## About Tracee
@@ -27,6 +27,7 @@ Tracee should run on most common Linux distributions and kernels. For compatibil
 docker run --name tracee \
   --pid=host --cgroupns=host --privileged \
   -v /etc/os-release:/etc/os-release-host:ro \
+  -v /var/run:/var/run \
   aquasec/tracee:latest
 ```
 

docs/docs/data-sources/containers.md → docs/docs/advanced/data-sources/containers.md

@@ -6,7 +6,7 @@ The [data source](./overview.md) feature makes the information gathered from act
 
 ## Internal Data Organization
 
-From the [data-sources documentation](../data-sources/overview.md), you'll see that searches use keys. It's a bit like looking up information with a specific tag (or a key=value storage).
+From the [data-sources documentation](./overview.md), you'll see that searches use keys. It's a bit like looking up information with a specific tag (or a key=value storage).
 
 The `containers data source` operates straightforwardly. Using `string` keys, which represent the container IDs, you can fetch `map[string]string` values as shown below:
 

docs/docs/data-sources/process-tree.md → docs/docs/advanced/data-sources/process-tree.md

@@ -197,7 +197,7 @@ func (sig *e2eProcessTreeDataSource) checkProcess(eventObj *trace.Event) error {
     }
 ```
 
-From the [data-sources documentation](../data-sources/overview.md), you'll see that searches use keys. It's a bit like looking up information with a specific tag (or a key=value storage).
+From the [data-sources documentation](./overview.md), you'll see that searches use keys. It's a bit like looking up information with a specific tag (or a key=value storage).
 
 In the provided example, the `eventObj.ProcessEntityId` key (which is the process hash accompanying the event being handled) is utilized alongside the `datasource.ProcKey{}` argument to search for a process in the process tree. The resulting process is the one associated with the event under consideration.
 

docs/docs/flags/capabilities.1.md

@@ -45,4 +45,4 @@ Please note that the available capabilities will depend on the running system. F
   --capabilities drop=cap_chown
   ```
 
-Please refer to the [documentation](../deep-dive/dropping-capabilities.md) for more information on environment capabilities.
+Please refer to the [documentation](../advanced/dropping-capabilities.md) for more information on environment capabilities.

docs/docs/install/config/cli.md

@@ -1,28 +1,7 @@
-# Configuring Tracee through the CLI
+# Configuring Tracee with 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:
+To use the `--config` flag, specifying the path to the configuration file:
 
 ```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.

docs/docs/install/config/index.md

@@ -0,0 +1,148 @@
+# 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.
+
+```yaml
+blob-perf-buffer-size: 1024
+cache:
+    type: none
+    size: 1024
+
+proctree:
+    source: none
+    cache:
+        process: 8192
+        thread: 4096
+
+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
+
+    gob:
+        files:
+        - /path/to/gob1.out
+
+    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: false
+        parse-arguments: true
+        sort-events: false
+
+perf-buffer-size: 1024
+pprof: false
+pyroscope: false
+rego:
+    partial-eval: true
+    aio: true
+signatures-dir: ""
+```

docs/docs/install/config/kubernetes.md

@@ -1,11 +1,8 @@
-# Kubernetes Config
+# Configuring Tracee in Kubernetes
 
-## Configmap
+In Kubernetes, Tracee uses a ConfigMap, called `tracee` to make Tracee configuration accessible. The ConfigMap includes a data file called `config.yaml` with the desired configuration. For example:
 
-Tracee ConfigMap exposed [tracee configuration](https://github.com/aquasecurity/tracee/blob/main/examples/config/global_config.yaml) to the deployment.
-
-```
----
+```yaml
 apiVersion: v1
 kind: ConfigMap
 metadata:
@@ -19,42 +16,46 @@ data:
     cache:
       - 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:
-        - info
-    output:
-        - json
-        - option:parse-arguments
-```
-
-## Customizing
+```
+
+## Kubectl
+
+You can use `kubectl` to interact with it:
+
+View:
+
+```shell
+kubectl get cm tracee -n tracee
+```
+
+Edit:
+
+```shell
+kubectl edit cm tracee -n tracee
+```
+
+## Helm
 
 You can customize specific options with the helm installation:
 
 ```
-# setting blob-perf-event-size
 helm install tracee aqua/tracee \
-        --namespace tracee-system --create-namespace \
+        --namespace tracee --create-namespace \
         --set config.blobPerfEventSize=1024
+```
 
+or after installation:
 
-# setting a different output
+```
 helm install tracee aqua/tracee \
-        --namespace tracee-system --create-namespace \
+        --namespace tracee --create-namespace \
         --set config.output[0]=table \
-        --set config.output[1]=option:parse-arguments
 ```
 
-Or you can pass a config file directly:
+or to provide a complete config file:
 
 ```
  helm install tracee aqua/tracee \
-        --namespace tracee-system --create-namespace \
-        --set-file traceeConfig=<path/to/config/file>
+        --namespace tracee --create-namespace \
+        --set-file traceeConfig=myconfig.yaml
 ```

docs/docs/install/container-engines.md

@@ -1,55 +1,31 @@
 # Tracee Events Container Enrichment
 
-Tracee is capable of **extracting information about running containers**. It
-does that by tracking container namespaces creation kernel events and enriching
-those events by communicating with the relevant container's runtime and SDK.
+Tracee events provide context about where the collected events originated from, including information about the originating container if available. To gather this information, Tracee needs to communicate with the relevant container runtime.
 
-1. Running **tracee** manually
+## Detecting container runtime
 
-    If running tracee directly (not in a container), it will automatically
-    search for known supported runtimes in their socket's default locations.
-    You may track if tracee was able to find the container runtime socket by
-    running tracee with `--log debug` option. There will be a line to each known
-    runtime engine socket location and a message saying if tracee wass able to
-    find it or not.
+Tracee will automatically search for known supported runtimes by looking for their socket files in known locations.  
+You may track if Tracee was able to find the container runtime socket by running Tracee with `debug` log level. There will be a line to each known runtime engine socket and a message sharing it's status.
 
-2. Running **tracee** using a docker container
+When running Tracee in a container, the runtime sockets must be mounted to be available for Tracee.
 
-    When running tracee from a container, the runtime sockets must be manually
-    mounted in order for the enrichment features to work.
+For example, if running Tracee using Docker, and ContainerD runtime:
 
-    Using containerd as our runtime for example, this can be done by running
-    tracee like:
+```console
+docker run \
+    --pid=host --cgroupns=host --privileged \
+    -v /etc/os-release:/etc/os-release-host:ro \
+    -v /var/run/containerd:/var/run/containerd \
+    aquasec/tracee
+```
 
-    ```console
-    docker run \
-        --name tracee --rm -it \
-        --pid=host --cgroupns=host --privileged \
-        -v /etc/os-release:/etc/os-release-host:ro \
-        -v /var/run/containerd:/var/run/containerd \
-        aquasec/tracee:{{ git.tag }}
-    ```
-
-    Most container runtimes have their sockets installed by default in
-    `/var/run`. If your system includes multiple container runtimes, tracee can
-    track them all, however one should mount either all their runtime sockets or
-    `/var/run` in it's entirety to do so.
+Most container runtimes have their sockets installed by default in `/var/run`, so mounting this path can also be a good option.
 
 ## Supported Container Runtime Engines
 
-Currently, tracee will look in the following paths for auto-discovering the listed runtimes:
+Tracee supports the following container runtimes and will look in the following paths for their socket files:
 
-1. Docker:     `/var/run/docker.sock`
+1. Docker: `/var/run/docker.sock`
 2. Containerd: `/var/run/containerd/containerd.sock`
-3. CRI-O:      `/var/run/crio/crio.sock`
-4. Podman:     `/var/run/podman/podman.sock`
-
-!!! Tip
-    **Nested environments** are somewhat tricky with this feature as evidenced
-    by the docker mounting instructions. Tracee does not auto-discover this
-    nesting and so sockets must be appropriately mounted and set up for tracee
-    to enrich all containers correctly.
-
-## Enrichment output
-
-Example of the output.
+3. CRI-O: `/var/run/crio/crio.sock`
+4. Podman: `/var/run/podman/podman.sock`