diff --git a/Vagrantfile b/Vagrantfile index 94f05137c677..947c87bef5a1 100644 --- a/Vagrantfile +++ b/Vagrantfile @@ -24,6 +24,10 @@ end vm_name = "tracee-#{arch}-vm" Vagrant.configure("2") do |config| + # need to make sure the Prometheus tutorials are working on Mac + config.vm.network "forwarded_port", guest: 9090, host: 9090 + config.vm.network "forwarded_port", guest: 3366, host: 3366 + config.vm.network "forwarded_port", guest: 3000, host: 3000 case arch when "amd64" # config.vm.box = "ubuntu/focal64" # Ubuntu 20.04 Focal Fossa (non CO-RE) diff --git a/docs/images/signatures.png b/docs/images/signatures.png new file mode 100644 index 000000000000..226a17d0f57c Binary files /dev/null and b/docs/images/signatures.png differ diff --git a/docs/tutorials/additional-resources.md b/docs/tutorials/additional-resources.md index a40bb2f119f6..ad2253b2fe4f 100644 --- a/docs/tutorials/additional-resources.md +++ b/docs/tutorials/additional-resources.md @@ -9,13 +9,14 @@ This page links to external resources, created by Aqua Security and the communit ## Useful Videos * [Tracee Livestream: Everything is an Event in Tracee](https://www.youtube.com/live/keqVe4d71uk?feature=share) +* [Tracee Video Series on the Aqua Open Source YouTube channel](https://www.youtube.com/watch?v=ddkTX9vAHqE&list=PLRdPssLrT8d2Jp71pkgDTjq2fm_8P7Nqk) Have a look at the recordings on the [Aqua Open Source YouTube channel.](https://www.youtube.com/channel/UCZd5NF4XJRaU-yfextsY-pw) ## Conference recording * [eBPF Warfare - Detecting Kernel & eBPF Rootkits with Tracee](https://youtu.be/0MjVan5lQd0) -* [Verifiable GitHub Actions with eBPF - Jose Donizetti, Aqua](https://www.youtube.com/watch?v=6vNt9JMU9p4) +* [Verifiable GitHub Actions with eBPF - Jose Donizetti, Aqua](https://www.youtube.com/watch?v=6vNt9JMU9p4) * [Tracee Features and Internals: High Throughput of eBPF Events for Execution Patterns Detections](https://youtu.be/xdEVGT5vAIM) * [BlackHat Arsenal 2022: Detecting Linux kernel rootkits with Aqua Tracee](https://youtu.be/EATX8g3sh-0) * [Tracee presentation at BlackHat USA 2021](https://youtu.be/LXP2tdBPNj8) \ No newline at end of file diff --git a/docs/tutorials/deploy-grafana-dashboard.md b/docs/tutorials/deploy-grafana-dashboard.md index f7e46f6260c5..e6fc2c3a7745 100644 --- a/docs/tutorials/deploy-grafana-dashboard.md +++ b/docs/tutorials/deploy-grafana-dashboard.md @@ -1,28 +1,38 @@ -# Deploy Grafana Dashboard +# Access Tracee Metrics in Prometheus and Grafana Grafana is a visualization tools for exported metrics and logs, most commonly -used alongside prometheus. +used alongside Prometheus. Since version 0.7.0, tracee exports useful runtime metrics to prometheus. +By using Grafana and the new metrics from tracee, we can deploy a simple +dashboard which tracks the tracee instance performance and outputs. + +There are three options for accessing Tracee metrics: +* Running the Tracee Docker Container Image -- Shown in this tutorial +* Running the Tracee Helm Chart -- Detailed as part of the [Promtail-Tracee](./promtail.md) tutorial + +![Dashboard Image](../images/tracee-grafana-dashboard.png) + +## Tracee Docker Container Image + These metrics exports are enabled by default in all docker images and can be -enabled using the `--metrics`. +enabled using the `--metrics` flag. [tracee]: https://github.com/aquasecurity/tracee/tree/{{ git.tag }}/cmd/tracee -By using grafana and the new metrics from tracee, we can deploy a simple -dashboard which tracks your tracee's instance performance and outputs. - -## Pre-requisites +### Prerequisites The following tools must be available for use, they can all be installed either -through docker or installed/built on your machine. +through docker or installed/built on your machine. Note that you need to be on a Linux machine to follow the Docker tutorial. +Alternative, on a MacBook it is possible to use Vagrant with Parallels as detailed in the following tutorial: +[Running Tracee on Mac with Parallels and Vagrant](./tracee-vagrant.md) - [Tracee](https://github.com/aquasecurity/tracee/) - [Prometheus](https://prometheus.io/download/) - [Grafana](https://grafana.com/docs/grafana/latest/getting-started/getting-started) -## Run Tracee with Metrics Enabled +### Run Tracee with Metrics Enabled -- The Docker Command Tracee can be most easily deployed with metrics enabled by default and port forwarded through the following commands: @@ -33,7 +43,7 @@ docker run \ --cgroupns=host --privileged \ -v /tmp/tracee:/tmp/tracee \ -v /etc/os-release:/etc/os-release-host:ro \ - -it -p 3366:3366 aquasec/tracee:{{ git.tag }} + -it -p 3366:3366 aquasec/tracee:latest ``` Of course, the forwarded metrics ports can be changed, but you should note that @@ -42,9 +52,9 @@ some of the later instructions depend on these ports. If running Tracee locally through built binaries, the metrics address may be overrides with the `--listen-addr` flag. -## Run Prometheus and Configure it to Scrape Tracee +### Run Prometheus and Configure it to Scrape Tracee -Install prometheus or pull it's docker image. Then create the following +Install Prometheus or pull it's Docker image. Then create the following configuration file, call it `prometheus.yml` to scrape Tracee: ```yaml @@ -52,10 +62,11 @@ configuration file, call it `prometheus.yml` to scrape Tracee: # Here it's Tracee. scrape_configs: # The job name is added as a label `job=` to any timeseries scraped from this config. - - job_name: 'prometheus' + - job_name: 'tracee' # Override the global default and scrape targets from this job every 5 seconds. scrape_interval: 5s + metrics_path: /metrics #Scrape tracee's default metrics hosts. #If forwarding different ports make sure to change these addresses. @@ -63,7 +74,12 @@ scrape_configs: - targets: ['localhost:3366'] ``` -We must then start prometheus with the following command: +Note that the localhost:3366 might have to be replaced with your IP address. The IP address can be found with the following command: +``` +/sbin/ifconfig +``` + +We can then start Prometheus with the following command: ```console prometheus --config.file=/path/to/prometheus.yml @@ -72,19 +88,29 @@ prometheus --config.file=/path/to/prometheus.yml Or alternatively with docker: ```console -docker run -p 9090:9090 -v /path/to/config:/etc/prometheus prom/prometheus +docker run \ + -p 9090:9090 \ + -v ./prometheus.yml:/etc/prometheus/prometheus.yml \ + prom/prometheus ``` -Then, try to access prometheus through `http://localhost:9090`. If successful, -move to the next step, otherwise consult with prometheus documentation. +Ensure that prometheus can scrape the Tracee target: Open the Prometheus UI at `http://localhost:9090` +Under Status < Targets will be the scrape targets listed. + +If successful, move to the next step, otherwise consult with the Prometheus documentation. ## Run Grafana to display Tracee's Prometheus Metrics After successfully deploying Tracee and Prometheus we may now run Grafana to visualize it's metrics. -Install grafana using their instructions and enter the now available grafana -website (by default it's usually through http://localhost:3000). +Install Grafana using the Grafana container image: + +```console +docker run -d -p 3000:3000 --name=grafana grafana/grafana-enterprise +``` + +Next, you should be able to access the Grafana UI throug: `http://localhost:3000`. After entering the website, logging in with username and password `admin` (and changing your password if you wish), you should see the homepage: @@ -96,9 +122,11 @@ selecting "Data Sources" and pressing "Add Data Source" at the top left. Create a Prometheus Data Source and point it's URL to the relevant location (usually http://localhost:9090) +Note that you might have to use your local IP address again instead of `localhost`. + You may now either create your own Dashboard or import our default dashboard. -## Import Tracee's Default Dashboard +### Import Tracee's Default Dashboard First download our Grafana Dashboard's json [here]. @@ -109,4 +137,4 @@ After adding the data source hover on the plus icon in the sidebar and select downloaded json from your file browser. Change the name and Dashboard UID if you wish and press "Import" to finish. -Finally you will be redirected to the dashboard 🥳 +Finally you will be redirected to the dashboard 🥳 \ No newline at end of file diff --git a/docs/tutorials/overview.md b/docs/tutorials/overview.md index bbf0af0950d5..f2896ef0242d 100644 --- a/docs/tutorials/overview.md +++ b/docs/tutorials/overview.md @@ -3,3 +3,5 @@ In this section you can find step-by-step guides that help you accomplish specific tasks. 👈 Please use the side-navigation on the left in order to browse the different topics. + +If there are any specific tutorials that you would like to see please let us know on the [Aqua Open Source Slack](https://slack.aquasec.com/). \ No newline at end of file diff --git a/docs/tutorials/promtail.md b/docs/tutorials/promtail.md index f4e416e8b4dd..1d1e65a47404 100644 --- a/docs/tutorials/promtail.md +++ b/docs/tutorials/promtail.md @@ -10,6 +10,8 @@ If you prefer the video tutorial, check out the tutorial below on the Aqua Open ## Prerequisites +### CLI tools + Please make sure to have - Kubectl installed and connected to a Kubernetes cluster (any cluster will work for this purpose) - The Helm CLI installed @@ -26,7 +28,64 @@ and helm version ``` -## Installation +### Obserability Tools + +Lastly, please ensure that the following observability tools are already installed inside the Kubernetes cluster: + +* Prometheus +* Loki and Promtail +* Grafana + +Alternatively, this tutorial showcases after the Tracee Installation section how to get an observability stack running with the above tools. + +## Installing the Tracee Helm Chart and accessing logs + +Right now, we cannot access any logs from our cluster since we do not have any application that actively produces logs. +Thus, we will install Tracee inside our cluster through the Tracee Helm Chart. + +Add the Tracee Helm Chart: + +```console +helm repo add aqua https://aquasecurity.github.io/helm-charts/ +``` + +Update the repository list on Helm: + +```console +helm repo update +``` + +Install the Tracee Helm Chart inside your Kubernetes cluster: + +```console +helm install tracee aqua/tracee \ + --namespace tracee-system --create-namespace \ + --set hostPID=true +``` + +Now, ensure that Tracee is running inside the `tracee-system` namespace: + +```console +kubectl get all -n tracee-system +``` + +Similar to Promtail, also for Tracee one pod should run on each node of the Kubernetes cluster. + +### Accessing Tracee Logs + +Generally, it is possible to access logs from the Tracee pods directly through kubectl: + +```console +kubectl logs -f daemonset/tracee -n tracee-system +``` + +Next, open the Grafana Dashboard, on the left, go to "Explore". There, you should be able to select Loki as a Datasource. + +Now, you can write log queries in LogQL to access the logs that are stored in the Tracee pods: + +![Screenshot from Grafana, accessing Tracee logs through Loki](../images/loki.png) + +## Installation of Observability Tools We need to install an observability stack to access the logs of the pods inside our cluster. This will consist of: - Grafana (for Dashboards and querying logs) @@ -185,50 +244,3 @@ The password name is dependent on how you called the Helm Chart installation of Now navigate on Grafana to: Explore Here select Loki as a data source. - -### Tracee - -Right now, we cannot access any logs from our cluster since we do not have any application that actively produces logs. -Thus, we will install Tracee inside our cluster through the Tracee Helm Chart. - -Add the Tracee Helm Chart: - -```console -helm repo add aqua https://aquasecurity.github.io/helm-charts/ -``` - -Update the repository list on Helm: - -```console -helm repo update -``` - -Install the Tracee Helm Chart inside your Kubernetes cluster: - -```console -helm install tracee aqua/tracee \ - --namespace tracee-system --create-namespace \ - --set hostPID=true -``` - -Now, ensure that Tracee is running inside the `tracee-system` namespace: - -```console -kubectl get all -n tracee-system -``` - -Similar to Promtail, also for Tracee one pod should run on each node of the Kubernetes cluster. - -## Accessing Tracee Logs - -Generally, it is possible to access logs from the Tracee pods directly through kubectl: - -```console -kubectl logs -f daemonset/tracee -n tracee-system -``` - -However, once you have all the above components installed, you can open the Grafana Dashboard, on the left, go to "Explore". There, you should be able to select Loki as a Datasource. - -Now, you can write log queries in LogQL to access the logs that are stored in the Tracee pods: - -![Screenshot from Grafana, accessing Tracee logs through Loki](../images/loki.png) diff --git a/docs/tutorials/tracee-vagrant.md b/docs/tutorials/tracee-vagrant.md new file mode 100644 index 000000000000..e00c7d61f461 --- /dev/null +++ b/docs/tutorials/tracee-vagrant.md @@ -0,0 +1,42 @@ +# Using the Tracee container image on MacOS with Parallels and Vagrant + +There are a few more steps involved in running Tracee through a container image on arm64 (M1). + +Prerequisites: + +* [Vagrant CLI](https://developer.hashicorp.com/vagrant/downloads) installed +* [Parallels Pro](https://www.parallels.com/uk/products/desktop/pro/) installed + +First, clone the Tracee Git repository and move into the root directory: + +```console +git clone git@github.com:aquasecurity/tracee.git + +cd tracee +``` + +Next, use Vagrant to start a Parallels VM: + +```console +vagrant up +``` + +This will use the [Vagrantfile](https://github.com/aquasecurity/tracee/blob/main/Vagrantfile) in the root of the Tracee directory. + +Lastly, ssh into the created VM: + +```console +vagrant ssh +``` + +Now, it is possible to run the Tracee Container image: + +```console +docker run \ + --name tracee --rm -it \ + --pid=host --cgroupns=host --privileged \ + -v /etc/os-release:/etc/os-release-host:ro \ + aquasec/tracee:latest +``` + +To learn how to install Tracee in a production environment, [check out the Kubernetes guide](./kubernetes-quickstart). diff --git a/docs/tutorials/verify-tracee-signature.md b/docs/tutorials/verify-tracee-signature.md index fe6d185acf56..d1af92707d36 100644 --- a/docs/tutorials/verify-tracee-signature.md +++ b/docs/tutorials/verify-tracee-signature.md @@ -3,7 +3,7 @@ ## Prerequisites -Before you begin, ensure that you have the following: +Before you begin, ensure that you have the following installed: - [cosign](https://docs.sigstore.dev/cosign/installation/) @@ -12,5 +12,10 @@ Before you begin, ensure that you have the following: Tracee images are signed with cosign keyless. To verify the signature we can run the command: ```console -cosign verify aquasec/tracee:{{ git.tag }} --certificate-oidc-issuer https://token.actions.githubusercontent.com --certificate-identity-regexp https://github.com/aquasecurity/tracee | jq +cosign verify aquasec/tracee:tag-name --certificate-oidc-issuer https://token.actions.githubusercontent.com --certificate-identity-regexp https://github.com/aquasecurity/tracee | jq ``` + +Note that all of the tag-names can be found on the [Tracee Docker Hub Registry](https://hub.docker.com/r/aquasec/tracee/tags). + +The output should look similar to the following: +![Tracee Signature Scanning](../images/signatures.png) diff --git a/mkdocs.yml b/mkdocs.yml index a2485b945cef..a32601f6e889 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -23,9 +23,10 @@ nav: - NixOS: getting-started/installing/distros/nix-nixos.md - Tutorials: - Overview: tutorials/overview.md + - Cosign - verify Tracee signature: tutorials/verify-tracee-signature.md + - Access Tracee Metrics in Grafana and Prometheus: tutorials/deploy-grafana-dashboard.md + - Using Tracee Container Image with Vagrant on Mac: tutorials/tracee-vagrant.md - Working with Tracee's Policies on Kubernetes: tutorials/k8s-policies.md - - Cosign - verify tracee signature: tutorials/verify-tracee-signature.md - - Deploy Tracee Grafana Dashboard: tutorials/deploy-grafana-dashboard.md - Accessing Tracee Logs through Promtail and Loki: tutorials/promtail.md - Additional Resources: tutorials/additional-resources.md - Docs: