base on Tool for building Kubernetes attack paths # KubeHound <p align="center"> <img src="./docs/logo.png" alt="KubeHound" width="300" /> </p> 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 + [Docker](https://docs.docker.com/engine/install/) `>= 19.03` + [Docker Compose](https://docs.docker.com/compose/compose-file/compose-versioning/) `V2` ### Install #### From Release Download binaries are available for Linux / Windows / Mac OS via the [releases](https://github.com/DataDog/KubeHound/releases) page or by running the following (Mac OS/Linux): ```bash wget https://github.com/DataDog/KubeHound/releases/latest/download/kubehound-$(uname -o | sed 's/GNU\///g')-$(uname -m) -O kubehound chmod +x kubehound ``` <details> <summary>MacOS Notes</summary> 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](https://support.apple.com/en-gb/guide/mac-help/mchleab3a043/mac) </details> #### With homebrew KubeHound is available in homebrew-core and you can simply run ```bash brew update && brew install kubehound ``` `kubehound` should now be in your path. #### From source If you wish to build KubeHound from source, you will need to checkout a tag before building ```bash git clone https://github.com/DataDog/KubeHound.git cd KubeHound git checkout $(git describe --tags --abbrev=0) make build ``` KubeHound binary will be output to `./bin/build/kubehound`. ### Run Select a target Kubernetes cluster, either: * Using [kubectx](https://github.com/ahmetb/kubectx) * Using specific kubeconfig file by exporting the env variable: `export KUBECONFIG=/your/path/to/.kube/config` Then, simply run the `kubehound` binary: ```bash # If you installed it from brew, it is in your path kubehound # If you installed it from release, it should be were you downloaded it ./kubehound # If you installed it from source, it should be in the <repo_path>/bin/build folder ./bin/build/kubehound ``` For more advanced use case and configuration, see * [advanced configuration](https://kubehound.io/user-guide/advanced-configuration/): all the settings available through the configuration file. * [common operations](https://kubehound.io/user-guide/common-operations/): the commands available from the KubeHound binary (`dump` / `ingest`). * [common errors](https://kubehound.io/user-guide/troubleshooting/): troubleshooting guide. > Note: KubeHound can be deployed as a serivce (KHaaS), [for more information](https://kubehound.io/khaas/getting-started/). ## Using KubeHound Data To query the KubeHound graph data requires using the [Gremlin](https://tinkerpop.apache.org/gremlin.html) 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](https://github.com/aws/graph-notebook),to quickly showcase the capabilities of KubeHound. To access the UI: + Visit [http://localhost:8888/notebooks/KubeHound.ipynb](http://localhost:8888/notebooks/KubeHound.ipynb) in your browser + Use the default password `admin` to login (note: this can be changed via the [Dockerfile](./deployments/kubehound/notebook/Dockerfile) or by setting the `NOTEBOOK_PASSWORD` environment variable in the [.env](./deployments/kubehound/.env.tpl) 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](https://kubehound.io/queries/gremlin/). A specific DSL has been developped to query the Graph for the most basic use cases ([KubeHound DSL](https://kubehound.io/queries/dsl/)). ## Sample Attack 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: ```bash make sample-graph ``` To view the generated graph see the [Using KubeHound Data](#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: ```python #!/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 + For an overview of the application architecture see the [design canvas](./docs/Architecture.excalidraw) + To see the attacks covered see the [edge definitions](./docs/reference/attacks) + To contribute a new attack to the project follow the [contribution guidelines](./CONTRIBUTING.md) ## Acknowledgements KubeHound was created by the Adversary Simulation Engineering (ASE) team at Datadog: + Jeremy Fox [@0xff6a](https://www.twitter.com/0xff6a) + Julien Terriac + Edouard Schweisguth [@edznux](https://www.twitter.com/edznux) With additional support from: + Christophe Tafani-Dereeper [@christophetd](https://twitter.com/christophetd) We would also like to acknowledge the [BloodHound](https://github.com/BloodHoundAD/BloodHound) team for pioneering the use of graph theory in offensive security and inspiring us to create this project. ", Assign "at most 3 tags" to the expected json: {"id":"3075","tags":[]} "only from the tags list I provide: [{"id":77,"name":"3d"},{"id":89,"name":"agent"},{"id":17,"name":"ai"},{"id":54,"name":"algorithm"},{"id":24,"name":"api"},{"id":44,"name":"authentication"},{"id":3,"name":"aws"},{"id":27,"name":"backend"},{"id":60,"name":"benchmark"},{"id":72,"name":"best-practices"},{"id":39,"name":"bitcoin"},{"id":37,"name":"blockchain"},{"id":1,"name":"blog"},{"id":45,"name":"bundler"},{"id":58,"name":"cache"},{"id":21,"name":"chat"},{"id":49,"name":"cicd"},{"id":4,"name":"cli"},{"id":64,"name":"cloud-native"},{"id":48,"name":"cms"},{"id":61,"name":"compiler"},{"id":68,"name":"containerization"},{"id":92,"name":"crm"},{"id":34,"name":"data"},{"id":47,"name":"database"},{"id":8,"name":"declarative-gui "},{"id":9,"name":"deploy-tool"},{"id":53,"name":"desktop-app"},{"id":6,"name":"dev-exp-lib"},{"id":59,"name":"dev-tool"},{"id":13,"name":"ecommerce"},{"id":26,"name":"editor"},{"id":66,"name":"emulator"},{"id":62,"name":"filesystem"},{"id":80,"name":"finance"},{"id":15,"name":"firmware"},{"id":73,"name":"for-fun"},{"id":2,"name":"framework"},{"id":11,"name":"frontend"},{"id":22,"name":"game"},{"id":81,"name":"game-engine "},{"id":23,"name":"graphql"},{"id":84,"name":"gui"},{"id":91,"name":"http"},{"id":5,"name":"http-client"},{"id":51,"name":"iac"},{"id":30,"name":"ide"},{"id":78,"name":"iot"},{"id":40,"name":"json"},{"id":83,"name":"julian"},{"id":38,"name":"k8s"},{"id":31,"name":"language"},{"id":10,"name":"learning-resource"},{"id":33,"name":"lib"},{"id":41,"name":"linter"},{"id":28,"name":"lms"},{"id":16,"name":"logging"},{"id":76,"name":"low-code"},{"id":90,"name":"message-queue"},{"id":42,"name":"mobile-app"},{"id":18,"name":"monitoring"},{"id":36,"name":"networking"},{"id":7,"name":"node-version"},{"id":55,"name":"nosql"},{"id":57,"name":"observability"},{"id":46,"name":"orm"},{"id":52,"name":"os"},{"id":14,"name":"parser"},{"id":74,"name":"react"},{"id":82,"name":"real-time"},{"id":56,"name":"robot"},{"id":65,"name":"runtime"},{"id":32,"name":"sdk"},{"id":71,"name":"search"},{"id":63,"name":"secrets"},{"id":25,"name":"security"},{"id":85,"name":"server"},{"id":86,"name":"serverless"},{"id":70,"name":"storage"},{"id":75,"name":"system-design"},{"id":79,"name":"terminal"},{"id":29,"name":"testing"},{"id":12,"name":"ui"},{"id":50,"name":"ux"},{"id":88,"name":"video"},{"id":20,"name":"web-app"},{"id":35,"name":"web-server"},{"id":43,"name":"webassembly"},{"id":69,"name":"workflow"},{"id":87,"name":"yaml"}]" returns me the "expected json"