Skip to content

Commit

Permalink
Zenithar/doc various cleanup (#294)
Browse files Browse the repository at this point in the history 
* chore(doc): add a programmatically readable graphdb schema.

* chore(doc): fix various inconsistencies.

* chore(doc): split vertex/edge in the JSON schema.

---------

Co-authored-by: jt-dd <[email protected]>
  • Loading branch information
@Zenithar @jt-dd
Zenithar and jt-dd authored Dec 9, 2024
1 parent 30084a5 commit 560e11b
Show file tree
Hide file tree
Showing 30 changed files with 991 additions and 182 deletions.
42 changes: 23 additions & 19 deletions docs/queries/dsl.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,33 +17,37 @@ _DSL definition code available [here](https://github.com/DataDog/KubeHound/blob/

### Retrieve cluster data

| Method | Gremlin equivalent |
| --------------------------- | -------------------------------------------------------- |
| `.cluster([string...])` | `.has("class","Cluster")` |
| `.containers([string...])` | `.has("class","Container")` |
| `.endpoints([int])` | `.has("class","Endpoint")` |
| `.groups([string...])` | `.has("class","Group")` |
| `.hostMounts([string...])` | `.has("class","Volume").has("type", "HostPath")` |
| `.nodes([string...])` | `.has("class","Node")` |
| `.permissions([string...])` | `.has("class","PermissionSet")` |
| `.pods([string...])` | `.has("class","Pod")` |
| `.run([string...])` | `.has("runID", P.within(ids)` |
| `.sas([string...])` | `.has("class","Identity").has("type", "ServiceAccount")` |
| `.services([string...])` | `.has("class","Endpoint").has("exposure", EXTERNAL)` |
| `.users([string...])` | `.has("class","Identity").has("type", "User")` |
| `.volumes([string...])` | `.has("class","Volume")` |
> These methods are defined in the [`KubeHoundTraversalSourceDsl`](https://github.com/DataDog/KubeHound/blob/main/deployments/kubehound/graph/dsl/kubehound/src/main/java/com/datadog/ase/kubehound/KubeHoundTraversalSourceDsl.java) class.
| Method | Gremlin equivalent | Example usage |
| --------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------- |
| `.cluster([string...])` | `.has("class","Cluster")` | `kh.cluster("kind-kubehound.local")` |
| `.containers([string...])` | `.has("class","Container")` | `kh.cluster("kind-kubehound.local").containers("nginx")` |
| `.endpoints([int])` | `.has("class","Endpoint")` | `kh.cluster("kind-kubehound.local").endpoints(3)` |
| `.hostMounts([string...])` | `.has("class","Volume").has("type", "HostPath")` | `kh.cluster("kind-kubehound.local").hostMounts("/proc")` |
| `.nodes([string...])` | `.has("class","Node")` | `kh.cluster("kind-kubehound.local").nodes("control-plane")` |
| `.permissions([string...])` | `.has("class","PermissionSet")` | `kh.cluster("kind-kubehound.local").permissions("system::kube-controller")` |
| `.pods([string...])` | `.has("class","Pod")` | `kh.cluster("kind-kubehound.local").pods("app-pod")` |
| `.run([string...])` | `.has("runID", P.within(ids))` | `kh.run("01he5ebh73tah762qgdd5k4wqp")` |
| `.services([string...])` | `.has("class","Endpoint").has("exposure", "EXTERNAL")` | `kh.cluster("kind-kubehound.local").services("app-front-proxy")` |
| `.sas([string...])` | `.has("class","Identity").has("type", "ServiceAccount")` | `kh.cluster("kind-kubehound.local").sas("postgres-admin")` |
| `.users([string...])` | `.has("class","Identity").has("type", "User")` | `kh.cluster("kind-kubehound.local").users("[email protected]")` |
| `.groups([string...])` | `.has("class","Identity").has("type", "Group")` | `kh.cluster("kind-kubehound.local").groups("engineering")` |
| `.volumes([string...])` | `.has("class","Volume")` | `kh.cluster("kind-kubehound.local").volumes("db-data")` |

### Retrieving attack oriented data

> These methods are defined in the [`KubeHoundTraversalDsl`](https://github.com/DataDog/KubeHound/blob/main/deployments/kubehound/graph/dsl/kubehound/src/main/java/com/datadog/ase/kubehound/KubeHoundTraversalDsl.java) class.
| Method | Gremlin equivalent |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.attacks()` | `.outE().inV().path()` |
| `.critical()` | `.has("critical", true)` |
| `.criticalPaths(int)` | see [KubeHoundTraversalDsl.java](https://github.com/DataDog/KubeHound/blob/main/deployments/kubehound/kubegraph/dsl/kubehound/src/main/java/com/datadog/ase/kubehound/KubeHoundTraversalDsl.java) |
| `.criticalPathsFilter(int, string...)` | see [KubeHoundTraversalDsl.java](https://github.com/DataDog/KubeHound/blob/main/deployments/kubehound/kubegraph/dsl/kubehound/src/main/java/com/datadog/ase/kubehound/KubeHoundTraversalDsl.java) |
| `.criticalPathsFreq([maxHops])` | see [KubeHoundTraversalDsl.java](https://github.com/DataDog/KubeHound/blob/main/deployments/kubehound/kubegraph/dsl/kubehound/src/main/java/com/datadog/ase/kubehound/KubeHoundTraversalDsl.java) |
| `.criticalPaths(int)` | see [KubeHoundTraversalDsl.java](https://github.com/DataDog/KubeHound/blob/main/deployments/kubehound/graph/dsl/kubehound/src/main/java/com/datadog/ase/kubehound/KubeHoundTraversalDsl.java) |
| `.criticalPathsFilter(int, string...)` | see [KubeHoundTraversalDsl.java](https://github.com/DataDog/KubeHound/blob/main/deployments/kubehound/graph/dsl/kubehound/src/main/java/com/datadog/ase/kubehound/KubeHoundTraversalDsl.java) |
| `.criticalPathsFreq([maxHops])` | see [KubeHoundTraversalDsl.java](https://github.com/DataDog/KubeHound/blob/main/deployments/kubehound/graph/dsl/kubehound/src/main/java/com/datadog/ase/kubehound/KubeHoundTraversalDsl.java) |
| `.hasCriticalPath()` | `.where(__.criticalPaths().limit(1))` |
| `.minHopsToCritical([maxHops])` | see [KubeHoundTraversalDsl.java](https://github.com/DataDog/KubeHound/blob/main/deployments/kubehound/kubegraph/dsl/kubehound/src/main/java/com/datadog/ase/kubehound/KubeHoundTraversalDsl.java) |
| `.minHopsToCritical([maxHops])` | see [KubeHoundTraversalDsl.java](https://github.com/DataDog/KubeHound/blob/main/deployments/kubehound/graph/dsl/kubehound/src/main/java/com/datadog/ase/kubehound/KubeHoundTraversalDsl.java) |

For more detailed explanation, please see below.

Expand Down
6 changes: 3 additions & 3 deletions docs/reference/attacks/CE_MODULE_LOAD.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ mitreAttackTactic: TA0004 - Privilege escalation

# CE_MODULE_LOAD

| Source | Destination | MITRE |
| ----------------------------------------- | ------------------------------------- |----------------------------------|
| Source | Destination | MITRE |
| ------------------------------------- | --------------------------- | ------------------------------------------------------------------- |
| [Container](../entities/container.md) | [Node](../entities/node.md) | [Escape to Host, T1611](https://attack.mitre.org/techniques/T1611/) |

Load a kernel module from within an overprivileged container to breakout into the node.
Expand Down Expand Up @@ -72,4 +72,4 @@ Avoid running containers as the `root` user. Enforce running as an unprivileged

+ [Compendium Of Container Escapes](https://i.blackhat.com/USA-19/Thursday/us-19-Edwards-Compendium-Of-Container-Escapes-up.pdf)
+ [Linux Privilege Escalation - Exploiting Capabilities - StefLan's Security Blog](https://steflan-security.com/linux-privilege-escalation-exploiting-capabilities/)
+ [Module Load Breakout](https://raesene.github.io/blog/2023/08/06/fun-with-privileged-container-breakout/)
+ [Module Load Breakout](https://raesene.github.io/blog/2023/08/06/fun-with-privileged-container-breakout/)
5 changes: 2 additions & 3 deletions docs/reference/attacks/CE_NSENTER.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ mitreAttackTactic: TA0004 - Privilege escalation

# CE_NSENTER

| Source | Destination | MITRE |
| ----------------------------------------- | ------------------------------------- |----------------------------------|
| Source | Destination | MITRE |
| ------------------------------------- | --------------------------- | ------------------------------------------------------------------- |
| [Container](../entities/container.md) | [Node](../entities/node.md) | [Escape to Host, T1611](https://attack.mitre.org/techniques/T1611/) |

Container escape via the nsenter built-in linux program that allows executing a binary into another namespace.
Expand Down Expand Up @@ -86,4 +86,3 @@ Avoid running containers as the `root` user. Enforce running as an unprivileged
+ [nsenter(1) - Linux manual page](https://man7.org/linux/man-pages/man1/nsenter.1.html)
+ [Bad Pod #2: Privilege and HostPid](https://bishopfox.com/blog/kubernetes-pod-privilege-escalation#Pod2)
+ [Debugging containers using nsenter](https://jaanhio.me/blog/nsenter-debug/)

4 changes: 2 additions & 2 deletions docs/reference/attacks/CE_PRIV_MOUNT.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ mitreAttackTactic: TA0004 - Privilege escalation

# CE_PRIV_MOUNT

| Source | Destination | MITRE |
| ----------------------------------------- | ------------------------------------- |----------------------------------|
| Source | Destination | MITRE |
| ------------------------------------- | --------------------------- | ------------------------------------------------------------------- |
| [Container](../entities/container.md) | [Node](../entities/node.md) | [Escape to Host, T1611](https://attack.mitre.org/techniques/T1611/) |

Mount the host disk and gain access to the host via arbitrary filesystem write
Expand Down
5 changes: 2 additions & 3 deletions docs/reference/attacks/CE_SYS_PTRACE.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ mitreAttackTactic: TA0004 - Privilege escalation

# CE_SYS_PTRACE

| Source | Destination | MITRE |
| ----------------------------------------- | ------------------------------------- |----------------------------------|
| Source | Destination | MITRE |
| ------------------------------------- | --------------------------- | ------------------------------------------------------------------- |
| [Container](../entities/container.md) | [Node](../entities/node.md) | [Escape to Host, T1611](https://attack.mitre.org/techniques/T1611/) |

Given the requisite capabilities, abuse the legitimate OS debugging mechanisms to escape the container via attaching to a node process.
Expand Down Expand Up @@ -84,4 +84,3 @@ Avoid running containers as the `root` user. Enforce running as an unprivileged
## References:

+ [Container Escape: All You Need is Cap (Capabilities)](https://www.cybereason.com/blog/container-escape-all-you-need-is-cap-capabilities?hs_amp=true)

8 changes: 4 additions & 4 deletions docs/reference/attacks/CE_UMH_CORE_PATTERN.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ mitreAttackTactic: TA0004 - Privilege escalation

Container escape via the `core_pattern` `usermode_helper` in the case of an exposed `/proc` mount.

| Source | Destination | MITRE |
| ----------------------------------------- | ------------------------------------- |----------------------------------|
| Source | Destination | MITRE |
| ------------------------------------- | --------------------------- | ------------------------------------------------------------------- |
| [Container](../entities/container.md) | [Node](../entities/node.md) | [Escape to Host, T1611](https://attack.mitre.org/techniques/T1611/) |

## Details
Expand All @@ -37,7 +37,7 @@ proc /hostproc proc rw,nosuid,nodev,noexec,relatime 0 0

## Exploitation

First find the path of the container’s filesystem on the host. This can be done by retrieving the current mounts (see [VOLUME_DISCOVER](./VOLUME_DISCOVER.md#checks)). Looks for the `upperdir` value of the overlayfs entry associated with containerd:
First find the path of the container's filesystem on the host. This can be done by retrieving the current mounts (see [VOLUME_DISCOVER](./VOLUME_DISCOVER.md#checks)). Looks for the `upperdir` value of the overlayfs entry associated with containerd:

```bash
$ cat /etc/mtab # or `cat /proc/mounts` depending on the system
Expand Down Expand Up @@ -73,7 +73,7 @@ apt update && apt install gcc
gcc -o crash /tmp/crash.c
```

Next write a shell script to be triggered inside the container’s file system as `shell.sh`:
Next write a shell script to be triggered inside the container's file system as `shell.sh`:

```bash
# Reverse shell
Expand Down
8 changes: 4 additions & 4 deletions docs/reference/attacks/CE_VAR_LOG_SYMLINK.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,15 @@ mitreAttackTactic: TA0006 - Credential Access

# CE_VAR_LOG_SYMLINK

| Source | Destination | MITRE |
| ----------------------------------------- | ------------------------------------- |----------------------------------|
| Source | Destination | MITRE |
| ------------------------------------- | --------------------------- | ------------------------------------------------------------------- |
| [Container](../entities/container.md) | [Node](../entities/node.md) | [Escape to Host, T1611](https://attack.mitre.org/techniques/T1611/) |

Arbitrary file reads on the host from a node via an exposed `/var/log` mount.

## Details

A pod running as root and with a mount point to the node’s `/var/log` directory can expose the entire contents of its host filesystem to any user who has access to its logs, enabling an attacker to read arbitrary files on the host node. See [Kubernetes Pod Escape Using Log Mounts](https://blog.aquasec.com/kubernetes-security-pod-escape-log-mounts) for a more detailed explanation of the technique.
A pod running as root and with a mount point to the node's `/var/log` directory can expose the entire contents of its host filesystem to any user who has access to its logs, enabling an attacker to read arbitrary files on the host node. See [Kubernetes Pod Escape Using Log Mounts](https://blog.aquasec.com/kubernetes-security-pod-escape-log-mounts) for a more detailed explanation of the technique.

## Prerequisites

Expand Down Expand Up @@ -65,7 +65,7 @@ Setup the symlink:
ln -s / /host/var/log/root_link
```

Call the kubelet API to read the “logs” and extract pod service account tokens:
Call the kubelet API to read the "logs" and extract pod service account tokens:

```bash
$ KUBE_TOKEN=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)
Expand Down
8 changes: 4 additions & 4 deletions docs/reference/attacks/CONTAINER_ATTACH.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,9 @@ mitreAttackTactic: TA0008 - Lateral Movement

# CONTAINER_ATTACH

| Source | Destination | MITRE |
| ----------------------------------------- | ------------------------------------- |----------------------------------|
| [Pod](../entities/pod.md) | [Container](../entities/container.md) | [Lateral Movement, TA0008](https://attack.mitre.org/tactics/TA0008/) |
| Source | Destination | MITRE |
| ------------------------- | ------------------------------------- | -------------------------------------------------------------------- |
| [Pod](../entities/pod.md) | [Container](../entities/container.md) | [Lateral Movement, TA0008](https://attack.mitre.org/tactics/TA0008/) |

Attach to a container running within a pod given access to the pod.

Expand Down Expand Up @@ -69,4 +69,4 @@ kubectl describe pod <pod name>

## References:

+ [Official Kubernetes Documentation](https://kubernetes.io/docs/tasks/debug/debug-application/debug-running-pod/)
+ [Official Kubernetes Documentation](https://kubernetes.io/docs/tasks/debug/debug-application/debug-running-pod/)
5 changes: 2 additions & 3 deletions docs/reference/attacks/ENDPOINT_EXPLOIT.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ mitreAttackTactic: TA0008 - Lateral Movement

Represents a network endpoint exposed by a container that could be exploited by an attacker (via means known or unknown). This can correspond to a Kubernetes service, node service, node port, or container port.

| Source | Destination | MITRE |
| ----------------------------------------- | ------------------------------------- |----------------------------------|
| Source | Destination | MITRE |
| ----------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------ |
| [Endpoint](../entities/endpoint.md) | [Container](../entities/container.md) | [Exploitation of Remote Services, T1210](https://attack.mitre.org/techniques/T1210/) |

## Details
Expand Down Expand Up @@ -51,4 +51,3 @@ None
## References:

+ [Official Kubernetes documentation: EndpointSlices ](https://kubernetes.io/docs/concepts/storage/volumes/)

6 changes: 3 additions & 3 deletions docs/reference/attacks/EXPLOIT_CONTAINERD_SOCK.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,9 @@ mitreAttackTactic: TA0008 - Lateral Movement

# EXPLOIT_CONTAINERD_SOCK

| Source | Destination | MITRE |
| ----------------------------------------- | ------------------------------------- |----------------------------------|
| [Container](../entities/container.md) | [Container](../entities/container.md) | [Lateral Movement, TA0008](https://attack.mitre.org/tactics/TA0008/) |
| Source | Destination | MITRE |
| ------------------------------------- | ------------------------------------- | -------------------------------------------------------------------- |
| [Container](../entities/container.md) | [Container](../entities/container.md) | [Lateral Movement, TA0008](https://attack.mitre.org/tactics/TA0008/) |

Container escape via the `containerd.sock` file that allows executing a binary into another container.

Expand Down
Loading

0 comments on commit 560e11b

Please sign in to comment.