From dfa1a5060e89f41c834161c4725d70377569c5bb Mon Sep 17 00:00:00 2001 From: Itay Shakury Date: Fri, 27 Oct 2023 18:36:50 +0300 Subject: [PATCH] docs: redo readme and getting started (#3616) --- Readme.md | 68 ++++++++++--------- .../install}/distros/fedora.md | 0 .../install}/distros/nix-nixos.md | 0 .../install}/distros/ubuntu.md | 0 .../install/docker.md} | 0 .../getting.md => docs/install/index.md} | 0 .../install/kubernetes.md} | 0 .../install}/override-os-files.md | 0 .../install}/prerequisites.md | 0 docs/getting-started/installing/docker.md | 9 --- docs/getting-started/installing/kubernetes.md | 62 ----------------- docs/index.md | 68 ++++++++++--------- mkdocs.yml | 25 +++---- 13 files changed, 82 insertions(+), 150 deletions(-) rename docs/{getting-started/installing => docs/install}/distros/fedora.md (100%) rename docs/{getting-started/installing => docs/install}/distros/nix-nixos.md (100%) rename docs/{getting-started/installing => docs/install}/distros/ubuntu.md (100%) rename docs/{getting-started/docker-quickstart.md => docs/install/docker.md} (100%) rename docs/{getting-started/installing/getting.md => docs/install/index.md} (100%) rename docs/{getting-started/kubernetes-quickstart.md => docs/install/kubernetes.md} (100%) rename docs/{getting-started/installing => docs/install}/override-os-files.md (100%) rename docs/{getting-started/installing => docs/install}/prerequisites.md (100%) delete mode 100644 docs/getting-started/installing/docker.md delete mode 100644 docs/getting-started/installing/kubernetes.md diff --git a/Readme.md b/Readme.md index 7645b9041d51..36649661db56 100644 --- a/Readme.md +++ b/Readme.md @@ -1,55 +1,59 @@ ![Tracee Logo](docs/images/tracee.png) -[![GitHub release (latest by date)](https://img.shields.io/github/v/release/aquasecurity/tracee)](https://github.com/aquasecurity/tracee/releases) -[![License](https://img.shields.io/github/license/aquasecurity/tracee)](https://github.com/aquasecurity/tracee/blob/main/LICENSE) -[![docker](https://badgen.net/docker/pulls/aquasec/tracee)](https://hub.docker.com/r/aquasec/tracee) + +[installation]:https://aquasecurity.github.io/tracee/latest/docs/install +[docker-guide]:https://aquasecurity.github.io/tracee/latest/docker.md +[kubernetes-guide]:https://aquasecurity.github.io/tracee/latest/kubernetes.md +[prereqs]:https://aquasecurity.github.io/tracee/latest/docs/install/prerequisites.md +Before moving on, please consider giving us a GitHub star ⭐️. Thank you! -# Tracee: Runtime Security and Forensics using eBPF +## About Tracee -Tracee uses eBPF technology to tap into your system and give you access to hundreds of events that help you understand how your system behaves. -In addition to basic observability events about system activity, Tracee adds a collection of sophisticated security events that expose more advanced behavioral patterns. -Tracee provides a rich filtering mechanism that allows you to eliminate noise and focus on specific workloads that matter most to you. +Tracee is a runtime security and observability tool that helps you understand how your system and applications behave. +It is using [eBPF technology](https://ebpf.io/what-is-ebpf/) to tap into your system and expose that information as events that you can consume. +Events range from factual system activity events to sophisticated security events that detect suspicious behavioral patterns. -**Key Features:** -* Kubernetes native installation -* Hundreds of default events -* Ships with a basic set of behavioral signatures for malware detection out of the box -* Easy configuration through Tracee Policies -* Kubernetes native user experience that is targetted at cluster administrators +To learn more about Tracee, check out the [documentation](https://aquasecurity.github.io/tracee/). -> We release new features and changes on a regular basis. Learn more about the latest release in our [discussions.](https://github.com/aquasecurity/tracee/discussions) +## Quickstart -To learn more about Tracee, check out the [documentation](https://aquasecurity.github.io/tracee/latest/docs/overview/). +To quickly try Tracee use one of the following snippets. For a more complete installation guide, check out the [Installation section][installation]. +Tracee should run on most common Linux distributions and kernels. For compatibility information see the [Prerequisites][prereqs] page. MacOS users, please read it too. -## Quickstart +### Using Docker + +```shell +docker run --name tracee \ + --pid=host --cgroupns=host --privileged \ + -v /etc/os-release:/etc/os-release-host:ro \ + aquasec/tracee:latest +``` -Installation options: -* [Install Tracee in your Kubernetes cluster.](https://aquasecurity.github.io/tracee/latest/getting-started/kubernetes-quickstart) -* [Experiment using the Tracee container image.](https://aquasecurity.github.io/tracee/latest/getting-started/docker-quickstart) +For a complete walkthrough please see the [Docker getting started guide][docker-guide]. -Steps to get started: +### On Kubernetes -1. [Install Tracee in your Kubernetes cluster through Helm](https://aquasecurity.github.io/tracee/latest/getting-started/kubernetes-quickstart/) -2. Query logs to see detected events +```shell +helm repo add aqua https://aquasecurity.github.io/helm-charts/ +helm repo update +helm install tracee aqua/tracee --namespace tracee --create-namespace +``` -Next, try one of our tutorials: +```shell +kubectl logs --follow --namespace tracee daemonset/tracee +``` -3. Filter events through [Tracee Policies](https://aquasecurity.github.io/tracee/latest/tutorials/k8s-policies/) -4. [Manage logs through Grafana Loki](https://aquasecurity.github.io/tracee/latest/tutorials/promtail/) or your preferred monitoring solution +For a complete walkthrough please see the [Kubernetes getting started guide][kubernetes-guide]. -![Example log output in Tracee pod](./docs/images/log-example.png) -Example log output in Tracee pod ## Contributing Join the community, and talk to us about any matter in the [GitHub Discussions](https://github.com/aquasecurity/tracee/discussions) or [Slack](https://slack.aquasec.com). -If you run into any trouble using Tracee or you would like to give us your feedback, please [create an issue.](https://github.com/aquasecurity/tracee/issues) +If you run into any trouble using Tracee or you would like to give use user feedback, please [create an issue.](https://github.com/aquasecurity/tracee/issues) -Find more information on [contributing to the source code](https://aquasecurity.github.io/tracee/latest/contributing/overview/) in the documentation. - -Please consider giving us a star ⭐️ -by clicking the button at the top of the [GitHub page](https://github.com/aquasecurity/tracee/) +Find more information on [contribution documentation](./contributing/overview/). ## More about Aqua Security Tracee is an [Aqua Security](https://aquasec.com) open source project. Learn about our open source work and portfolio [here](https://www.aquasec.com/products/open-source-projects/). + diff --git a/docs/getting-started/installing/distros/fedora.md b/docs/docs/install/distros/fedora.md similarity index 100% rename from docs/getting-started/installing/distros/fedora.md rename to docs/docs/install/distros/fedora.md diff --git a/docs/getting-started/installing/distros/nix-nixos.md b/docs/docs/install/distros/nix-nixos.md similarity index 100% rename from docs/getting-started/installing/distros/nix-nixos.md rename to docs/docs/install/distros/nix-nixos.md diff --git a/docs/getting-started/installing/distros/ubuntu.md b/docs/docs/install/distros/ubuntu.md similarity index 100% rename from docs/getting-started/installing/distros/ubuntu.md rename to docs/docs/install/distros/ubuntu.md diff --git a/docs/getting-started/docker-quickstart.md b/docs/docs/install/docker.md similarity index 100% rename from docs/getting-started/docker-quickstart.md rename to docs/docs/install/docker.md diff --git a/docs/getting-started/installing/getting.md b/docs/docs/install/index.md similarity index 100% rename from docs/getting-started/installing/getting.md rename to docs/docs/install/index.md diff --git a/docs/getting-started/kubernetes-quickstart.md b/docs/docs/install/kubernetes.md similarity index 100% rename from docs/getting-started/kubernetes-quickstart.md rename to docs/docs/install/kubernetes.md diff --git a/docs/getting-started/installing/override-os-files.md b/docs/docs/install/override-os-files.md similarity index 100% rename from docs/getting-started/installing/override-os-files.md rename to docs/docs/install/override-os-files.md diff --git a/docs/getting-started/installing/prerequisites.md b/docs/docs/install/prerequisites.md similarity index 100% rename from docs/getting-started/installing/prerequisites.md rename to docs/docs/install/prerequisites.md diff --git a/docs/getting-started/installing/docker.md b/docs/getting-started/installing/docker.md deleted file mode 100644 index 92009c2d08e7..000000000000 --- a/docs/getting-started/installing/docker.md +++ /dev/null @@ -1,9 +0,0 @@ -# Docker - -Tracee, as a runtime detection tool, is built and distributed as a -[docker container](https://hub.docker.com/r/aquasec/tracee). Tracee, -as an introspection tool, can either be used as a docker image, -[binary artifacts](https://github.com/aquasecurity/tracee/releases) or -[OS packages](../../contributing/building/packaging.md). - -Check [Getting Started](../../index.md#quickstart) for how to run tracee. diff --git a/docs/getting-started/installing/kubernetes.md b/docs/getting-started/installing/kubernetes.md deleted file mode 100644 index e7b92f8b65b0..000000000000 --- a/docs/getting-started/installing/kubernetes.md +++ /dev/null @@ -1,62 +0,0 @@ -# Install **Tracee** on Kubernetes - -In the [deploy/](https://github.com/aquasecurity/tracee/tree/{{ git.tag}}/deploy) directory you will find Yaml files to deploy Tracee -in a Kubernetes environment either with **Helm** or with a static yaml. - -!!! Tip - The **preferred** way to deploy **Tracee** is through its [Helm] chart! - -[Helm]: https://helm.sh - -1. Install **Tracee** using **Helm** - - 1. Add Aqua chart repository: - - ```console - helm repo add aqua https://aquasecurity.github.io/helm-charts/ - helm repo update - ``` - - or clone the Helm chart: - - ```console - git clone --depth 1 --branch {{ git.tag }} https://github.com/aquasecurity/tracee.git - cd tracee - ``` - - - 2. Install the chart from the Aqua chart repository: - - ```console - helm install tracee aqua/tracee \ - --namespace tracee-system --create-namespace - ``` - - or install the Helm chart from a local directory: - - ```console - helm install tracee ./deploy/helm/tracee \ - --namespace tracee-system --create-namespace - ``` - -2. Install **Tracee** **Manually** - - To install Tracee - - ```console - kubectl create namespace tracee-system - kubectl create -n tracee-system \ - -f https://raw.githubusercontent.com/aquasecurity/tracee/main/deploy/kubernetes/tracee/tracee.yaml - ``` - -[HERE]: https://github.com/aquasecurity/postee/blob/main/cfg.yaml - -## Platform Support - -This approach assumes that host nodes have either BTF available or kernel -headers available under conventional location. See Tracee's -[prerequisites](../installing/prerequisites.md) for more info. For the major -Kubernetes platforms this should work out-of-the-box, including GKE, EKS, AKS, -minikube. - -[deploy/kubernetes]:https://github.com/aquasecurity/tracee/blob/{{ git.tag }}/deploy/kubernetes diff --git a/docs/index.md b/docs/index.md index 8aa4343f1bd1..13367b5280af 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,11 +4,6 @@ hide: --- ![Tracee Logo >](images/tracee.png) -Before moving on, please consider giving us a star ⭐️ -by clicking the button at the top of the [GitHub page](https://github.com/aquasecurity/tracee/) - -# Navigating the Documentation - 👋 Welcome to Tracee Documentation! To help you get around, please notice the different sections at the top global menu: - You are currently in the [Getting Started](./) section where you can find general information and help with first steps. @@ -16,52 +11,59 @@ by clicking the button at the top of the [GitHub page](https://github.com/aquase - In the [Docs](./docs/overview) section you can find the complete reference documentation for all of the different features and settings that Tracee has to offer. - In the [Contributing](./contributing/overview) section you can find technical developer documentation and contribution guidelines. -## Tracee: Runtime Security and Forensics using eBPF - -Tracee uses eBPF technology to tap into your system and give you access to hundreds of events that help you understand how your system behaves. -In addition to basic observability events about system activity, Tracee adds a collection of sophisticated security events that expose more advanced behavioral patterns. -Tracee provides a rich filtering mechanism that allows you to eliminate noise and focus on specific workloads that matter most to you. + +[installation]:./docs/install/ +[docker-guide]:./docker.md +[kubernetes-guide]:./kubernetes.md +[prereqs]:./docs/install/prerequisites.md + -**Key Features:** +Before moving on, please consider giving us a GitHub star ⭐️. Thank you! -* Kubernetes native installation -* Hundreds of default events -* Ships with a basic set of behavioral signatures for malware detection out of the box -* Easy configuration through Tracee Policies -* Kubernetes native user experience that is targetted at cluster administrators +## About Tracee -> We release new features and changes on a regular basis. Learn more about the letest release in our [discussions.](https://github.com/aquasecurity/tracee/discussions) +Tracee is a runtime security and observability tool that helps you understand how your system and applications behave. +It is using [eBPF technology](https://ebpf.io/what-is-ebpf/) to tap into your system and expose that information as events that you can consume. +Events range from factual system activity events to sophisticated security events that detect suspicious behavioral patterns. -To learn more about Tracee, check out the [documentation](https://aquasecurity.github.io/tracee/latest/docs/overview/). +To learn more about Tracee, check out the [documentation](https://aquasecurity.github.io/tracee/). ## Quickstart -Installation options: +To quickly try Tracee use one of the following snippets. For a more complete installation guide, check out the [Installation section][installation]. +Tracee should run on most common Linux distributions and kernels. For compatibility information see the [Prerequisites][prereqs] page. MacOS users, please read it too. -- [Install Tracee in your Kubernetes cluster.](./getting-started/kubernetes-quickstart) -- [Experiment using the Tracee container image.](./getting-started/docker-quickstart) +### Using Docker -Steps to get started: +```shell +docker run --name tracee \ + --pid=host --cgroupns=host --privileged \ + -v /etc/os-release:/etc/os-release-host:ro \ + aquasec/tracee:latest +``` -1. [Install Tracee in your Kubernetes cluster through Helm](./getting-started/kubernetes-quickstart/) -2. Query logs to see detected events +For a complete walkthrough please see the [Docker getting started guide][docker-guide]. -Next, try one of our tutorials: +### On Kubernetes -3. Filter events through [Tracee Policies](./tutorials/k8s-policies/) -4. [Manage logs through Grafana Loki](./tutorials/promtail/) or your preferred monitoring solution +```shell +helm repo add aqua https://aquasecurity.github.io/helm-charts/ +helm repo update +helm install tracee aqua/tracee --namespace tracee --create-namespace +``` + +```shell +kubectl logs --follow --namespace tracee daemonset/tracee +``` + +For a complete walkthrough please see the [Kubernetes getting started guide][kubernetes-guide]. -![Example log output in Tracee pod](./images/log-example.png) -Example log output in Tracee pod ## Contributing Join the community, and talk to us about any matter in the [GitHub Discussions](https://github.com/aquasecurity/tracee/discussions) or [Slack](https://slack.aquasec.com). If you run into any trouble using Tracee or you would like to give use user feedback, please [create an issue.](https://github.com/aquasecurity/tracee/issues) -Find more information on [contributing to the source code](./contributing/overview/) in the documentation. - -Please consider giving us a star ⭐️ -by clicking the button at the top of the [GitHub page](https://github.com/aquasecurity/tracee/) +Find more information on [contribution documentation](./contributing/overview/). ## More about Aqua Security diff --git a/mkdocs.yml b/mkdocs.yml index a2485b945cef..f3ad593e337e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,20 +7,7 @@ repo_url: https://github.com/aquasecurity/tracee edit_uri: "" nav: - - Getting Started: - - Overview: index.md - - Kubernetes - Quick Start: getting-started/kubernetes-quickstart.md - - Docker - Quick Start: getting-started/docker-quickstart.md - - Installation: - - Getting Tracee: getting-started/installing/getting.md - - Prerequisites: getting-started/installing/prerequisites.md - - Docker: getting-started/installing/docker.md - - Kubernetes: getting-started/installing/kubernetes.md - - Override OS files: getting-started/installing/override-os-files.md - - Packages: - - Ubuntu: getting-started/installing/distros/ubuntu.md - - Fedora: getting-started/installing/distros/fedora.md - - NixOS: getting-started/installing/distros/nix-nixos.md + - Home: index.md - Tutorials: - Overview: tutorials/overview.md - Working with Tracee's Policies on Kubernetes: tutorials/k8s-policies.md @@ -30,6 +17,16 @@ nav: - Additional Resources: tutorials/additional-resources.md - Docs: - Overview: docs/overview.md + - Installation: + - Overview: docs/install/overview.md + - Prerequisites: docs/install/prerequisites.md + - Docker: docs/install/docker.md + - Kubernetes: docs/install/kubernetes.md + - Override OS files: docs/install/override-os-files.md + - Packages: + - Ubuntu: docs/install/distros/ubuntu.md + - Fedora: docs/install/distros/fedora.md + - NixOS: docs/install/distros/nix-nixos.md - Events: - Overview: docs/events/overview.md - Built-in Events: