- 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
- Golang
>= 1.20: https://go.dev/doc/install - Docker
>= 19.03: https://docs.docker.com/engine/install/ - Docker Compose
V2: https://docs.docker.com/compose/compose-file/compose-versioning/
- Kind: https://kind.sigs.k8s.io/docs/user/quick-start/#installing-with-a-package-manager
- Kubectl: https://kubernetes.io/docs/tasks/tools/
Release binaries are available for Linux / Windows / Mac OS via the releases page. These provide access to core KubeHound functionality but lack support for the make commands detailed in subsequent sections. Once the release archive is downloaded and extracted start the backend via:
./kubehound.sh backend-upNOTE:
- If downloading the releases via a browser you must run e.g
xattr -d com.apple.quarantine KubeHound_Darwin_arm64.tar.gzbefore running to prevent MacOS blocking execution
Next choose a target Kubernetes cluster, either:
- Select the targeted cluster via
kubectx(need to be installed separately) - Use a specific kubeconfig file by exporting the env variable:
export KUBECONFIG=/your/path/to/.kube/config
Finally run the compiled binary with packaged configuration (config.yaml):
./kubehound.sh runClone this repository via git:
git clone https://github.com/DataDog/KubeHound.gitKubeHound ships with a sensible default configuration designed to get new users up and running quickly. The first step is to prepare the application:
cd KubeHound
make kubehoundThis will do the following:
- Start the backend services via docker compose (wiping any existing data)
- Compile the kubehound binary from source
Next choose a target Kubernetes cluster, either:
- Select the targeted cluster via
kubectx(need to be installed separately) - Use a specific kubeconfig file by exporting the env variable:
export KUBECONFIG=/your/path/to/.kube/config
Finally run the compiled binary with default configuration:
bin/kubehoundTo view the generated graph see the Using KubeHound Data section.
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-graphTo view the generated graph see the Using KubeHound Data section.
First create and populate a .env file with the required variables:
cp deployments/kubehound/.env.tpl deployments/kubehound/.envEdit the variables (datadog env DD_* related and KUBEHOUND_ENV):
KUBEHOUND_ENV:devorreleaseDD_API_KEY: api key you created from https://app.datadoghq.com/ website
Note:
KUBEHOUND_ENV=devwill build the images locallyKUBEHOUND_ENV=releasewill use prebuilt images from ghcr.io
To replicate the automated command and run KubeHound step-by-step. First build the application:
make buildNext spawn the backend infrastructure
make backend-upNext create a configuration file:
collector:
type: live-k8s-api-collector
telemetry:
enabled: trueA tailored sample configuration file can be found here, a full configuration reference containing all possible parameters here.
Finally run the KubeHound binary, passing in the desired configuration:
bin/kubehound -c <config path>Remember the targeted cluster must be set via kubectx or setting the KUBECONFIG environment variable. Additional functionality for managing the application can be found via:
make helpTo 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
adminto login (note: this can be changed via the Dockerfile or by setting theNOTEBOOK_PASSWORDenvironment 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!
We have documented a few sample queries to execute on the database in our documentation.
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
Build the application via:
make buildAll binaries will be output to the bin folder
Build the release packages locally using goreleaser:
make local-releaseThe full suite of unit tests can be run locally via:
make testThe repository includes a suite of system tests that will do the following:
- create a local kubernetes cluster
- collect kubernetes API data from the cluster
- run KubeHound using the file collector to create a working graph database
- query the graph database to ensure all expected vertices and edges have been created correctly
The cluster setup and running instances can be found under test/setup
If you need to manually access the system test environment with kubectl and other commands, you'll need to set (assuming you are at the root dir):
cd test/setup/ && export KUBECONFIG=$(pwd)/.kube-configDD_API_KEY(optional): set to the datadog API key used to submit metrics and other observability data.
Setup the test kind cluster (you only need to do this once!) via:
make local-cluster-deployThen run the system tests via:
make system-testTo cleanup the environment you can destroy the cluster via:
make local-cluster-destroyTo list all the available commands, run:
make helpNote: if you are running on Linux but you dont want to run sudo for kind and docker command, you can overwrite this behavior by editing the following var in test/setup/.config:
DOCKER_CMD="docker"for docker commandKIND_CMD="kind"for kind command
System tests will be run in CI via the system-test github action
KubeHound was created by the Adversary Simulation Engineering (ASE) team at Datadog:
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.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent