KubeHound
A Kubernetes attack graph tool allowing automated calculation of attack paths between assets in a cluster
Quick Links
Requirements
Application
Test (Development only)
Quick Start
Run KubeHound
KubeHound ships with a sensible default configuration designed to get new users up and running quickly. First step is to prepare the application:
make kubehound
This 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/kubehound
To view the generated graph see the Using KubeHound Data section.
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.
Advanced Usage
Infrastructure Setup
First create and populate a .env file with the required variables:
cp deployments/kubehound/.env.tpl deployments/kubehound/.env
Edit the variables (datadog env DD_*
related and KUBEHOUND_ENV
):
Note:
KUBEHOUND_ENV=prod
will use prebuilt image from ghcr.io (🚨 currently NOT supported 🚨)
KUBEHOUND_ENV=dev
will build the images locally
Running Kubehound
To replicate the automated command and run KubeHound step-by-step. First build the application:
make build
Next spawn the backend infrastructure
make backend-up
Next create a configuration file:
collector:
type: live-k8s-api-collector
telemetry:
enabled: true
A 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 help
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 graph query UIs are availble, but we recommend gdotv. To access the KubeHound graph using gdotv
:
Development
Build
Build the application via:
make build
All binaries will be output to the bin folder
Unit Testing
The full suite of unit tests can be run locally via:
make test
System Testing
The 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 environement with kubectl and other commands, you'll need to set (assuming you are at the root dir):
cd test/setup/ && export KUBECONFIG=$(pwd)/.kube-config
Environment variable:
DD_API_KEY
(optional): set to the datadog API key used to submit metrics and other observability data.
Setup
Setup the test kind cluster (you only need to do this once!) via:
make local-cluster-deploy
Then run the system tests via:
make system-test
To cleanup the environment you can destroy the cluster via:
make local-cluster-destroy
To list all the available commands, run:
make help
Note: 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 command
KIND_CMD="kind"
for kind command
CI Testing
System tests will be run in CI via the system-test github action