From 3fc4ac4e98965f2d04d22ab3218ab8f748288038 Mon Sep 17 00:00:00 2001
From: Andrei Fedotov <anfedotoff@yandex-team.ru>
Date: Tue, 3 Sep 2024 15:27:43 +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 | 103 ++++++++++++++++++
 1 file changed, 103 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..00f1a05a1e0 100644
--- a/docs/content/en/docs/concepts/tracing-policy/selectors.md
+++ b/docs/content/en/docs/concepts/tracing-policy/selectors.md
@@ -1052,6 +1052,109 @@ 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:
+
+- file_open
+- mmap_file
+- bprm_check_security
+
+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).
+
+
+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