docs: installation section (#3627)

Co-authored-by: Rafael David Tinoco <[email protected]>

docs/docs/deep-dive/ksyms.md

@@ -0,0 +1,22 @@
+# About Kernel symbols
+
+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:
+
+**Kernel Configuration**: If compiled without `CONFIG_KALLSYMS`, the kernel
+won't have this file. This option enables the kernel symbol table, used mainly
+for debugging.
+
+**Security Protocols**: Some systems might hide kernel symbols to prevent
+potential exploits. The `/proc/kallsyms` file could appear incomplete or even
+empty to non-root users. The `CONFIG_KALLSYMS_ALL` option ensures all symbols
+are visible.
+
+The Linux kernel also offers a setting, `/proc/sys/kernel/kptr_restrict`, to
+control kernel symbol visibility:
+
+- **0**: No restrictions.
+- **1**: Hide from non-privileged users.
+- **2**: Hide from all users.

docs/docs/install/index.md

@@ -1,10 +1,12 @@
-# Getting Tracee
+# Installing Tracee
 
-You're able to use tracee by any of these means:
+1. Tracee executable binary is available in under [releases](https://github.com/aquasecurity/tracee/releases).
+2. Tracee container image is available in Docker Hub as [aquasec/tracee](https://hub.docker.com/r/aquasec/tracee).
+3. Tracee Helm chart is available in Aqua Security's registry: `https://aquasecurity.github.io/helm-charts/` as `tracee`.
 
-1. [docker hub container image](https://hub.docker.com/r/aquasec/tracee)
-2. [distributed binaries](https://github.com/aquasecurity/tracee/releases) (`tracee.tar.gz`).
-3. [building from the source](../../contributing/building/building.md)
-4. [building environment](../../contributing/building/environment.md)
-5. [building container images](../../contributing/building/containers.md)
-6. [building OS packages](../../contributing/building/packaging.md)
+It might also be available in various package managers managed by the community.
+
+Before continuing, please make sure Tracee is supported on your environment by reading the [Prerequisites](./prerequisites.md).
+
+To get started with Docker, please read the [Docker guide](./docker.md).
+To get started on Kubernetes, please read the [Kubernetes guide](./kubernetes.md).

docs/docs/install/prerequisites.md

@@ -1,36 +1,74 @@
 # Prerequisites for running Tracee
 
-A longterm supported kernel: 5.4, 5.10, 5.15, 5.18, 6.1, 6.2. Check
-[kernel.org](https://kernel.org) for current supported kernels.
+Tracee is heavily dependent on Linux and does not support any other operating system.
 
-!!! Note
-    Most distributions long-term supported kernels are supported as well,
-    including CentOS8 4.18 kernel.
+<!--
+every section should roughly cover:
+1. what is this prereq
+2. why is it needed
+3. how to test if I'm compliant
+4. link for details and help
+-->
 
-- For **tracee:{{ git.tag }}** docker image, you should have one of the two:
+## Kernel version
 
-    1. A kernel that has `/sys/kernel/btf/vmlinux` file available
-    2. A kernel supported through [BTFHUB]
-    > see [libbpf CO-RE documentation] for more info
+To run Tracee a modern longterm supported kernel is needed: 5.4, 5.10, 5.15, 5.18, 6.1, 6.2.
 
-## Permissions
+You can check [kernel.org](https://kernel.org) for current supported kernels.  
+In addition to upstream kernels, most distributions long-term supported kernels are supported as well, including CentOS8 4.18 kernel.
 
-For using the eBPF Linux subsystem, Tracee needs to run with sufficient
-capabilities:
+## BTF
 
-* Manage eBPF maps limits (`CAP_SYS_RESOURCE`)
-* Load and Attach eBPF programs:
-    1. `CAP_BPF`+`CAP_PERFMON` for recent kernels (>=5.8) where the kernel perf paranoid value in `/proc/sys/kernel/perf_event_paranoid` is equal to 2 or less
-    2. or `CAP_SYS_ADMIN` otherwise
-* `CAP_SYS_PTRACE` (to collect information about processes)
-* `CAP_NET_ADMIN` (to use tc for packets capture)
-* `CAP_SETPCAP` (if given - used to reduce bounding set capabilities)
-* `CAP_SYSLOG` (to access kernel symbols through /proc/kallsyms)
-* On some environments (e.g. Ubuntu) `CAP_IPC_LOCK` might be required as well.
-* On cgroup v1 environments, `CAP_SYS_ADMIN` is recommended if running from a
-  container in order to allow tracee to mount the cpuset cgroup controller.
+Tracee needs low-level type information about the running kernel. Most modern Linux distributions ship with the [BTF](https://www.kernel.org/doc/html/latest/bpf/btf.html) feature that exposes this information.  
 
-> Alternatively, you may [bypass the capabilities dropping feature](../../docs/deep-dive/dropping-capabilities.md) if facing any issue.
+To test if this feature is enabled in your environment, check if `/sys/kernel/btf/vmlinux` exists. If absent, you might need to upgrade to a newer OS version, or contact your OS provider.
 
-[libbpf CO-RE documentation]: https://github.com/libbpf/libbpf#bpf-co-re-compile-once--run-everywhere
-[BTFHUB]: https://github.com/aquasecurity/btfhub-archive
+## Kernel symbols
+
+Certain Tracee events require access to the Kernel Symbols Table, a feature present in many Linux distributions.
+
+To test if this feature is enabled in your environment, check if `/proc/kallsyms` exists. If absent, contact your OS provider. 
+
+Alternatively, you can disable the following events which depends on kallsyms:
+
+- `dirty_pipe_splice` (detects dirty pipe vulnerability - CVE-2022-0847)
+- `hooked_syscall` (detects system call interception technique)
+- `hidden_kernel_module` (detects hidden kernel modules technique)
+- `hooked_proc_fops` (detects procfs file operations interception technique)
+- `print_net_seq_ops` (related hooked_seq_ops event)
+- `hooked_seq_ops` (detects network packets interception technique)
+- `print_mem_dump` (allows memory dumping from symbols to signatures can use)
+
+For more information and help about kernel symbols, please see [here](../deep-dive/ksyms.md).
+
+## OS information
+
+Tracee will try to probe the running OS and kernel to detect available capabilities. For this, it needs access to some standard informative files:
+
+- For OS information please make sure the file `/etc/os-release` is available.
+- For Kernel information please make sure on of the files `/boot/config-$(uname-r)` OR `/proc/config.gz` is available.
+
+For more information and help about OS info files, please see [here](../deep-dive/os-info.md).
+
+## Process capabilities
+
+Tracee needs non-trivial capabilities to instrument the kernel. The easiest way is run Tracee as "privileged" or "root".  
+
+If you want to run Tracee with "least privileges", here are the required capabilities and justifications:
+
+- Manage eBPF maps limits (`CAP_SYS_RESOURCE`)
+- Load and Attach eBPF programs:
+    - `CAP_BPF`+`CAP_PERFMON` for recent kernels (>=5.8) where the kernel perf paranoid value in `/proc/sys/kernel/perf_event_paranoid` is equal to 2 or less
+    - or `CAP_SYS_ADMIN` otherwise
+- `CAP_SYS_PTRACE` (to collect information about processes)
+- `CAP_NET_ADMIN` (to use tc for packets capture)
+- `CAP_SETPCAP` (if given - used to reduce bounding set capabilities)
+- `CAP_SYSLOG` (to access kernel symbols through /proc/kallsyms)
+- On some environments (e.g. Ubuntu) `CAP_IPC_LOCK` might be required as well.
+- On cgroup v1 environments, `CAP_SYS_ADMIN` is recommended if running from a container in order to allow tracee to mount the cpuset cgroup controller.
+
+For more information and help about process capabilities, please see [here](../deep-dive/dropping-capabilities.md).
+
+## Processor architecture
+
+Tracee supports x86 and arm64 processors.

mkdocs.yml

@@ -597,6 +597,7 @@ nav:
                 - Caching Events: docs/deep-dive/caching-events.md
                 - Ordering Events: docs/deep-dive/ordering-events.md
                 - Dropping Capabilities: docs/deep-dive/dropping-capabilities.md
+                - Kernel Symbols: docs/deep-dive/ksyms.md
                 - Secure Tracing: docs/deep-dive/secure-tracing.md
     - Contributing:
           - Overview: contributing/overview.md