KubeHound

README

KubeHound

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 >= 19.03
• Docker Compose V2

Install and run

Select a target Kubernetes cluster, either:

• Using 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 page or by running the following (Mac OS/Linux):

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

MacOS Notes

If downloading the releases via a browser you must run e.g xattr -d com.apple.quarantine kubehound before running to prevent MacOS blocking execution

Then, simply run

./kubehound

For more advanced use case and configuration, see

• advanced configuration: all the settings available through the configuration file.
• common operations: the commands available from the KubeHound binary (dump / ingest).
• common errors: troubleshooting guide.

Note: KubeHound can be deployed as a serivce (KHaaS), for more information.

Using KubeHound Data

To query the KubeHound graph data requires using the Gremlin 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,to quickly showcase the capabilities of KubeHound. To access the UI:

• Visit http://localhost:8888/notebooks/KubeHound.ipynb in your browser
• Use the default password admin to login (note: this can be changed via the Dockerfile or by setting the NOTEBOOK_PASSWORD environment variable in the .env 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. A specific DSL has been developped to query the Graph for the most basic use cases (KubeHound DSL).

Sample Attack Path

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:

make sample-graph

To view the generated graph see the 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:

#!/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
• To see the attacks covered see the edge definitions
• To contribute a new attack to the project follow the contribution guidelines

Acknowledgements

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

• Jeremy Fox @0xff6a
• Julien Terriac
• Edouard Schweisguth @edznux

With additional support from:

• Christophe Tafani-Dereeper @christophetd

We would also like to acknowledge the BloodHound team for pioneering the use of graph theory in offensive security and inspiring us to create this project.