diff --git a/Readme.md b/Readme.md index 36649661db56..a0eb789641e9 100644 --- a/Readme.md +++ b/Readme.md @@ -5,6 +5,7 @@ [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 +[macfaq]:https://aquasecurity.github.io/tracee/latest/docs/deep-dive/mac.md Before moving on, please consider giving us a GitHub star ⭐️. Thank you! ## About Tracee @@ -18,7 +19,7 @@ To learn more about Tracee, check out the [documentation](https://aquasecurity.g ## Quickstart 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. +Tracee should run on most common Linux distributions and kernels. For compatibility information see the [Prerequisites][prereqs] page. Mac users, please read [this FAQ](macfaq). ### Using Docker diff --git a/docs/docs/deep-dive/mac.md b/docs/docs/deep-dive/mac.md new file mode 100644 index 000000000000..1c8aff1f3b64 --- /dev/null +++ b/docs/docs/deep-dive/mac.md @@ -0,0 +1,19 @@ +# Tracee on Apple Mac FAQ + +## Does Tracee run on MacOS? + +No. Tracee runs only on Linux operating system. But you can run a Linux VM on your Mac, and then run Tracee in it. Please note though, that with this setup Tracee will only have visibility to the Linux VM it is running in, and not the host Mac machine. + +## Does Tracee run on Apple Silicon? + +Apple Silicon (a.k.a `M#` CPUs) utilizes the ARM64 CPU architecture. Given that [Tracee is compatible with ARM64](../install/prerequisites.md#processor-architecture), it should run on Apple Silicon as well. + +## Does Tracee run in a Linux container on MacOS? + +Yes. It is very common to install a container engine (e.g Docker Desktop) on MacOS and still be able to run Linux containers. This works by creating a Linux virtual machine inside your MacOS and running the container engine and all your containers from inside it. Note that with this setup Tracee will only have visibility to that Linux VM which is dedicated for the container engine, and not to your Mac machine. If you wanted to run something and see how Tracee reacts to it, you can run it as another container which should be visible to Tracee. + +## Linuxkit + +[linuxkit](https://github.com/linuxkit/linuxkit) is a popular Linux distribution used by Docker Desktop and other solutions. +Linux kit does not have the Kernel Symbols Table feature properly configured by default, which is a [prerequisite](../install/prerequisites.md#kernel-symbols) for running Tracee. +It is technically possible to enable kernel symbols in linuxkit but an easier solution would be to disable [those Tracee events that depend on kernel symbols](../install/prerequisites.md#kernel-symbols). diff --git a/docs/docs/install/docker.md b/docs/docs/install/docker.md index 1cd1daf328f9..50204d53eea2 100644 --- a/docs/docs/install/docker.md +++ b/docs/docs/install/docker.md @@ -1,19 +1,27 @@ -# Docker Quickstart +# Running Tracee with Docker -This section details how you can run Tracee through a container image. +This guide will help you get started with running Tracee as a container. ## Prerequisites -Please ensure that Docker or another container runtime is working on your machine. +- Review the [prerequisites for running Tracee](./prerequisites.md) +- If you are an Apple Mac user, please read [the Mac FAQ](../deep-dive/apple.md) +- Ensure that you have Docker or a compatible container runtime -## Run the Tracee container images +## Tracee container image -All of the Tracee container images are stored in a public registry on [Docker Hub.](https://hub.docker.com/r/aquasec/tracee) -You can easily start experimenting with Tracee using the Docker image. +Tracee container image is available in Docker Hub as [aquasec/tracee](https://hub.docker.com/r/aquasec/tracee). -### On x86 architecture, please run the following command +- You can use the `latest` tag or a named version version e.g `aquasec/tracee:{{ git.tag }}`. +- If you are trying the most cutting edge features, there is also a `dev` tag which is built nightly from source. +- The Tracee image is a [Multi-platform](https://docs.docker.com/build/building/multi-platform/) image that includes a x86 and arm64 flavors. You can also access the platform-specific images directly with the `aarch64` and `x86_64` tags for the latest version or `aarch64-` and `x86_64-` for a specific version. +- For most first time users, just use `aquasec/tracee`! -```console +## Running Tracee container + +Here is the docker run command, we will analyze it next: + +```shell docker run \ --name tracee --rm -it \ --pid=host --cgroupns=host --privileged \ @@ -21,45 +29,25 @@ docker run \ aquasec/tracee:latest ``` -### Steps to run the Tracee container image on arm64 - -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 +1. Docker general flags: + 1.1 `--name` - name our container so that we can interact with it easily. + 1.2. `--rm` - remove the container one it exits, assuming this is an interactive trial of Tracee. + 1.3. `-it` - allow the container to interact with your terminal. +2. Since Tracee runs in a container but is instrumenting the host, it will need access to some resources from the host: + 2.2 `--pid=host` - share the host's [process namespace]() with Tracee's container. + 2.3 `--cgroupns-host` - share the host's [cgroup namespace]() with Tracee's container. + 2.4 `--privileged` - run the Tracee container as root so it has all the [required capabilities](./prerequisites.md#process-capabilities). + 2.5 `-v /etc/os-release:/etc/os-release-host:ro` - share the host's [OS information file](./prerequisites.md#os-information) with the Tracee container. -First, clone the Tracee Git repository and move into the root directory: +After running this command, you should start seeing a stream of events that Tracee is emitting. -```console -git clone git@github.com:aquasecurity/tracee.git - -cd tracee -``` - -Next, use Vagrant to start a Parallels VM: - -```console -vagrant up -``` +For next steps, please read about Tracee [Policies](../policies/index.md) -This will use the [Vagrantfile](https://github.com/aquasecurity/tracee/blob/main/Vagrantfile) in the root of the Tracee directory. +## Installing Tracee -Lastly, ssh into the created VM: +If you are looking to permanently install Tracee, you would probably do the following: -```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 -``` +1. Remove interactive flags `-it` and replace with daemon flag `-d` +2. Consider how to collect events from the container. -To learn how to install Tracee in a production environment, [check out the Kubernetes guide](./kubernetes-quickstart). +Or you can follow the [Kubernetes guide](./kubernetes.md) which addresses these concerns. diff --git a/docs/index.md b/docs/index.md index 13367b5280af..03c76c1e992c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,6 +16,7 @@ hide: [docker-guide]:./docker.md [kubernetes-guide]:./kubernetes.md [prereqs]:./docs/install/prerequisites.md +[macfaq]:./docs/deep-dive/mac.md Before moving on, please consider giving us a GitHub star ⭐️. Thank you! @@ -31,7 +32,7 @@ To learn more about Tracee, check out the [documentation](https://aquasecurity.g ## Quickstart 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. +Tracee should run on most common Linux distributions and kernels. For compatibility information see the [Prerequisites][prereqs] page. Mac users, please read [this FAQ](macfaq). ### Using Docker