From 5f9d458a96b867dbec2889fef1d12e095d277052 Mon Sep 17 00:00:00 2001
From: Andrei Fedotov <anfedotoff@yandex-team.ru>
Date: Tue, 24 Sep 2024 16:15:49 +0300
Subject: [PATCH]  docs: imaHash flag for Post Action selector

Signed-off-by: Andrei Fedotov <anfedotoff@yandex-team.ru>
---
 .../docs/concepts/tracing-policy/selectors.md | 118 ++++++++++++++++++
 1 file changed, 118 insertions(+)

diff --git a/docs/content/en/docs/concepts/tracing-policy/selectors.md b/docs/content/en/docs/concepts/tracing-policy/selectors.md
index 02aa9dacdb5..9c44cca76f7 100644
--- a/docs/content/en/docs/concepts/tracing-policy/selectors.md
+++ b/docs/content/en/docs/concepts/tracing-policy/selectors.md
@@ -1052,6 +1052,124 @@ Compact output will display missing addresses as `0x0`, see the above note on
 `--expose-stack-addresses` for more info.
 {{< /note >}}
 
+#### File hash collection with IMA
+
+`Post` takes the `imaHash` parameter, when turned to `true` (by default to
+`false`) it adds file hashes in LSM events calculated by Linux integrity subsystem.
+The following list of LSM hooks is supported:
+
+- bprm_check_security
+- bprm_committed_creds
+- bprm_committing_creds
+- bprm_creds_from_file
+- file_ioctl
+- file_lock
+- file_open
+- file_post_open
+- file_receive
+- mmap_file
+
+First, you need to be sure that LSB BPF is [enabled](https://tetragon.io/docs/concepts/tracing-policy/hooks/#lsm-bpf).
+
+To verify if IMA-measurement is available use the following command:
+
+```shell
+cat /boot/config-$(uname -r) | grep "CONFIG_IMA\|CONFIG_INTEGRITY"
+```
+
+The output should be similar to this if IMA-measurement is supported:
+
+```
+CONFIG_INTEGRITY=y
+CONFIG_IMA=y
+```
+
+If provided above conditions are met, you can enable IMA-measurement by modifying `/etc/deault/grub`:
+
+```
+GRUB_CMDLINE_LINUX="lsm=integrity,bpf ima_policy=tcb"
+```
+
+Then, update the grub configuration and restart the system.
+
+`ima_policy=` is used to define which files will be measured. `tcb` measures all executables run,
+all mmap'd files for execution (such as shared libraries), all kernel modules loaded,
+and all firmware loaded. Additionally, a files opened for read by root are measured as well.
+`ima_policy=` can be specified multiple times, and the result is the union of the policies.
+To know more about `ima_policy` you can follow this [link](https://ima-doc.readthedocs.io/en/latest/ima-policy.html).
+
+{{< note >}}
+Hash calculation with IMA subsystem and LSM BPF is supported from 5.11 kernel version.
+For kernel versions below 6.1 is recommended to mount filesystems with `iversion`. Mounting with `iversion`
+helps IMA not recalculating hash if file is not changed. From kernel 6.1 `iversion` is by default.
+It is not necessary to enable IMA to calculate hashes with Tetragon if you have kernel 6.1+.
+But hashes will be recalculated no matter if file is not changed. See implementation details of
+`bpf_ima_file_hash` helper.
+{{< /note >}}
+
+The provided example of `TracingPolicy` collects hashes of executed binaries from
+`zsh` and `bash` interpreters:
+
+```yaml
+apiVersion: cilium.io/v1alpha1
+kind: TracingPolicy
+spec:
+  lsmhooks:
+  - hook: "bprm_check_security"
+    args:
+      - index: 0
+        type: "linux_binprm"
+    selectors:
+    - matchBinaries:
+      - operator: "In"
+        values:
+        - "/usr/bin/zsh"
+        - "/usr/bin/bash"
+      matchActions:
+        - action: Post
+          imaHash: true
+```
+
+LSM event with file hash can look like this:
+
+```json
+{
+  "process_lsm": {
+    "process": {
+        ...
+    },
+    "parent": {
+        ...
+    },
+    "function_name": "bprm_check_security",
+    "policy_name": "file-integrity-monitoring",
+    "args": [
+      {
+        "linux_binprm_arg": {
+          "path": "/usr/bin/grep",
+          "permission": "-rwxr-xr-x"
+        }
+      }
+    ],
+    "action": "KPROBE_ACTION_POST",
+    "ima_hash": "sha256:73abb4280520053564fd4917286909ba3b054598b32c9cdfaf1d733e0202cc96"
+  },
+}
+```
+
+`ima_hash` field contains information about hashing algorithm and the hash value itself
+separated by ':'.
+
+This output can be enhanced in a more human friendly using the
+`tetra getevents -e PROCESS_LSM -o compact` command.
+
+```
+🔒 LSM     user-nix /usr/bin/zsh bprm_check_security
+   /usr/bin/cat sha256:dd5526c5872cce104a80f4d4e7f787c56ab7686a5b8dedda0ba4e8b36a3c084c
+🔒 LSM     user-nix /usr/bin/zsh bprm_check_security
+   /usr/bin/grep sha256:73abb4280520053564fd4917286909ba3b054598b32c9cdfaf1d733e0202cc96
+```
+
 ### NoPost action
 
 The `NoPost` action can be used to suppress the event to be generated, but at