KubeHound

README

KubeHound

A Kubernetes attack graph tool allowing automated calculation of attack paths between assets in a cluster

Quick Links

• 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

Requirements

Application

• 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/

Test (Development only)

• Kind: https://kind.sigs.k8s.io/docs/user/quick-start/#installing-with-a-package-manager
• Kubectl: https://kubernetes.io/docs/tasks/tools/

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):

• KUBEHOUND_ENV: dev or prod
• DD_API_KEY: api key you created from https://app.datadoghq.com/ website

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:

• Download and install the application from https://gdotv.com/
• Create a connection to the local janusgraph instance by following the steps here https://docs.gdotv.com/connection-management/ and using hostname=localhost
• Navigate to the query editor and enter a sample query e.g g.V().count(). See detailed instructions here: https://docs.gdotv.com/query-editor/#run-your-query
• See the provided cheatsheet for examples of useful queries for various use cases.

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