Skip to content

Commit

Permalink
docs: process credential use case reorganization
Browse files Browse the repository at this point in the history 
Signed-off-by: Mahe Tardy <[email protected]>
  • Loading branch information
@mtardy @kkourt
mtardy authored and kkourt committed Jul 11, 2023
1 parent d4b50bc commit 82fb976
Show file tree
Hide file tree
Showing 2 changed files with 72 additions and 55 deletions.
66 changes: 33 additions & 33 deletions docs/content/en/docs/use-cases/linux-process-credentials/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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" >}}).
61 changes: 39 additions & 22 deletions docs/content/en/docs/use-cases/linux-process-credentials/syscalls.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
{
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 82fb976

Please sign in to comment.