# Tool for building Kubernetes attack paths


![KubeHound](https://github.com/DataDog/KubeHound/raw/main/docs/logo.png align="center")

A Kubernetes attack graph tool allowing automated calculation of attack paths between assets in a cluster.

## Quick Start

### Requirements

To run KubeHound, you need a couple dependencies

* [Docker](https://docs.docker.com/engine/install/) `>= 19.03`
    
* [Docker Compose](https://docs.docker.com/compose/compose-file/compose-versioning/) `V2`
    

### Install and run

Select a target Kubernetes cluster, either:

* Using [kubectx](https://github.com/ahmetb/kubectx)
    
* Using specific kubeconfig file by exporting the env variable: `export KUBECONFIG=/your/path/to/.kube/config`
    

Download binaries are available for Linux / Windows / Mac OS via the [releases](https://github.com/DataDog/KubeHound/releases) page or by running the following (Mac OS/Linux):

```basic
wget https://github.com/DataDog/KubeHound/releases/latest/download/kubehound-$(uname -o | sed 's/GNU\///g')-$(uname -m) -O kubehound
chmod +x kubehound
```

<details><summary>MacOS Notes</summary><p><code></code><a href="https://support.apple.com/en-gb/guide/mac-help/mchleab3a043/mac"></a></p></details>

Then, simply run

```basic
./kubehound
```

For more advanced use case and configuration, see

* [advanced configuration](https://kubehound.io/user-guide/advanced-configuration/): all the settings available through the configuration file.
    
* [common operations](https://kubehound.io/user-guide/common-operations/): the commands available from the KubeHound binary (`dump` / `ingest`).
    
* [common errors](https://kubehound.io/user-guide/troubleshooting/): troubleshooting guide.
    

> Note: KubeHound can be deployed as a serivce (KHaaS), [for more information](https://kubehound.io/user-guide/khaas-101/).

## Using KubeHound Data

To query the KubeHound graph data requires using the [Gremlin](https://tinkerpop.apache.org/gremlin.html) query language via an API call or dedicated graph query UI. A number of fully featured graph query UIs are available (both commercial and open source), but we provide an accompanying Jupyter notebook based on the [AWS Graph Notebook](https://github.com/aws/graph-notebook),to quickly showcase the capabilities of KubeHound. To access the UI:

* Visit [http://localhost:8888/notebooks/KubeHound.ipynb](http://localhost:8888/notebooks/KubeHound.ipynb) in your browser
    
* Use the default password `admin` to login (note: this can be changed via the [Dockerfile](https://github.com/DataDog/KubeHound/blob/main/deployments/kubehound/notebook/Dockerfile) or by setting the `NOTEBOOK_PASSWORD` environment variable in the [.env](https://github.com/DataDog/KubeHound/blob/main/deployments/kubehound/.env.tpl) file)
    
* Follow the initial setup instructions in the notebook to connect to the KubeHound graph and configure the rendering
    
* Start running the queries and exploring the graph!
    

### Example queries

We have documented a few sample queries to execute on the database in [our documentation](https://kubehound.io/queries/gremlin/). A specific DSL has been developped to query the Graph for the most basic use cases ([KubeHound DSL](https://kubehound.io/queries/dsl/)).

## Sample Attack Path

[![Example Path](https://github.com/DataDog/KubeHound/raw/main/docs/images/example-graph.png align="left")](https://github.com/DataDog/KubeHound/blob/main/docs/images/example-graph.png)

### Sample Data

To view a sample graph demonstrating attacks in a very, very vulnerable cluster you can generate data via running the app against the provided kind cluster:

```basic
make sample-graph
```

To view the generated graph see the [Using KubeHound Data](https://github.com/DataDog/KubeHound#using-kubehound-data) section.

## Query data from your scripts

If you expose the graph endpoint you can automate some queries to gather some KPI and metadata for instance.

### Python

You can query the database data in your python script by using the following snippet:

```basic
#!/usr/bin/env python
import sys
from gremlin_python.driver.client import Client

KH_QUERY = "kh.containers().count()"
c = Client("ws://127.0.0.1:8182/gremlin", "kh")
results = c.submit(KH_QUERY).all().result()
```

You'll need to install `gremlinpython` as a dependency via: `pip install gremlinpython`

## Further information

* For an overview of the application architecture see the [design canvas](https://github.com/DataDog/KubeHound/blob/main/docs/Architecture.excalidraw)
    
* To see the attacks covered see the [edge definitions](https://github.com/DataDog/KubeHound/blob/main/docs/reference/attacks)
    
* To contribute a new attack to the project follow the [contribution guidelines](https://github.com/DataDog/KubeHound/blob/main/CONTRIBUTING.md)
    

## Acknowledgements

KubeHound was created by the Adversary Simulation Engineering (ASE) team at Datadog:

* Jeremy Fox [@0xff6a](https://www.twitter.com/0xff6a)
    
* Julien Terriac
    
* Edouard Schweisguth [@edznux](https://www.twitter.com/edznux)
    

With additional support from:

* Christophe Tafani-Dereeper [@christophetd](https://twitter.com/christophetd)
    

We would also like to acknowledge the [BloodHound](https://github.com/BloodHoundAD/BloodHound) team for pioneering the use of graph theory in offensive security and inspiring us to create this project.