Getting started
Prerequisites
To get started with KubeHound, you'll need the following pre-requirements on your system:
- Docker >= 19.03 (
docker version
) - Docker Compose >= v2.0 (
docker compose version
)
Running KubeHound
KubeHound ships with a sensible default configuration as well as a pre-built binary, designed to get new users up and running quickly.
First, download KubeHound:
wget https://github.com/DataDog/KubeHound/releases/latest/download/KubeHound_$(uname -o | sed 's/GNU\///g')_$(uname -m).tar.gz -O kubehound.tar.gz
mkdir kubehound
tar -xf kubehound.tar.gz -C kubehound --strip-components=1
cd kubehound
Then, prepare the application by running:
This will start backend services via docker compose (wiping any existing data), and compile the kubehound binary from source.
Next, make sure your current kubectl context points at the target cluster:
# View the current context
kubectl config current-context
# Set your context
kubectl config set-context <name>
# alternatively, use https://github.com/ahmetb/kubectx
Finally, run KubeHound with the default configuration:
Sample output:
INFO[0000] Starting KubeHound (run_id: aff49337-5e36-46ea-ac1f-ed224bf215ba) component=kubehound run_id=aff49337-5e36-46ea-ac1f-ed224bf215ba service=kubehound
INFO[0000] Initializing launch options component=kubehound run_id=aff49337-5e36-46ea-ac1f-ed224bf215ba service=kubehound
INFO[0000] Loading application configuration from default embedded component=kubehound run_id=aff49337-5e36-46ea-ac1f-ed224bf215ba service=kubehound
INFO[0000] Initializing application telemetry component=kubehound run_id=aff49337-5e36-46ea-ac1f-ed224bf215ba service=kubehound
INFO[0000] Loading cache provider component=kubehound run_id=aff49337-5e36-46ea-ac1f-ed224bf215ba service=kubehound
INFO[0000] Loaded MemCacheProvider cache provider component=kubehound run_id=aff49337-5e36-46ea-ac1f-ed224bf215ba service=kubehound
INFO[0000] Loading store database provider component=kubehound run_id=aff49337-5e36-46ea-ac1f-ed224bf215ba service=kubehound
INFO[0000] Loaded MongoProvider store provider component=kubehound run_id=aff49337-5e36-46ea-ac1f-ed224bf215ba service=kubehound
INFO[0000] Loading graph database provider component=kubehound run_id=aff49337-5e36-46ea-ac1f-ed224bf215ba service=kubehound
INFO[0000] Loaded JanusGraphProvider graph provider component=kubehound run_id=aff49337-5e36-46ea-ac1f-ed224bf215ba service=kubehound
INFO[0001] Starting Kubernetes raw data ingest component=kubehound run_id=aff49337-5e36-46ea-ac1f-ed224bf215ba service=kubehound
INFO[0001] Loading Kubernetes data collector client component=kubehound run_id=aff49337-5e36-46ea-ac1f-ed224bf215ba service=kubehound
INFO[0001] Loaded k8s-api-collector collector client component=kubehound run_id=aff49337-5e36-46ea-ac1f-ed224bf215ba service=kubehound
...
INFO[0028] Building edge ExploitHostWrite component=kubehound run_id=aff49337-5e36-46ea-ac1f-ed224bf215ba service=kubehound
INFO[0028] Edge writer 22 ContainerAttach::CONTAINER_ATTACH written component=kubehound run_id=aff49337-5e36-46ea-ac1f-ed224bf215ba service=kubehound
INFO[0028] Building edge IdentityAssumeNode component=kubehound run_id=aff49337-5e36-46ea-ac1f-ed224bf215ba service=kubehound
INFO[0029] Edge writer 8 ExploitHostWrite::EXPLOIT_HOST_WRITE written component=kubehound run_id=aff49337-5e36-46ea-ac1f-ed224bf215ba service=kubehound
...
INFO[0039] Completed edge construction component=kubehound run_id=aff49337-5e36-46ea-ac1f-ed224bf215ba service=kubehound
INFO[0039] Completed graph construction component=kubehound run_id=aff49337-5e36-46ea-ac1f-ed224bf215ba service=kubehound
INFO[0039] Attack graph generation complete in 39.108174109s component=kubehound run_id=aff49337-5e36-46ea-ac1f-ed224bf215ba service=kubehound
Access the KubeHound data
At this point, the KubeHound data has been ingested in KubeHound's graph database. You can use any client that supports accessing JanusGraph - we recommend using gdotv:
- Download and install gdotv from the official website
- Create a connection to the local KubeHound JanusGraph instance
- Click on the
New database connection
button - Enter
localhost
as an hostname, and click on theTest connection
button - Once the connection is successful, click
Submit
- you're good to go!
- Click on the
Visualize and query the KubeHound data
Once the data is loaded in the graph database, it's time to visualize and query it!
You can explore it interactively in your graph client. Then, refer to KubeHound's query library to start asking questions to your data.
Generating sample data
If you don't have a cluster at your disposal: clone the KubeHound repository, install kind and run the following command:
This will spin up a temporary local kind cluster, run KubeHound on it, and destroy the cluster.