Skip to content

Latest commit

 

History

History
115 lines (74 loc) · 4.89 KB

README.md

File metadata and controls

115 lines (74 loc) · 4.89 KB
Raw

KubeHound

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

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

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

Example 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

Acknowledgements

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

With additional support from:

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.