From 82fb9766b0b04826abfb6cdcce55c449f676947f Mon Sep 17 00:00:00 2001 From: Mahe Tardy Date: Tue, 11 Jul 2023 12:25:58 +0200 Subject: [PATCH] docs: process credential use case reorganization Signed-off-by: Mahe Tardy --- .../linux-process-credentials/_index.md | 66 +++++++++---------- .../linux-process-credentials/syscalls.md | 61 ++++++++++------- 2 files changed, 72 insertions(+), 55 deletions(-) diff --git a/docs/content/en/docs/use-cases/linux-process-credentials/_index.md b/docs/content/en/docs/use-cases/linux-process-credentials/_index.md index 9b82108604a..45ed038d303 100644 --- a/docs/content/en/docs/use-cases/linux-process-credentials/_index.md +++ b/docs/content/en/docs/use-cases/linux-process-credentials/_index.md @@ -17,49 +17,49 @@ actions or to execute commands as another user. The obvious example is as root or another user. An other example is services or containers that can gain high privileges during execution to perform restricted operations. +Process credentials monitoring is a good practice to identify programs +running with high privileges. Tetragon is able to observe process credentials at +different layers of the operating system. Each layer will generate a number of events, +where the upper layer that is the user space layer may generate a low number +of events, where the lower kernel layers could generate a high number of events. -## Process Credentials: - -Linux process credentials include the following types: - -* Traditional UNIX credentials: - - Real User ID - Real Group ID - Effective, Saved and FS User ID - Effective, Saved and FS Group ID - Supplementary groups - -* Linux Capabilities +Depending on the use case, users should chose the right layer at which they want to +monitor process credentials and apply the corresponding +[Tracing Policies]({{< ref "/docs/concepts/tracing-policy" >}}). - Set of permitted capabilities - Set of inheritable capabilities - Set of effective capabilities - Capability bounding set +## Composition of Linux process credentials - The effective capabilities are the ones that a task is actually allowed to make use of itself. +### Traditional UNIX credentials - The inheritable capabilities are the ones that may get passed across execve(). +- Real User ID +- Real Group ID +- Effective, Saved and FS User ID +- Effective, Saved and FS Group ID +- Supplementary groups - The bounding set limits the capabilities that may be inherited across execve(), especially when a binary is executed that will execute as UID 0. +### Linux Capabilities -* Secure management flags (securebits). +- Set of permitted capabilities: a limiting superset for the effective + capabilities. +- Set of inheritable capabilities: the set that may get passed across + `execve(2)`. +- Set of effective capabilities: the set of capabilities a task is actually + allowed to make use of itself. +- Set of bounding capabilities: limits the capabilities that may be inherited + across `execve(2)`, especially when a binary is executed that will execute as + UID 0. - These govern the way the UIDs/GIDs and capabilities are manipulated and inherited over certain operations such as execve(). +### Secure management flags (securebits). -* [Linux Security Module (LSM)](https://www.kernel.org/doc/html/latest/admin-guide/LSM/index.html) +These govern the way the UIDs/GIDs and capabilities are manipulated and +inherited over certain operations such as `execve(2)`. - The LSM framework provides a mechanism for various security checks to be hooked by new kernel extensions. - Tasks can have extra controls part of LSM on what operations they - are allowed to perform. +### Linux Security Module (LSM) +The [LSM framework](https://www.kernel.org/doc/html/latest/admin-guide/LSM/index.html) +provides a mechanism for various security checks to be hooked by new kernel +extensions. Tasks can have extra controls part of LSM on what operations they +are allowed to perform. -Process credentials monitoring is a good practice to identify programs -running with high privileges. Tetragon is able to observe process credentials at -different layers of the operating system. Each layer will generate a number of events, -where the upper layer that is the user space layer may generate a low number -of events, where the lower kernel layers could generate a high number of events. -Depending on the use case, users should chose the right layer at which they want to -monitor process credentials and apply the corresponding [Tracing Policies]({{< ref "/docs/concepts/tracing-policy" >}}). diff --git a/docs/content/en/docs/use-cases/linux-process-credentials/syscalls.md b/docs/content/en/docs/use-cases/linux-process-credentials/syscalls.md index c3ef7bd5f2e..217330e7a63 100644 --- a/docs/content/en/docs/use-cases/linux-process-credentials/syscalls.md +++ b/docs/content/en/docs/use-cases/linux-process-credentials/syscalls.md @@ -1,20 +1,23 @@ --- title: "Credentials change system calls" -weight: 2 -icon: "reference" -description: "Monitor change Credentials System calls" +weight: 1 +icon: "overview" +description: "Monitor credentials change system calls" --- -Tetragon allows to hook at the system calls that directly manipulate the credentials. This allows to determine which process is trying to change its own credentials and the new credentials that could be applied by the kernel. +Tetragon can hook at the system calls that directly manipulate the credentials. +This allows us to determine which process is trying to change its credentials +and the new credentials that could be applied by the kernel. This answers the questions: -> Which process or container is trying to change its own UIDs/GIDs in my cluster? +> Which process or container is trying to change its UIDs/GIDs in my cluster? -> Which process or container is trying to change its own capabilities in my cluster? +> Which process or container is trying to change its capabilities in my +> cluster? - -Before going forward, verify that all pods are up and running, ensure you deploy our Demo Application to explore the Security Observability Events: +Before going forward, verify that all pods are up and running, ensure you +deploy our Demo Application to explore the Security Observability Events: ```bash kubectl create -f https://raw.githubusercontent.com/cilium/cilium/v1.11/examples/minikube/http-sw-app.yaml @@ -34,36 +37,46 @@ kube-system tetragon-sdwv6 2/2 Runnin ## Monitor UIDs/GIDs credential changes -We use the [process.credentials.changes.at.syscalls](https://raw.githubusercontent.com/cilium/tetragon/main/examples/tracingpolicy/process-credentials/process.credentials.changes.at.syscalls.yaml) Tracing Policy that hooks the [setuid()](https://man7.org/linux/man-pages/man2/setuid.2.html) system calls family: - - setuid(), setgid(), setfsuid(), setfsgid(), setreuid(), setregid(), setresuid() and setresgid(). +We use the +[process.credentials.changes.at.syscalls](https://raw.githubusercontent.com/cilium/tetragon/main/examples/tracingpolicy/process-credentials/process.credentials.changes.at.syscalls.yaml) +Tracing Policy that hooks the +[`setuid`](https://man7.org/linux/man-pages/man2/setuid.2.html) system calls +family: +- `setuid` +- `setgid` +- `setfsuid` +- `setfsgid` +- `setreuid` +- `setregid` +- `setresuid` +- `setresgid` -So let's apply the [process.credentials.changes.at.syscalls](https://raw.githubusercontent.com/cilium/tetragon/main/examples/tracingpolicy/process-credentials/process.credentials.changes.at.syscalls.yaml) Tracing Policy. +Let's apply the [process.credentials.changes.at.syscalls](https://raw.githubusercontent.com/cilium/tetragon/main/examples/tracingpolicy/process-credentials/process.credentials.changes.at.syscalls.yaml) Tracing Policy. ```bash kubectl apply -f https://raw.githubusercontent.com/cilium/tetragon/main/examples/tracingpolicy/process-credentials/process.credentials.changes.at.syscalls.yaml - ``` -Then we start monitoring for events with `tetra` cli: +Then start monitoring events with the `tetra` CLI: ```bash kubectl exec -it -n kube-system ds/tetragon -c tetragon -- tetra getevents ``` -In another terminal, kubectl exec into the xwing pod: +In another terminal, `kubectl exec` into the xwing Pod: ```bash kubectl exec -it xwing -- /bin/bash ``` -and execute [su](https://en.wikipedia.org/wiki/Su_(Unix)) as this will call the related setuid() system calls: +And execute [su](https://en.wikipedia.org/wiki/Su_(Unix)) as this will call the +related `setuid` system calls: ```bash su root ``` -The `tetra` cli will generate the following [ProcessKprobe](https://tetragon.cilium.io/docs/reference/grpc-api/#processkprobe) events: +The `tetra` CLI will generate the following [ProcessKprobe](https://tetragon.cilium.io/docs/reference/grpc-api/#processkprobe) events: ```json { @@ -228,14 +241,18 @@ The `tetra` cli will generate the following [ProcessKprobe](https://tetragon.cil } ``` -In addition to the Kubernetes Identity and process metadata from exec events, [ProcessKprobe](https://tetragon.cilium.io/docs/reference/grpc-api/#processkprobe) events contain the arguments of the observed system call. In the above case they are: - -* `function_name`: that is the system call, `__x64_sys_setuid` or `__x64_sys_setgid` +In addition to the Kubernetes Identity and process metadata from exec events, +[ProcessKprobe](https://tetragon.cilium.io/docs/reference/grpc-api/#processkprobe) +events contain the arguments of the observed system call. In the above case +they are: -* `int_arg`: is the uid or gid to use, here it is 0 which corresponds to the root user. +- `function_name`: the system call, `__x64_sys_setuid` or + `__x64_sys_setgid` +- `int_arg`: the `uid` or `gid` to use, in our case it's 0 which corresponds to + the root user. -To disable the [process.credentials.changes.at.syscalls Tracing Policy](https://raw.githubusercontent.com/cilium/tetragon/main/examples/tracingpolicy/process-credentials/process.credentials.changes.at.syscalls.yaml) run: +To disable the [process.credentials.changes.at.syscalls](https://raw.githubusercontent.com/cilium/tetragon/main/examples/tracingpolicy/process-credentials/process.credentials.changes.at.syscalls.yaml) Tracing Policy run: ```bash kubectl delete -f https://raw.githubusercontent.com/cilium/tetragon/main/examples/tracingpolicy/process-credentials/process.credentials.changes.at.syscalls.yaml