edit existing tutorials #3605

Signed-off-by: AnaisUrlichs <[email protected]>

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)

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)

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,28 +52,34 @@ 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
 # A scrape configuration containing exactly one endpoint to scrape:
 # Here it's Tracee.
 scrape_configs:
   # The job name is added as a label `job=<job_name>` 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.
     static_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 🥳

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/).

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)

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 [email protected]: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).

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)

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: