diff --git a/Makefile b/Makefile index 8ca4813a7321..ecab6b4f7942 100644 --- a/Makefile +++ b/Makefile @@ -320,6 +320,7 @@ help: @echo " $$ STATIC=1 make ... # build static binaries" @echo " $$ BTFHUB=1 STATIC=1 make ... # build static binaries, embed BTF" @echo " $$ DEBUG=1 make ... # build binaries with debug symbols" + @echo " $$ METRICS=1 make ... # build enabling BPF metrics" @echo "" # diff --git a/docs/contributing/building/building.md b/docs/contributing/building/building.md index cc542fce7da2..8807e58a89fc 100644 --- a/docs/contributing/building/building.md +++ b/docs/contributing/building/building.md @@ -12,43 +12,33 @@ 2. Building **dependencies** - 1. **clang** && **llvm** (12, 13 or 14) - 1. **golang** (1.22.3 toolchain) - 1. **libelf** and **libelf-dev** + 1. `clang` && `llvm` (14) + 2. `golang` (1.22.3 toolchain) + 3. `libelf` and `libelf-dev` (or elfutils-libelf and elfutils-libelf-devel) - 1. **zlib1g** and **zlib1g-dev** + 4. `zlib1g` and `zlib1g-dev` (or zlib and zlib-devel) - 1. **libzstd-dev** for static build (libelf linkage) - 1. **clang-format-12** (specific version) for `fix-fmt` + 5. `libzstd-dev` for static build (libelf linkage) + 6. `clang-format-12` (specific version) for `fix-fmt` > You might take a look at the following files to understand how to have a > building environment: > > 1. [.github/actions/build-dependencies/action.yaml](https://github.com/aquasecurity/tracee/blob/main/.github/actions/build-dependencies/action.yaml) - > 1. [packaging/Dockerfile.ubuntu-packaging](https://github.com/aquasecurity/tracee/blob/main/packaging/Dockerfile.ubuntu-packaging) - > 1. [packaging/Dockerfile.fedora-packaging](https://github.com/aquasecurity/tracee/blob/main/packaging/Dockerfile.fedora-packaging) + > 1. [builder/Dockerfile.ubuntu-tracee-make](https://github.com/aquasecurity/tracee/blob/main/builder/Dockerfile.ubuntu-tracee-make) + > 1. [builder/Dockerfile.alpine-tracee-make](https://github.com/aquasecurity/tracee/blob/main/builder/Dockerfile.alpine-tracee-make) > > Those are very good examples for you to replicate a working environment. 3. **Clone** [tracee repository](https://github.com/aquasecurity/tracee/) - ```console - git clone git@github.com:aquasecurity/tracee - ``` - - ```text - Cloning into 'tracee'... - remote: Enumerating objects: 13251, done. - remote: Counting objects: 100% (555/555), done. - remote: Compressing objects: 100% (240/240), done. - remote: Total 13251 (delta 343), reused 369 (delta 280), pack-reused 12696 - Receiving objects: 100% (13251/13251), 11.75 MiB | 8.62 MiB/s, done. - Resolving deltas: 100% (8105/8105), done. + ```bash + git clone [https://github.com/aquasecurity/tracee/](https://github.com/aquasecurity/tracee/) ``` 4. All makefiles have a **help** target to give you needed instructions - ```console + ```bash make help ``` @@ -68,6 +58,7 @@ $ make e2e-net-signatures # build ./dist/e2e-net-signatures $ make e2e-inst-signatures # build ./dist/e2e-inst-signatures $ make tracee # build ./dist/tracee + $ make tracee-operator # build ./dist/tracee-operator # clean @@ -78,6 +69,7 @@ $ make clean-tracee-bench # wipe ./dist/tracee-bench $ make clean-signatures # wipe ./dist/signatures $ make clean-tracee # wipe ./dist/tracee + $ make clean-tracee-operator # wipe ./dist/tracee-operator # test @@ -90,65 +82,28 @@ $ STATIC=1 make ... # build static binaries $ BTFHUB=1 STATIC=1 make ... # build static binaries, embed BTF $ DEBUG=1 make ... # build binaries with debug symbols + $ METRICS=1 make ... # build enabling BPF metrics + ``` 5. Build **all** targets at once - ```console + ```bash make all ``` - ```text - Submodule 'libbpf' (https://github.com/libbpf/libbpf.git) registered for path '3rdparty/libbpf' - Cloning into '/home/rafaeldtinoco/tracee/3rdparty/libbpf'... - mkdir -p dist/signatures - GOOS=linux CC=clang GOARCH=amd64 CGO_CFLAGS= CGO_LDFLAGS= go build \ - --buildmode=plugin \ - -o dist/signatures/builtin.so \ - signatures/golang/export.go signatures/golang/kubernetes_api_connection.go signatures/golang/stdio_over_socket.go - ``` - 6. Build a **static binary** by setting `STATIC=1` - ```console + ```bash STATIC=1 make all ``` - ```text - CC="clang" \ - CFLAGS=""-fPIC"" \ - LD_FLAGS="" \ - make \ - -C ./3rdparty/libbpf/src \ - BUILD_STATIC_ONLY=1 \ - DESTDIR=/home/rafaeldtinoco/tracee/dist/libbpf \ - OBJDIR=/home/rafaeldtinoco/tracee/dist/libbpf/obj \ - INCLUDEDIR= LIBDIR= UAPIDIR= prefix= libdir= \ - install install_uapi_headers - ... - ``` - 7. Build a **static binary** with [BTFHUB Support](https://github.com/aquasecurity/btfhub) - ```console + ```bash BTFHUB=1 STATIC=1 make all ``` - ```text - Cloning into '/home/rafaeldtinoco/tracee/3rdparty/btfhub'... - remote: Enumerating objects: 205, done. - remote: Counting objects: 100% (16/16), done. - remote: Compressing objects: 100% (12/12), done. - remote: Total 205 (delta 4), reused 10 (delta 3), pack-reused 189 - Receiving objects: 100% (205/205), 10.59 MiB | 7.56 MiB/s, done. - Resolving deltas: 100% (73/73), done. - Cloning into '/home/rafaeldtinoco/tracee/3rdparty/btfhub-archive'... - remote: Enumerating objects: 1993, done. - remote: Counting objects: 100% (28/28), done. - remote: Compressing objects: 100% (23/23), done. - Receiving objects: 15% (301/1993), 154.97 MiB | 15.72 MiB/s - ``` - !!! Note BTFHUB support will embed several very small files (BTF files) into your final binary. Those files will allow **tracee** binary to be executed @@ -163,19 +118,16 @@ >plugin.Open("/tracee/dist/signatures/builtin.so"): Dynamic loading not supported >``` -8. Build a **debugable binary** with DWARF generation by setting `DEBUG=1` +8. Build a **debuggable binary** with DWARF debug symbols by setting `DEBUG=1` - ```console + ```bash DEBUG=1 make ``` - - ```text - GOOS=linux CC=clang GOARCH=amd64 CGO_CFLAGS="-I/home/gg/code/tracee/dist/libbpf" CGO_LDFLAGS="-lelf -lz /home/gg/code/tracee/dist/libbpf/libbpf.a" go build \ - -tags core,ebpf \ - -ldflags=" \ - -extldflags \"\" \ - -X main.version=\"v0.8.0-107-g121efeb\" \ - " \ - -v -o dist/tracee \ - ./cmd/tracee + +9. Build enabling BPF metrics by setting `METRICS=1` + + BPF metrics are only available if the BPF object is built with `METRICS` debug flag defined. + + ```bash + METRICS=1 make ``` diff --git a/docs/contributing/building/environment.md b/docs/contributing/building/environment.md index 0926103b6389..ab13b6630834 100644 --- a/docs/contributing/building/environment.md +++ b/docs/contributing/building/environment.md @@ -14,72 +14,43 @@ If you want to build tracee on your local machine [read this](./building.md). +## Quick steps -## Quick steps (**impatient readers**) +1. Build tracee environment: -!!! Example - - * Build and execute **tracee**: - - ```console - make -f builder/Makefile.tracee-make alpine-prepare - make -f builder/Makefile.tracee-make alpine-shell - ``` - - and inside the container: - - ```console - make clean - make tracee - sudo ./dist/tracee \ - -o option:parse-arguments \ - --scope comm=bash \ - --scope follow - ``` - - Now, in your host's bash shell, execute a command. You will see all events - (except scheduler ones) being printed, in "table format", to stdout. - - * Build and execute **tracee**: - - ```console - make -f builder/Makefile.tracee-make alpine-prepare - make -f builder/Makefile.tracee-make alpine-shell - ``` + ```bash + make -f builder/Makefile.tracee-make alpine-prepare + make -f builder/Makefile.tracee-make alpine-shell + ``` - and inside the container: +2. Build and execute tracee: - ```console - make clean - make all - sudo ./dist/tracee \ - -o format:json \ - -o option:parse-arguments \ - --scope comm=bash \ - --scope follow - ``` - - Now, in your host's bash shell, execute: `sudo strace /bin/ls` and observe - tracee warning you about a possible risk (with its Anti-Debugging signature). + ```bash + make clean + make tracee + sudo ./dist/tracee \ + -o option:parse-arguments \ + --scope comm=bash \ + --scope follow + ``` -Now, for **more patient readers** ... +Now, in your host's shell, execute a command. You will see all events +(except scheduler ones) being printed, in "table format", to stdout. ## How to build and use the environment In order to have a controlled building environment for tracee, tracee provides -a `Makefile.tracee-make` file that allows you to create and use a docker -container environment to build & test **tracee**. +a `Makefile.tracee-make` file that allows you to create and use a docker container environment to build & test **tracee**. -Two different environments are maintained for building tracee: +There are Two different environments that are maintained for building tracee: -* Alpine -* Ubuntu +* **Alpine** +* **Ubuntu** -The reason for that is that **Alpine Linux** is based in the -[musl](https://en.wikipedia.org/wiki/Musl) C standard library, while the -**Ubuntu Linux** uses [glibc](https://en.wikipedia.org/wiki/Glibc). By -supporting both building environments we can always be sure that the project -builds (and executes) correctly in both environments. +The reason for that is that `Alpine Linux` is based in the [musl](https://en.wikipedia.org/wiki/Musl) C standard library, +while the `Ubuntu Linux` uses [glibc](https://en.wikipedia.org/wiki/Glibc). + +By supporting both building environments we can always be sure that the project builds (and executes) correctly in both environments. !!! Attention Locally created containers, called `alpine-tracee-make` or @@ -91,13 +62,13 @@ builds (and executes) correctly in both environments. * To create an **alpine-tracee-make** container: - ```console + ```bash make -f builder/Makefile.tracee-make alpine-prepare ``` * To create an **ubuntu-tracee-make** container: - ```console + ```bash make -f builder/Makefile.tracee-make ubuntu-prepare ``` @@ -105,67 +76,80 @@ builds (and executes) correctly in both environments. * To execute an **alpine-tracee-make** shell: - ```console + ```bash make -f builder/Makefile.tracee-make alpine-shell ``` * To execute an **ubuntu-tracee-make** shell: - ```console + ```bash make -f builder/Makefile.tracee-make ubuntu-shell ``` ### Using build environment as a **make** replacement -Instead of executing a builder shell, you may use `alpine-tracee-make`, or -`ubuntu-tracee-make`, as a replacement for the `make` command: +Instead of executing a builder shell, you may use `alpine-make`, or +`ubuntu-make`, as a replacement for the `make` command: -```console -make -f builder/Makefile.tracee-make ubuntu-prepare -make -f builder/Makefile.tracee-make ubuntu-make ARG="help" -make -f builder/Makefile.tracee-make ubuntu-make ARG="clean" -make -f builder/Makefile.tracee-make ubuntu-make ARG="bpf" -make -f builder/Makefile.tracee-make ubuntu-make ARG="tracee" -make -f builder/Makefile.tracee-make ubuntu-make ARG="all" -``` +1. Create builder environment as described: + [Creating a builder environment](#creating-a-builder-environment) +2. Compile tracee using `ubuntu-make` -And, after the compilation, run the commands directly in your host: + * Build tracee binary: -```console -sudo ./dist/tracee \ - -o option:parse-arguments \ - --scope comm=bash \ - --scope follow -``` + ```bash + make -f builder/Makefile.tracee-make ubuntu-make ARG="tracee" + ``` -> **Note**: the generated binary must be compatible to your host (depending on -> glibc version, for example). + * Show available `ubuntu-make` commands: -If you don't want to depend on host's libraries versions, or if you are using -the `alpine-tracee-make` container as a replacement for `make`, and your host -is not an **Alpine Linux**, then you may set `STATIC=1` variable so you can run -compiled binaries in your host: + ```bash + make -f builder/Makefile.tracee-make ubuntu-make ARG="help" + ``` -```console -make -f builder/Makefile.tracee-make alpine-prepare -make -f builder/Makefile.tracee-make alpine-make ARG="help" -STATIC=1 make -f builder/Makefile.tracee-make alpine-make ARG="all" -``` + * Remove tracee binary -and execute the static binary from your host: + ```bash + make -f builder/Makefile.tracee-make ubuntu-make ARG="clean" + ``` -```console -ldd dist/tracee -``` + * Build binaries for all -```text -not a dynamic executable -``` + ```bash + make -f builder/Makefile.tracee-make ubuntu-make ARG="all" + ``` -!!! Attention - compiling **tracee-rules** with STATIC=1 won't allow you to use golang based - signatures: - > ```text - > 2021/12/13 13:27:21 error opening plugin /tracee/dist/signatures/builtin.so: - > plugin.Open("/tracee/dist/signatures/builtin.so"): Dynamic loading not supported - > ``` +3. Run tracee binary + + ```bash + sudo ./dist/tracee + ``` + +> **Note**: the generated binary must be compatible to your host (depending on glibc version). + +If you don't want to depend on host's libraries versions, or you are using the `alpine-make` container as a replacement for `make`, then it's necessary to set `STATIC` variable to `1` so you can run compiled binaries in your host machine: + +1. Compile tracee + + ```bash + make -f builder/Makefile.tracee-make alpine-prepare + STATIC=1 make -f builder/Makefile.tracee-make alpine-make ARG="all" + ``` + +2. Verify the executable is static + + * Note: ldd prints the shared libraries required by an executable file + + ```bash + ldd dist/tracee + ``` + + ```text + not a dynamic executable + ``` + +3. Execute the static binary from your host + + ```bash + sudo ./dist/tracee + ``` diff --git a/docs/contributing/documentation.md b/docs/contributing/documentation.md deleted file mode 100644 index c178dccefadd..000000000000 --- a/docs/contributing/documentation.md +++ /dev/null @@ -1,40 +0,0 @@ -# Contributing to the documentation - -We welcome contributions to the Tracee documentation. - -Our documentation aims to follow the [Diátaxis documentation framework](https://diataxis.fr/) which includes: - -1. A getting started section -- Installation Guidelines and simple scenarios -2. Tutorials -- End-to-end tutorials that have real-world use cases -3. Reference Material -- How to use Tracee -4. Contribution Guidelines - -To contribute to the documentation please - -1. Clone the Tracee GitHub repository -2. Make changes in the `./docs` directory in the root folder -3. Remember to edit the index in `mkdocs.yml` in the root folder if you add or move existing files or directories -4. Test your changes to the documentation -5. Submit a PR - -## Test Documentation Changes - -You can test your changes to the documentation by building and running a docker container. - -Prerequisites: Docker installed and running locally. - -Build the container image: -```bash -make -f ./builder/Makefile.mkdocs mkdocs-build -``` - -Serve the container image: -```bash -make -f ./builder/Makefile.mkdocs mkdocs-serve -``` - -Open `localhost:8000/tracee` - -Now you should see the documentation. - - diff --git a/docs/contributing/guidelines.md b/docs/contributing/guidelines.md index 864bba54ca5d..f66958b87aea 100644 --- a/docs/contributing/guidelines.md +++ b/docs/contributing/guidelines.md @@ -1,80 +1,111 @@ -## Style Guide for Contributors +# Style Guide for Contributors For those willing to contribute to Tracee, this repository has code formatting -guidelines being enforced. It is recommended that, before committing your -changes, you run the following command: +guidelines being enforced. -1. Check for formatting issues +## Contributing to Documentation -!!! check-fmt Example +Our documentation aims to follow the [Diátaxis documentation framework](https://diataxis.fr/). - ```console - make check-fmt - ``` +To contribute to the documentation: - ```text - Checking C and eBPF files and headers formatting... - Checking golang files formatting... - ``` - - > This will make sure PRs won't fail due to same checks being enforced. +1. Clone the Tracee GitHub repository. +2. Make changes in the `/docs` directory in the root folder. +3. Remember to edit the index in `mkdocs.yml` if you add or move existing files or directories. +4. Test your changes to the documentation. -2. Fix Go and C source files formatting +### Test Documentation Changes -!!! fix-fmt Example +You can test your changes to the documentation by building and running a docker container. +Prerequisites: Docker installed and running locally. +Build the container image: - ```console - make fix-fmt - ``` +```bash +make -f ./builder/Makefile.mkdocs mkdocs-build +``` - ```text - Fixing C and eBPF files and headers formatting... - Formatting ./pkg/ebpf/c/missing_definitions.h - Formatting ./pkg/ebpf/c/struct_flavors.h - Formatting ./pkg/ebpf/c/tracee.bpf.c - Formatting ./pkg/ebpf/c/vmlinux.h - - Fixing golang files formatting... - patching file pkg/ebpf/tracee.go - ``` +Serve the container image: + +```bash +make -f ./builder/Makefile.mkdocs mkdocs-serve +``` + +Open `localhost:8000/tracee` + +Now you should see the documentation. +Check that everything is like you intent. + +And finally Submit a PR about the changes. - ```console - git status -s +## Contributing to Tracee Code + +We welcome contributions to Tracee's codebase! Before submitting your changes, please familiarize yourself with these guidelines. +To contribute to the code: + +### Before You Commit + +Tracee relies on several generated files and has strict formatting requirements. Ensure you run the following commands before committing: + +**`NOTE:`** In order to not depend on host's libraries versions, we recommend that you always run make and other project dependencies on a virtual environment so the formatting will be align with Tracee guidelines + +1. Man Pages Generation: If you've modified core code or documentation that impacts the man pages, run: + + ```bash + make -f builder/Makefile.man ``` - ```text - M Makefile - M builder/Makefile.checkers - M pkg/ebpf/c/missing_definitions.h - M pkg/ebpf/c/struct_flavors.h - M pkg/ebpf/c/tracee.bpf.c - M pkg/ebpf/c/vmlinux.h + This regenerates the man pages to reflect your changes. + +2. Protocol Buffer Compilation: If your changes involve modifications to protocol buffer (`.proto`) files,run: + + ```bash + make -f builder/Makefile.man ``` -3. Static Check Go and C source files + This regenerates the corresponding Go code. +3. Pre-commit checks: Every time you're about to create a pull request, execute: -!!! check-code Example + **`NOTE:`** If your host machine dependencies doesn't align with Tracee dependencies, This command have to run on a supported [environment](./building/environment.md) - ```console - make check-code + ```bash + make check-pr ``` - ```text - Checking Golang vet... - make[2]: warning: jobserver unavailable: using -j1. Add '+' to parent make rule. - GOOS=linux CC=clang GOARCH=amd64 CGO_CFLAGS="-I/home/rafaeldtinoco/work/ebpf/tracee-review/dist/libbpf" CGO_LDFLAGS="-lelf -lz /home/rafaeldtinoco/work/ebpf/tracee-review/dist/libbpf/libbpf.a" \ - go vet \ - -tags core,ebpf \ - ./... - - Checking Golang with StaticChecker... - make[2]: warning: jobserver unavailable: using -j1. Add '+' to parent make rule. - GOOS=linux CC=clang GOARCH=amd64 CGO_CFLAGS="-I/home/rafaeldtinoco/work/ebpf/tracee-review/dist/libbpf" CGO_LDFLAGS="-lelf -lz /home/rafaeldtinoco/work/ebpf/tracee-review/dist/libbpf/libbpf.a" \ - staticcheck -f stylish \ - -tags core,ebpf \ - ./... - ✖ 0 problems (0 errors, 0 warnings, 0 ignored) - - Checking Golang with errcheck... + This command performs essential checks: + - `check-fmt`: Verifies code formatting adheres to project standards. + - `check-lint`: Runs linting tools (e.g., `golangci-lint`) to catch potential issues. + - `check-code`: Performs static code analysis for both Go and C code. + - `format-pr`: Displays the commits in your PR in a standardized format. + + **Note:** `check-fmt`,`check-lint`,`check-code`,`format-pr` are individual make command combined under `check-pr`. You can run the following command without any vm using Makefile + + - For `check-fmt`: + + ```bash + make -f builder/Makefile.checkers fmt-check + ``` + + - For `check-code`: + + ```bash + make -f builder/Makefile.checkers code-check + ``` + +4. Fixing Code Formatting: If `check-fmt` reports issues, use: + + ```bash + make -f builder/Makefile.checkers fmt-fix ``` + + This automatically formats your Go and C code to meet project standards. Review the changes with `git status -s` before committing. + +### Performance Considerations + +Performance is a critical aspect of Tracee. + +To ensure your contributions maintain optimal performance, follow the guidelines in [Performance Considerations](./performance.md) page. + +### Kubernetes Considerations + +If your contribution impacts Tracee's behavior within a Kubernetes cluster, follow the guidelines in [Kubernetes Considerations](./kubernetes.md). diff --git a/docs/contributing/kubernetes.md b/docs/contributing/kubernetes.md new file mode 100644 index 000000000000..dc4965cf9dd7 --- /dev/null +++ b/docs/contributing/kubernetes.md @@ -0,0 +1,66 @@ +# Kubernetes Considerations for Tracee Contributors + +1. **Set up a Local Kubernetes Cluster** + + We recommend using a local Kubernetes cluster for development and testing. Popular options include: + + * **kind:** Kubernetes IN Docker + * **minikube:** Runs a single-node cluster in a VM + * **MicroK8s:** Lightweight, snap-based Kubernetes + + Tracee's Makefile provides convenient targets for setting up MicroK8s: + + ```bash + make -f builder/Makefile.k8s help + ``` + + ```text + To build the operator docker container: + + $ make -f builder/Makefile.k8s build + + To generate the kubernetes manifests: + + $ make -f builder/Makefile.k8s manifests + + To generate operator code: + + $ make -f builder/Makefile.k8s generate + + Or simply: + + $ make -f builder/Makefile.k8s + ``` + +2. **Deploy Tracee** + + Deploy Tracee to your chosen local cluster. The deployment method will vary depending on your needs: + + * **DaemonSet:** For system-wide tracing, deploy Tracee as a DaemonSet. + * **Tracee Operator:** Use the Tracee operator for simplified management. + * **Other Methods:** Explore alternative methods like sidecar containers based on your use case. + +3. **Test Your Changes** + + Test your modifications with realistic scenarios within the Kubernetes environment. Consider these examples: + + * **Application Monitoring:** Deploy sample applications and observe Tracee's event capture for expected behavior. + * **Network Policies:** Configure network policies to restrict pod communication and verify Tracee captures relevant network events. + * **Resource Constraints:** Apply resource limits to pods and ensure Tracee functions correctly under constrained conditions. + * **Security Policies:** Implement Pod Security Policies and/or Security Contexts to validate Tracee's compliance and event capture in secure environments. + +4. **Monitor Tracee's Performance** + + Utilize Kubernetes' observability tools to monitor Tracee: + + * **Resource Usage:** Track pod resource consumption (CPU, memory) using `kubectl top` or monitoring dashboards. + * **Logs:** Analyze Tracee logs for errors, warnings, or unexpected behavior using `kubectl logs`. + * **Kubernetes Metrics:** If available, leverage Kubernetes metrics to gain insights into Tracee's performance. + +5. **Clean Up** + + After testing, remove deployed Tracee components and test resources to maintain a clean cluster environment. + +## Kubernetes-Specific Features + +If your contribution involves Kubernetes-specific features within Tracee (e.g., capturing Kubernetes events or metadata), ensure you test these functionalities thoroughly within the cluster environment. Pay close attention to event accuracy and any integration with Kubernetes APIs. diff --git a/docs/contributing/overview.md b/docs/contributing/overview.md index 04884f78cf46..570c5f7c7963 100644 --- a/docs/contributing/overview.md +++ b/docs/contributing/overview.md @@ -1,4 +1,4 @@ -## Contributing +# Contributing Thank you for taking interest in contributing to Tracee! This document covers our working practices and conventions. @@ -6,48 +6,65 @@ Thank you for taking interest in contributing to Tracee! This document covers ou We encourage open discussion and collaboration using both GitHub Issues and Discussions. -- [Discussions](https://github.com/aquasecurity/tracee/discussions) are free-style conversational tool, we use them for conversations. +- [Discussions](https://github.com/aquasecurity/tracee/discussions) are free-style conversational tool. - [Issues](https://github.com/aquasecurity/tracee/issues) are project management tool, we use them to keep track on who's working on what and plan ahead. If you have a suggestion, question, or a general comment - please use Discussions. If there's a clear work item (including bugs) - you can open an Issue. -### Discussions: +## Discussions -- We have the following discussion topics: - 1. [Announcements](https://github.com/aquasecurity/tracee/discussions/categories/announcements): One way communication from the team to the community. Consider this like our mini blog +- We have the following discussion topics: + 1. [Announcements](https://github.com/aquasecurity/tracee/discussions/categories/announcements): One way communication from the team to the community. Consider this like our mini blog. 1. [Questions and Help](https://github.com/aquasecurity/tracee/discussions/categories/questions-and-help): For help and support. Consider this similar to StackOverflow. 1. [Development](https://github.com/aquasecurity/tracee/discussions/categories/development): For discussing potential features, and collaborating on their design. -### Issues: - -1. Every issue needs to be actionable and assignable. Consider the scope of the issue if assigned to one person, and break down if necessary. -1. Be clear and definitive when composing issues. For bug reports, include detailed error messages and environment description. For features, include a clear scope and acceptance criteria. -1. Since we have different projects under the same monorepo, use labels to denote areas that the issue relates to: - 1. `tracee` - 1. `tracee-ebpf` - 1. `tracee-rules` - 1. `signatures` - 1. If non of the labels is relevant don't add any (usually for top-level issues) -1. We use the following labels to describe the type of issue: - 1. `bug` - 1. `good-first-issue` -1. Self-assign or request assignment for issues you intend to work on. Don't work on an issue assigned to someone else without checking with them first and reassigning. +## Issues + +1. **Actionable and Assignable:** Every issue must be clear, actionable, and assignable to a specific person. Break down large issues into smaller, more manageable tasks. +2. **Clear and Definitive Descriptions:** Be precise in your issue descriptions: + - **Bug Reports:** Include the following: + - Detailed steps to reproduce the bug. + - The complete error message. + - Your operating system, Tracee version, and any other relevant environment details. + - **Feature Requests:** Define: + - A clear scope for the feature. + - Specific acceptance criteria that will be used to determine if the feature is complete. +3. **Issue Labels:** We use these labels to categorize and track issues: + - `area/...` (e.g., `ebpf`, `events`): Specifies the area of Tracee affected by the issue. + - `kind/...` (e.g., `bug`, `chore`, `enhancement`, `documentation`): Indicates the type of issue. + - `milestone/...`: Specifies the target release for the issue. + - `priority/...`: Indicates the urgency of the issue. + - `good-first-issue`: Marks issues suitable for first-time contributors. + - `backport`: Applies to PRs targeting release branches for integrating changes from `main`. The original `main` PR gets labeled `backported/vX.X.X` after merge. + - `cherry-pick`: Similar to `backport`, but for specific commits. The original `main` PR gets labeled `cherry-picked/vX.X.X` after merge. + - `candidate/...`: (e.g., `candidate/v0.1.2`) Identifies PRs in the `main` branch as candidates for backporting or cherry-picking to a release branch (e.g., `v0.1.2`). The specific method will be determined during the porting process. + - `backported/...` (e.g., `backported/v0.1.2`): Marks PRs in the `main` branch as the basis for backporting changes to a release branch (e.g., `v0.1.2`) after the porting process. + - `cherry-picked/...` (e.g., `cherry-picked/v0.1.2`): Marks PRs in the `main` branch as the basis for cherry-picking commits to a release branch (e.g., `v0.1.2`) after the porting process. +4. **Issue Assignment:** Self-assign issues or request assignment. Don't work on an issue assigned to someone else without their consent. + +**Backporting and Cherry-Picking Workflow:** + +To backport or cherry-pick a change: + +1. Create a new PR targeting the appropriate release branch. +2. Label the new PR with `backport` or `cherry-pick`, depending on the method used. +3. Once the new PR is merged, remove the `candidate/vX.X.X` label from the original PR in `main`. +4. Finally, add the `backported/vX.X.X` or `cherry-picked/vX.X.X` label to the original PR in `main`, as appropriate. ## Pull Requests 1. Every Pull Request should have an associated Issue unless it is a trivial fix. -1. When adding a flag option or other UX related change, make sure the design is explicitly described in the associated issue, and a maintainer approved it. -1. Commit subject should succinctly describe the change: +2. When adding a flag option or other UX related change, make sure the design is explicitly described in the associated issue, and a maintainer approved it. +3. Commit subject should succinctly describe the change: 1. Max 50 chars. - 1. Written in imperative mood: begin with a verb like "fix", "add", "improve", or "refactor"; Think "once applied, this commit will...". - 1. If ambiguous, mention the area that this commit affects (see area labels above). -1. Optional commit body (separated by empty line from subject) may explain why the change was made and not how. Wrap at 72 chars. -1. Code related information should be in commit message, review related information should be in PR description. -1. For changes that span different areas please try to make each change self contained and independent. - + 2. Written in imperative mood: begin with a verb like "fix", "add", "improve", or "refactor"; Think "once applied, this commit will...". + 3. If ambiguous, mention the area that this commit affects (see area labels above). +4. Optional commit body (separated by empty line from subject) may explain why the change was made and not how. Wrap at 72 chars. +5. Code related information should be in commit message, review related information should be in PR description. +6. For changes that span different areas please try to make each change self contained and independent. ## Code -1. Follow Golang's code review standards: https://github.com/golang/go/wiki/CodeReviewComments. -1. Follow `gofmt` + `govet` + `goimports` formatting. -1. Tests should be included alongside code changes wherever applicable, except for parts that are harder to test and are not currently tested (e.g. eBPF). When modifying already tested code, your changes must be represented in the existing tests. +1. Follow Golang's code review standards: [https://github.com/golang/go/wiki/CodeReviewComments](https://github.com/golang/go/wiki/CodeReviewComments) +2. Follow `gofmt` + `govet` + `goimports` formatting. +3. Tests should be included alongside code changes wherever applicable, except for parts that are harder to test and are not currently tested (e.g. eBPF). When modifying already tested code, your changes must be represented in the existing tests. diff --git a/docs/contributing/performance.md b/docs/contributing/performance.md new file mode 100644 index 000000000000..f7d782c3307b --- /dev/null +++ b/docs/contributing/performance.md @@ -0,0 +1,33 @@ +# Performance Considerations + +1. **Profiling Tracee for Performance test** - Tracee integrates with Pyroscope and Pprof for continuous profiling. When running Tracee locally for development or testing, use the `--pyroscope --pprof` command-line option. + + ```bash + sudo ./dist/tracee --pyroscope --pprof + ``` + + This enables profiling data to be sent to a local server. The Tracee repository includes a convenient way to deploy a performance dashboard for analyzing this data. Run the following for more details: + + ```bash + make -f builder/Makefile.performance help + ``` + +2. **Performance Dashboard:** The provided performance dashboard allows visualization of host metrics, CPU flame graphs, and other performance-related data. Follow these steps to deploy locally and see instructions on using the dashboard: + + ```bash + make -f builder/Makefile.performance dashboard-start + ``` + + ```bash + make -f builder/Makefile.performance dashboard-stop + ``` + +3. **Benchmarking:** Before submitting significant code changes, consider running benchmarks to assess their impact on Tracee's performance. (Details on specific benchmarking tools or scripts used within the Tracee project should be added here. If there are existing benchmarks, provide instructions on how to run them. If not, suggest a methodology). + +4. **Common Performance Pitfalls:** + + - **Excessive eBPF Events:** Be mindful of the number and frequency of eBPF events being generated. Overly frequent events can lead to performance overhead. (Provide Tracee-specific examples or best practices to avoid this, such as filtering events effectively or using appropriate sampling rates.) + - **Inefficient eBPF Programs:** Optimize your eBPF programs for minimal overhead. (Provide Tracee-specific guidance. Are there common patterns to avoid within Tracee's eBPF context?) + - **Resource Consumption:** Consider the CPU and memory usage of Tracee itself. Avoid unnecessary allocations or computations. + +By adhering to these practices, you can contribute to Tracee's performance and help ensure its efficiency. Remember that performance is an ongoing effort, so continuous profiling, benchmarking, and optimization are essential. diff --git a/docs/contributing/setup-development-machine-with-vagrant.md b/docs/contributing/setup-development-machine-with-vagrant.md index 1e1df0f95117..fcf8da29daaf 100644 --- a/docs/contributing/setup-development-machine-with-vagrant.md +++ b/docs/contributing/setup-development-machine-with-vagrant.md @@ -4,10 +4,9 @@ all software requirements, packages, operating system configuration, and users to provide the same development environment for everyone. -The [Vagrantfile] describes the type of machine required to build Tracee from -source and follow the [Getting Started](../index.md) guides. This allows -developers involved in the project to check out the code, run `vagrant up`, and -be on their way. +The [Vagrantfile](/Vagrantfile) describes the type of machine required to build Tracee from the [Getting Started](../index.md) guides. + +This allows developers involved in the project to check out the code, run `vagrant up`, and be on their way. ## Prerequisites @@ -15,314 +14,99 @@ be on their way. - [Hypervisor] supported by Vagrant, such as [VirtualBox] on a amd64 (Linux) machine or [Parallels] on an arm64 M1 (Darwin) machine. +## Clone the Tracee Repository -## Create Development Machine - -Clone and change directory to Tracee Git repository: - -```console -git clone --branch {{ git.tag }} https://github.com/aquasecurity/tracee.git -cd tracee -``` - -Create and configure development machine according to the `Vagrantfile`: - -```console -vagrant up -``` - -If everything goes well, you can SSH into a running development machine and -access its shell: - -```console -vagrant ssh -``` - -```text -vagrant@ubuntu-jammy:/vagrant$ -``` - -!!! tip - Provisioning from scratch take time, but once created you can reuse the - machine with `vagrant halt` and `vagrant up` commands. If something goes - wrong with your machine, there's also the `vagrant destroy` to destroy it - and start over again. - -Synced folders enable Vagrant to sync a folder on the host machine to the -development machine, allowing you to continue working on your project's files -on your host machine, but use the resources in the development machine to -compile or run Tracee. - -By default, Vagrant will share Tracee project directory (the directory with the -`Vagrantfile`) to `/vagrant`. To get started list files: - -```console -ls -l -``` - -```text -total 648 -drwxr-xr-x 1 vagrant vagrant 4096 Mar 22 23:43 3rdparty --rw-r--r-- 1 vagrant vagrant 11358 Mar 18 14:45 LICENSE --rw-r--r-- 1 vagrant vagrant 21821 Mar 27 13:40 Makefile --rw-r--r-- 1 vagrant vagrant 133 Mar 18 14:45 NOTICE --rw-r--r-- 1 vagrant vagrant 2643 Mar 29 18:30 RELEASING.md --rw-r--r-- 1 vagrant vagrant 2238 Mar 22 23:43 Readme.md --rw-r--r-- 1 vagrant vagrant 3337 Mar 22 23:43 Vagrantfile -drwxr-xr-x 1 vagrant vagrant 4096 Mar 29 18:05 brand -drwxr-xr-x 1 vagrant vagrant 4096 Mar 22 23:43 builder -drwxr-xr-x 1 vagrant vagrant 4096 Mar 22 23:43 cmd --rw-r--r-- 1 vagrant vagrant 415013 Mar 28 23:17 coverage.txt -drwxr-xr-x 1 vagrant vagrant 4096 Mar 18 14:45 deploy -drwxr-xr-x 1 vagrant vagrant 4096 Mar 29 18:15 dist -drwxr-xr-x 1 vagrant vagrant 4096 Mar 22 23:43 docs --rw-r--r-- 1 vagrant vagrant 164 Mar 18 14:45 embedded-ebpf.go --rw-r--r-- 1 vagrant vagrant 101 Mar 18 14:45 embedded.go -drwxr-xr-x 1 vagrant vagrant 4096 Mar 27 12:08 examples --rw-r--r-- 1 vagrant vagrant 5599 Mar 29 17:22 go.mod --rw-r--r-- 1 vagrant vagrant 77170 Mar 29 17:22 go.sum --rw-r--r-- 1 vagrant vagrant 40206 Mar 22 23:43 mkdocs.yml -drwxr-xr-x 1 vagrant vagrant 4096 Mar 22 23:43 packaging -drwxr-xr-x 1 vagrant vagrant 4096 Mar 22 23:43 pkg -drwxr-xr-x 1 vagrant vagrant 4096 Mar 18 14:45 signatures --rw-r--r-- 1 vagrant vagrant 157 Mar 22 23:43 staticcheck.conf -drwxr-xr-x 1 vagrant vagrant 4096 Mar 24 15:44 tests -drwxr-xr-x 1 vagrant vagrant 4096 Mar 22 23:43 types -``` - -As you can see the `/vagrant` directory contains source code of Tracee cloned -from GitHub. - -## Build and Run Tracee - -To build **tracee** executable binary, run the -default make target: +Clone the Tracee repository to your local machine. This repository contains the Vagrantfile. -```console -make +```bash +git clone https://github.com/aquasecurity/tracee.git ``` -Build targets are saved in the `/vagrant/dist` directory: +## Navigate to the Tracee Directory -```console -ls -l dist/ -``` - -```text -total 161096 -drwxr-xr-x 1 vagrant vagrant 4096 Mar 29 19:06 btfhub -drwxr-xr-x 1 vagrant vagrant 4096 Mar 29 19:06 libbpf -drwxr-xr-x 1 vagrant vagrant 4096 Mar 29 19:08 signatures --rwxr-xr-x 1 vagrant vagrant 62619312 Mar 29 19:08 tracee --rw-r--r-- 1 vagrant vagrant 10753624 Mar 29 19:06 tracee.bpf.o -``` +Open a terminal and navigate to the directory containing the `Vagrantfile` within the cloned Tracee repository (`tracee/`) -You can now run Tracee and see events printed to the standard output in a tabular format: - -```console -sudo ./dist/tracee +```bash +cd tracee ``` -```text -TIME UID COMM PID TID RET EVENT ARGS -19:10:09:453832 0 coredns 1 8 0 security_socket_connect sockfd: 13, remote_addr: map[sa_family:AF_INET sin_addr:0.0.0.0 sin_port:8080] -19:10:09:454179 0 coredns 1 9 0 security_socket_accept sockfd: 8, local_addr: map[sa_family:AF_INET6 sin6_addr::: sin6_flowinfo:0 sin6_port:8080 sin6_scopeid:0] -19:10:09:454265 0 coredns 1 9 0 security_socket_accept sockfd: 8, local_addr: map[sa_family:AF_INET6 sin6_addr::: sin6_flowinfo:0 sin6_port:8080 sin6_scopeid:0] -19:10:09:454478 0 coredns 1 14 0 net_packet_http_request metadata: {127.0.0.1 127.0.0.1 43306 8080 6 144 any}, http_request: &{GET HTTP/1.1 :8080 /health map[Accept-Encoding:[gzip] User-Agent:[Go-http-client/1.1]] 0} -19:10:09:454774 0 coredns 1 14 0 net_packet_http_response metadata: {127.0.0.1 127.0.0.1 8080 43306 6 170 any}, http_response: &{200 OK 200 HTTP/1.1 map[Content-Length:[2] Content-Type:[text/plain; charset=utf-8] Date:[Wed, 29 Mar 2023 19:10:09 GMT]] 2} -19:10:10:452992 0 coredns 1 14 0 security_socket_connect sockfd: 13, remote_addr: map[sa_family:AF_INET sin_addr:0.0.0.0 sin_port:8080] -19:10:10:453850 0 coredns 1 1 0 security_socket_accept sockfd: 8, local_addr: map[sa_family:AF_INET6 sin6_addr::: sin6_flowinfo:0 sin6_port:8080 sin6_scopeid:0] -19:10:10:453983 0 coredns 1 1 0 security_socket_accept sockfd: 8, local_addr: map[sa_family:AF_INET6 sin6_addr::: sin6_flowinfo:0 sin6_port:8080 sin6_scopeid:0] -19:10:10:454612 0 coredns 1 9 0 net_packet_http_request metadata: {127.0.0.1 127.0.0.1 43318 8080 6 144 any}, http_request: &{GET HTTP/1.1 :8080 /health map[Accept-Encoding:[gzip] User-Agent:[Go-http-client/1.1]] 0} -19:10:10:455114 0 coredns 1 9 0 net_packet_http_response metadata: {127.0.0.1 127.0.0.1 8080 43318 6 170 any}, http_response: &{200 OK 200 HTTP/1.1 map[Content-Length:[2] Content-Type:[text/plain; charset=utf-8] Date:[Wed, 29 Mar 2023 19:10:10 GMT]] 2} -``` +## Configure VM Type (Optional) -## Switch Between CO-RE and non CO-RE Linux Distribution +The VM can be provisioned for either a `dev` or `test` environment. The `dev` environment includes additional tools like MicroK8s, kubectl, and Helm. -By default, the development machine is running Ubuntu Linux 22.04 Jammy Jellyfish. -You can see that it has a BTF-enabled kernel by checking the existence of the -`/sys/kernel/btf/vmlinux` file. +- **Development Environment:** Full development environment (Default) -```ruby -Vagrant.configure("2") do |config| - # config.vm.box = "ubuntu/focal64" # Ubuntu 20.04 Focal Fossa (non CO-RE) - # config.vm.box = "ubuntu/hirsute64" # Ubuntu 21.04 Hirsute Hippo (CO-RE) - # config.vm.box = "ubuntu/impish64" # Ubuntu 21.10 Impish Indri (CO-RE) - config.vm.box = "ubuntu/jammy64" # Ubuntu 22.04 Jammy Jellyfish (CO-RE) -... -``` + ```bash + export VM_TYPE=dev + ``` -Sometimes you may want to test Tracee with a non CO-RE distribution. You can do -that by editing the Vagrantfile and modifying the `config.vm.box` property. For -example, you can switch to Ubuntu Linux 20.04 Focal Fossa as follows: - -```ruby -Vagrant.configure("2") do |config| - config.vm.box = "ubuntu/focal64" # Ubuntu 20.04 Focal Fossa (non CO-RE) - # config.vm.box = "ubuntu/hirsute64" # Ubuntu 21.04 Hirsute Hippo (CO-RE) - # config.vm.box = "ubuntu/impish64" # Ubuntu 21.10 Impish Indri (CO-RE) - # config.vm.box = "ubuntu/jammy64" # Ubuntu 22.04 Jammy Jellyfish (CO-RE) -... -``` - -This change requires re-provisioning the development machine: +- **Testing Environment:** Smaller vagrant machine without k8s cumbersome to avoid conflicts with specific tests. -```console -vagrant destroy -vagrant up -``` + ```bash + export VM_TYPE=test + ``` -!!! Attention - Ubuntu Focal distribution has introduced BTF information to their recent - kernels, allowing eBPF CO-RE capable code to run. If you're willing to test - non CO-RE kernels, make sure to use an older kernel that does not provide - the `/sys/kernel/btf/vmlinux` file. +## Configure Resource Allocation (Optional) -## Deploy Tracee with Postee on Kubernetes +Customize the VM's resources by setting the following environment variables: -The development machine described by Vagrantfile pre-installs [MicroK8s] Kubernetes cluster, which is suitable for testing Tracee. +- `VM_PROC`: Number of virtual processors. Defaults to half of the host's processors. Example: -```console -microk8s status -``` + ```bash + export VM_PROC=4 + ``` -```text -microk8s is running -high-availability: no - datastore master nodes: 127.0.0.1:19001 - datastore standby nodes: none -... -``` +- `VM_MEM`: Memory in gigabytes. Defaults to 8GB. Example: -There's also the [kubectl] command installed and configured to communicate with -the cluster: + ```bash + export VM_MEM=16 + ``` -```console -kubectl get nodes -o wide -``` +## Start the VM -``` -NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME -ubuntu-jammy Ready 40m v1.26.1 10.0.2.15 Ubuntu 22.04.2 LTS 5.15.0-69-generic containerd://1.6.8 -``` +Run the following command to start the VM: -Create a new namespace called `tracee-system`: + ```bash + vagrant up + ``` -```console -kubectl create ns tracee-system -``` +Vagrant will download the base box, provision the VM, and install all required dependencies. This process may take some time. -Create Postee Persistent Volumes and StatefulSet in the `tracee-system` -namespace: +## Accessing the VM -```console -kubectl apply -n tracee-system \ - -f https://raw.githubusercontent.com/aquasecurity/postee/v2.2.0/deploy/kubernetes/hostPath/postee-pv.yaml \ - -f https://raw.githubusercontent.com/aquasecurity/postee/v2.2.0/deploy/kubernetes/postee.yaml -``` +Once the VM is up and running, you can access it via SSH: -Create Tracee DaemonSet in the `tracee-system`, configuring it to send -detections to the standard output and send them over to Postee webhook on -http://postee-svc:8082: - -```console -helm install tracee ./deploy/helm/tracee \ - --namespace tracee-system \ - --set hostPID=true \ - --set webhook=http://postee-svc:8082 -``` - -!!! tip - To test code that hasn't been released yet do the following: - - 1. Build the `tracee:latest` container image from the current Git revision: - ```console - make -f builder/Makefile.tracee-container build-tracee - ``` - 2. Import the container image to MicroK8s registry: - ```console - docker image save -o /tmp/tracee-latest.tar tracee:latest - microk8s ctr images import /tmp/tracee-latest.tar - rm /tmp/tracee-latest.tar - ``` - 3. Create Tracee DaemonSet using `tracee:latest` as container image: - ```console - kubectl apply -n tracee-system -k deploy/kubernetes/tracee - ``` - -While Tracee pod is running, run `strace ls` command and observe detection -printed to the standard output. - -```console -kubectl logs -n tracee-system -f daemonset/tracee -``` - -```text -INFO: probing tracee capabilities... -INFO: starting tracee... -{"timestamp":1680119087787203746,"threadStartTime":1680119087787109775,"processorId":0,"processId":95599,"cgroupId":9789,"threadId":95599,"parentProcessId":95597,"hostProcessId":95599,"hostThreadId":95599,"hostParentProcessId":95597,"userId":1000,"mountNamespace":4026531841,"pidNamespace":4026531836,"processName":"strace","hostName":"ubuntu-jammy","containerId":"","containerImage":"","containerName":"","podName":"","podNamespace":"","podUID":"","podSandbox":false,"eventId":"6018","eventName":"Anti-Debugging detected","matchedScopes":1,"argsNum":0,"returnValue":0,"syscall":"","stackAddresses":null,"contextFlags":{"containerStarted":false,"isCompat":false},"args":[],"metadata":{"Version":"1","Description":"A process used anti-debugging techniques to block a debugger. Malware use anti-debugging to stay invisible and inhibit analysis of their behavior.","Tags":null,"Properties":{"Category":"defense-evasion","Kubernetes_Technique":"","Severity":1,"Technique":"Debugger Evasion","external_id":"T1622","id":"attack-pattern--e4dc8c01-417f-458d-9ee0-bb0617c1b391","signatureID":"TRC-102","signatureName":"Anti-Debugging detected"}}} +```bash +vagrant ssh ``` -If everything is configured properly, you can find the same detection in Postee -logs: +This will place you in the `/vagrant` directory inside the VM, which is synced with the Tracee directory on your host machine. -```console -kubectl -n tracee-system logs -f postee-0 -``` - -```text -2023/03/29 19:44:47 {"timestamp":1680119087787203746,"threadStartTime":1680119087787109775,"processorId":0,"processId":95599,"cgroupId":9789,"threadId":95599,"parentProcessId":95597,"hostProcessId":95599,"hostThreadId":95599,"hostParentProcessId":95597,"userId":1000,"mountNamespace":4026531841,"pidNamespace":4026531836,"processName":"strace","hostName":"ubuntu-jammy","containerId":"","containerImage":"","containerName":"","podName":"","podNamespace":"","podUID":"","podSandbox":false,"eventId":"6018","eventName":"Anti-Debugging detected","matchedScopes":1,"argsNum":0,"returnValue":0,"syscall":"","stackAddresses":null,"contextFlags":{"containerStarted":false,"isCompat":false},"args":[],"metadata":{"Version":"1","Description":"A process used anti-debugging techniques to block a debugger. Malware use anti-debugging to stay invisible and inhibit analysis of their behavior.","Tags":null,"Properties":{"Category":"defense-evasion","Kubernetes_Technique":"","Severity":1,"Technique":"Debugger Evasion","external_id":"T1622","id":"attack-pattern--e4dc8c01-417f-458d-9ee0-bb0617c1b391","signatureID":"TRC-102","signatureName":"Anti-Debugging detected"}}} -``` +## Build and Run Tracee -### Access Kubernetes Dashboard +You can now build Tracee within the VM using the provided Makefile. Consult the Tracee documentation for specific build instructions. +[Building Tracee Documentation](./building/building.md) -Use the following command to get the token required to log in to the -[Kubernetes Dashboard]: +## Stopping the VM -```console -kubectl -n kube-system describe secret \ - $(kubectl -n kube-system get secret | grep default-token | cut -d " " -f1) -``` +To stop the VM, use: -Forward port 10443 in the development machine to the Kubernetes Dashboard's -pod: + ```bash + vagrant halt + ``` -```console -kubectl port-forward --address 0.0.0.0 -n kube-system service/kubernetes-dashboard 10443:443 -``` +## Destroying the VM -Since port 10443 is forwarded to port 10443 on your host, you can open your -browser to [https://localhost:10443](https://localhost:10443) and access -Kubernetes Dashboard. +To completely remove the VM, use: -!!! warning - Modern browser usually block insecure localhost TLS connections. For Google - Chrome you may allow insecure TLS connections at - [chrome://flags/#allow-insecure-localhost](chrome://flags/#allow-insecure-localhost). + ```bash + vagrant destroy + ``` -## Preview Tracee Documentation +**Troubleshooting:** -You can run [MkDocs] server and preview documentation on your host: +- Shared Folder Issues: If you experience issues with the shared folder, ensure your virtualization software's Guest Additions are properly installed and that the shared folder settings in the Vagrantfile match your setup. -```console -make -f builder/Makefile.mkdocs -``` +- Networking Issues: If you have trouble accessing forwarded ports, check your firewall settings on both the host and guest machines. -The development machine is running the MkDocs server listening on port 8000, -which is forwarded to port 8000 on your host. Therefore, you can open your -browser to [http://localhost:8000](http://localhost:8000) and access -documentation pages. - -[Vagrant]: https://www.vagrantup.com/docs/installation -[HashiCorp Vagrant]: https://www.vagrantup.com -[Vagrantfile]: https://github.com/aquasecurity/tracee/blob/{{ git.tag }}/Vagrantfile -[Hypervisor]: https://www.vagrantup.com/docs/providers -[VirtualBox]: https://www.virtualbox.org -[Parallels]: https://www.parallels.com -[MicroK8s]: https://microk8s.io -[MicroK8s add-ons]: https://microk8s.io/docs/addons -[kubectl]: https://kubernetes.io/docs/tasks/tools/#kubectl -[Kubernetes Dashboard]: https://github.com/kubernetes/dashboard -[Postee]: https://github.com/aquasecurity/postee -[Persistent Volumes]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/ -[MkDocs]: https://www.mkdocs.org +This setup provides a consistent and reproducible environment for developing and testing Tracee. Refer to the Tracee documentation for further details on building and using Tracee. diff --git a/mkdocs.yml b/mkdocs.yml index 2d04a5aec5d1..44047669aa71 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -612,8 +612,9 @@ nav: - Additional Resources: tutorials/additional-resources.md - Contributing: - Overview: contributing/overview.md - - Documentation: contributing/documentation.md - - Source Code Guidelines: contributing/guidelines.md + - Guidelines: contributing/guidelines.md + - Performence: contributing/performance.md + - Kubernetes: contributing/kubernetes.md - Setup Development Machine with Vagrant: contributing/setup-development-machine-with-vagrant.md - Building: - Building Tracee: contributing/building/building.md