Updating/cleaning docs (#242)

* updating docs * updating make file * Update docs/user-guide/advanced-configuration.md Co-authored-by: Edouard Schweisguth <[email protected]> * Update docs/user-guide/advanced-configuration.md Co-authored-by: Edouard Schweisguth <[email protected]> * Update docs/user-guide/advanced-configuration.md Co-authored-by: Edouard Schweisguth <[email protected]> * PR comment --------- Co-authored-by: Edouard Schweisguth <[email protected]>
DataDog · Aug 7, 2024 · 3c102cd · 3c102cd
1 parent 4f6bc39
commit 3c102cd
Show file tree

Hide file tree

Showing 13 changed files with 326 additions and 329 deletions.
diff --git a/ADVANCED.md b/ADVANCED.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -40,5 +40,4 @@ To add a new attack to KubeHound, please do the following:
 + Create the [resources](../test/setup/test-cluster/attacks/) file in the test cluster that will introduce an instance of the attack into the test cluster 
 + Add an [edge system test](../test/system/graph_edge_test.go) that verifies the attack is correctly created by KubeHound
 
-  See [here](https://github.com/DataDog/KubeHound/pull/68/files) for a previous example PR.
-
+See [here](https://github.com/DataDog/KubeHound/pull/68/files) for a previous example PR.
diff --git a/DEVELOPER.md b/DEVELOPER.md
diff --git a/Makefile b/Makefile
@@ -79,7 +79,7 @@ cache-clear: ## Clear the builder cache
 
 .PHONY: kubehound
 kubehound: | build ## Prepare kubehound (build go binary, deploy backend)
-	./bin/kubehound
+	./bin/build/kubehound
 
 .PHONY: test
 test: ## Run the full suite of unit tests 
@@ -133,7 +133,3 @@ thirdparty-licenses: ## Generate the list of 3rd party dependencies and write to
 local-wiki: ## Generate and serve the mkdocs wiki on localhost
 	poetry install || pip install mkdocs-material mkdocs-awesome-pages-plugin markdown-captions
 	poetry run mkdocs serve || mkdocs serve
-
-.PHONY: local-release
-local-release: ## Generate release packages locally via goreleaser
-	goreleaser release --snapshot --clean --config .goreleaser.yaml
diff --git a/README.md b/README.md
@@ -7,13 +7,21 @@ A Kubernetes attack graph tool allowing automated calculation of attack paths be
 
 ## 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 and 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`
 
 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/download/latest/kubehound-$(uname -o | sed 's/GNU\///g')-$(uname -m) -O kubehound
+wget https://github.com/DataDog/KubeHound/releases/latest/download/kubehound-$(uname -o | sed 's/GNU\///g')-$(uname -m) -O kubehound
 chmod +x kubehound
 ```
 
@@ -29,34 +37,32 @@ Then, simply run
 ```bash
 ./kubehound
 ```
-<details>
-<summary>To build KubeHound from source instead</summary>
 
-Clone and build this repository:
-```bash
-git clone https://github.com/DataDog/KubeHound.git
-cd KubeHound
-make kubehound
-```
+For more advanced use case and configuration, see 
 
-The built binary is now available at:
-```bash
-bin/build/kubehound
-```
-</details>
+* [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.
 
-For more advanced use case and configuration, see [ADVANCED.md](./ADVANCED.md)
-To view the generated graph see the [Using KubeHound Data](#using-kubehound-data) section.
+> Note: 
+  KubeHound can be deployed as a serivce (KHaaS), [for more information](https://kubehound.io/user-guide/khaas-101/).
 
-## Sample Attack Path
+## Using KubeHound Data
 
-![Example Path](./docs/images/example-graph.png)
+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!
 
-## Requirements
+### Example queries
 
-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`
+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
+
+![Example Path](./docs/images/example-graph.png)
 
 ### Sample Data
 
@@ -68,22 +74,11 @@ make sample-graph
 
 To view the generated graph see the [Using KubeHound Data](#using-kubehound-data) section. 
 
-## 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/).
+## Query data from your scripts
 
-### 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
+### Python
 
 You can query the database data in your python script by using the following snippet:
 

diff --git a/docs/dev-guide/datadog.md b/docs/dev-guide/datadog.md
@@ -0,0 +1,21 @@
+# Datadog setup
+
+The Datadog agent can be setup locally to provide some metrics and logs when developing on KubeHound.
+
+## Metrics and logs
+
+To have some in-depth metrics and log correlation, all the components are now linked to datadog.  To configure it you just need to add your Datadog API key (`DD_API_KEY`) in the environment variable in the `deployments/kubehound/.env`. When the API key is configured, a docker will be created `kubehound-dev-datadog`. 
+
+All the information being gathered are available at:
+
+* Metrics: https://app.datadoghq.com/metric/summary?filter=kubehound.janusgraph
+* Logs: https://app.datadoghq.com/logs?query=service%3Akubehound%20&cols=host%2Cservice&index=%2A&messageDisplay=inline&stream_sort=desc&viz=stream&from_ts=1688140043795&to_ts=1688140943795&live=true
+
+To collect the metrics for Janusgraph an exporter from Prometheus is being used:
+
+* https://github.com/prometheus/jmx_exporter
+
+They are exposed here:
+
+* Locally: http://127.0.0.1:8099/metrics
+* Datadog: https://app.datadoghq.com/metric/summary?filter=kubehound.janusgraph