From bcc39f7805fd333cd7f7be0e0ef478f15f1f8cf6 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Mon, 9 Dec 2024 21:18:24 +0000 Subject: [PATCH 01/15] add first changes to guidelines --- docs/contributing/documentation.md | 6 ++-- docs/contributing/guidelines.md | 37 +++++++++----------- docs/contributing/overview.md | 54 ++++++++++++++++-------------- 3 files changed, 47 insertions(+), 50 deletions(-) diff --git a/docs/contributing/documentation.md b/docs/contributing/documentation.md index c178dccefadd..4d1e82d9a85a 100644 --- a/docs/contributing/documentation.md +++ b/docs/contributing/documentation.md @@ -9,7 +9,7 @@ Our documentation aims to follow the [Diátaxis documentation framework](https:/ 3. Reference Material -- How to use Tracee 4. Contribution Guidelines -To contribute to the documentation please +To contribute to the documentation: 1. Clone the Tracee GitHub repository 2. Make changes in the `./docs` directory in the root folder @@ -24,11 +24,13 @@ You can test your changes to the documentation by building and running a docker 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 ``` @@ -36,5 +38,3 @@ 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..f06854c76757 100644 --- a/docs/contributing/guidelines.md +++ b/docs/contributing/guidelines.md @@ -1,27 +1,25 @@ -## 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: -1. Check for formatting issues +1. Check your PR -!!! check-fmt Example +```console +make check-pr +``` - ```console - make check-fmt - ``` +This command will run: - ```text - Checking C and eBPF files and headers formatting... - Checking golang files formatting... - ``` - +1. `check-fmt` - check for formatting changes > This will make sure PRs won't fail due to same checks being enforced. +2. `check-lint` +3. `check-code` +4. `format-pr` -2. Fix Go and C source files formatting -!!! fix-fmt Example +5. Fix Go and C source files formatting ```console make fix-fmt @@ -51,10 +49,7 @@ changes, you run the following command: M pkg/ebpf/c/vmlinux.h ``` -3. Static Check Go and C source files - - -!!! check-code Example +6. Static Check Go and C source files ```console make check-code @@ -65,15 +60,15 @@ changes, you run the following command: 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 \ - ./... + -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 \ - ./... + -tags core,ebpf \ + ./... ✖ 0 problems (0 errors, 0 warnings, 0 ignored) Checking Golang with errcheck... diff --git a/docs/contributing/overview.md b/docs/contributing/overview.md index 04884f78cf46..89973242dcd0 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,50 @@ 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: +- 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: +## 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: +2. 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. +3. 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. + 2. `tracee-ebpf` + 3. `tracee-rules` + 4. `signatures` + 5. If non of the labels is relevant don't add any (usually for top-level issues) +4. We use the following labels to describe the type of issue: + 1. `area/...` like: `ebpf`, `events` + 2. `kind/...` like: `bug`, `chore` + 3. `milestone/...` +5. 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. ## 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. From 55663e14b05d40c303f0941da9b504a39aa1f30a Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Tue, 10 Dec 2024 11:06:25 +0000 Subject: [PATCH 02/15] improve docs of guidelines and overview in contributing --- docs/contributing/guidelines.md | 130 +++++++++++++++----------------- docs/contributing/overview.md | 14 ++-- 2 files changed, 68 insertions(+), 76 deletions(-) diff --git a/docs/contributing/guidelines.md b/docs/contributing/guidelines.md index f06854c76757..cb832b918369 100644 --- a/docs/contributing/guidelines.md +++ b/docs/contributing/guidelines.md @@ -1,75 +1,69 @@ # 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 your PR +## Contributing to Documentation -```console -make check-pr +Our documentation aims to follow the [Diátaxis documentation framework](https://diataxis.fr/) which includes: + +To contribute to the documentation: + +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. + +### 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 ``` -This command will run: - -1. `check-fmt` - check for formatting changes - > This will make sure PRs won't fail due to same checks being enforced. -2. `check-lint` -3. `check-code` -4. `format-pr` - - -5. Fix Go and C source files formatting - - ```console - make fix-fmt - ``` - - ```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 - ``` - - ```console - git status -s - ``` - - ```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 - ``` - -6. Static Check Go and C source files - - ```console - make check-code - ``` - - ```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... - ``` +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. + +## Contributing to Code + +To contribute to the documentation: + +1. Clone the Tracee GitHub repository. +2. Make changes to code. +3. before committing your changes, run the following command: + 1. Check your PR: + + ```console + make check-pr + ``` + + This command will run: + 1. `check-fmt` - check for formatting changes + 2. `check-lint` - lint golang code + 3. `check-code` - Static Check Go and C source files + 4. `format-pr` - show PR commits + + 2. Fix Go and C source files formatting + + ```console + make fix-fmt + ``` + + After you run the fix, check your git status. + + ```console + git status -s + ``` diff --git a/docs/contributing/overview.md b/docs/contributing/overview.md index 89973242dcd0..a8b920d30dd7 100644 --- a/docs/contributing/overview.md +++ b/docs/contributing/overview.md @@ -24,17 +24,15 @@ If you have a suggestion, question, or a general comment - please use Discussion 2. 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. -3. Since we have different projects under the same monorepo, use labels to denote areas that the issue relates to: - 1. `tracee` - 2. `tracee-ebpf` - 3. `tracee-rules` - 4. `signatures` - 5. If non of the labels is relevant don't add any (usually for top-level issues) -4. We use the following labels to describe the type of issue: +3. We use the following labels to describe the type of issue: 1. `area/...` like: `ebpf`, `events` 2. `kind/...` like: `bug`, `chore` 3. `milestone/...` -5. 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. + 4. `priority/...` + 5. `good-first-issue` + 6. `backported/...` + 7. `cherry-picked/...` +4. 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. ## Pull Requests From 95e86ccb97e8cf04e4a17d9722671904b1f63e6b Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Tue, 10 Dec 2024 14:42:10 +0000 Subject: [PATCH 03/15] combine documentation and code guidelines --- docs/contributing/documentation.md | 40 ------------------------------ docs/contributing/guidelines.md | 10 ++++---- mkdocs.yml | 3 +-- 3 files changed, 6 insertions(+), 47 deletions(-) delete mode 100644 docs/contributing/documentation.md diff --git a/docs/contributing/documentation.md b/docs/contributing/documentation.md deleted file mode 100644 index 4d1e82d9a85a..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: - -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 cb832b918369..6028142bf1d7 100644 --- a/docs/contributing/guidelines.md +++ b/docs/contributing/guidelines.md @@ -39,11 +39,11 @@ And finally Submit a PR about the changes. ## Contributing to Code -To contribute to the documentation: +To contribute to the code: 1. Clone the Tracee GitHub repository. 2. Make changes to code. -3. before committing your changes, run the following command: +3. Before committing your changes, run the following command: 1. Check your PR: ```console @@ -51,10 +51,10 @@ To contribute to the documentation: ``` This command will run: - 1. `check-fmt` - check for formatting changes - 2. `check-lint` - lint golang code + 1. `check-fmt` - Check for formatting changes + 2. `check-lint` - Lint golang code 3. `check-code` - Static Check Go and C source files - 4. `format-pr` - show PR commits + 4. `format-pr` - Show PR commits 2. Fix Go and C source files formatting diff --git a/mkdocs.yml b/mkdocs.yml index d3d2e1692123..99aacf50f77a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -614,8 +614,7 @@ 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 - Setup Development Machine with Vagrant: contributing/setup-development-machine-with-vagrant.md - Building: - Building Tracee: contributing/building/building.md From 2b29f81b3f4f9dd4f288fe5bab4d61559f50a87e Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Tue, 10 Dec 2024 17:10:29 +0000 Subject: [PATCH 04/15] improve docs for setup development machine --- .../setup-development-machine-with-vagrant.md | 334 ++++-------------- 1 file changed, 59 insertions(+), 275 deletions(-) diff --git a/docs/contributing/setup-development-machine-with-vagrant.md b/docs/contributing/setup-development-machine-with-vagrant.md index 1e1df0f95117..7f1b7d327080 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.builder` within the cloned Tracee repository. Rename `Vagrantfile.builder` to `Vagrantfile`. -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:** Use the default setting (no action needed), or explicitly set: -```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:** -```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 (Ubuntu 22.04), 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. From 0dbe799173cde6137ac6e142e7f4b6fbff02a92f Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Tue, 10 Dec 2024 17:32:30 +0000 Subject: [PATCH 05/15] improve building tracee docs --- docs/contributing/building/building.md | 62 +------------------------- 1 file changed, 1 insertion(+), 61 deletions(-) diff --git a/docs/contributing/building/building.md b/docs/contributing/building/building.md index 74b7b098489a..d2744ac326da 100644 --- a/docs/contributing/building/building.md +++ b/docs/contributing/building/building.md @@ -33,17 +33,7 @@ 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. + git clone [https://github.com/aquasecurity/tracee/](https://github.com/aquasecurity/tracee/) ``` 4. All makefiles have a **help** target to give you needed instructions @@ -99,57 +89,18 @@ 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 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 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 @@ -169,14 +120,3 @@ ```console 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 - ``` From 482c1072b70bd78f53de56feb5bb10b17487108e Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Wed, 11 Dec 2024 08:55:48 +0000 Subject: [PATCH 06/15] improve environment building docs --- docs/contributing/building/environment.md | 177 ++++++++++------------ 1 file changed, 81 insertions(+), 96 deletions(-) diff --git a/docs/contributing/building/environment.md b/docs/contributing/building/environment.md index 0926103b6389..3572b6cbe24e 100644 --- a/docs/contributing/building/environment.md +++ b/docs/contributing/building/environment.md @@ -14,72 +14,44 @@ 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 bash 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**. + +There are Two different environments that are maintained for building tracee: + +* **Alpine** +* **Ubuntu** -Two different environments are maintained for building tracee: +The reason for that is that **Alpine Linux** is based in the [musl](https://en.wikipedia.org/wiki/Musl) C standard library. -* Alpine -* Ubuntu +while the **Ubuntu Linux** uses [glibc](https://en.wikipedia.org/wiki/Glibc). -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. +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 @@ -117,55 +89,68 @@ builds (and executes) correctly in both environments. ### 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: + +1. Create builder environment as described: + [Creating a builder environment](#creating-a-builder-environment) +2. Compile tracee using `ubuntu-make` + + * Build tracee binary + + ```bash + make -f builder/Makefile.tracee-make ubuntu-make ARG="tracee" + ``` + + * Show help for make file -```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" -``` + ```bash + make -f builder/Makefile.tracee-make ubuntu-make ARG="help" + ``` -And, after the compilation, run the commands directly in your host: + * Remove 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="clean" + ``` -> **Note**: the generated binary must be compatible to your host (depending on -> glibc version, for example). + * Build binaries for all -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="all" + ``` -```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" -``` +3. Run tracee binary -and execute the static binary from your host: + ```bash + sudo ./dist/tracee + ``` -```console -ldd dist/tracee -``` +> **Note**: the generated binary must be compatible to your host (depending on glibc version). -```text -not a dynamic executable -``` +If you don't want to depend on host's libraries versions, or your host is not an **Alpine Linux** or you are using the `alpine-tracee-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: -!!! 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 - > ``` +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 print 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 + ``` From 4bfe8168b5abec91f6b44cb6585797253aa17ca8 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Wed, 11 Dec 2024 09:28:30 +0000 Subject: [PATCH 07/15] change console to bash --- docs/contributing/building/building.md | 12 ++++++------ docs/contributing/building/environment.md | 18 +++++++++--------- docs/contributing/guidelines.md | 6 +++--- 3 files changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/contributing/building/building.md b/docs/contributing/building/building.md index d2744ac326da..a238dfedba5d 100644 --- a/docs/contributing/building/building.md +++ b/docs/contributing/building/building.md @@ -32,13 +32,13 @@ 3. **Clone** [tracee repository](https://github.com/aquasecurity/tracee/) - ```console + ```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 ``` @@ -85,19 +85,19 @@ 5. Build **all** targets at once - ```console + ```bash make all ``` 6. Build a **static binary** by setting `STATIC=1` - ```console + ```bash STATIC=1 make all ``` 7. Build a **static binary** with [BTFHUB Support](https://github.com/aquasecurity/btfhub) - ```console + ```bash BTFHUB=1 STATIC=1 make all ``` @@ -117,6 +117,6 @@ 8. Build a **debugable binary** with DWARF generation by setting `DEBUG=1` - ```console + ```bash DEBUG=1 make ``` diff --git a/docs/contributing/building/environment.md b/docs/contributing/building/environment.md index 3572b6cbe24e..88de2a387dd1 100644 --- a/docs/contributing/building/environment.md +++ b/docs/contributing/building/environment.md @@ -63,13 +63,13 @@ By supporting both building environments we can always be sure that the project * 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 ``` @@ -77,13 +77,13 @@ By supporting both building environments we can always be sure that the project * 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 ``` @@ -95,26 +95,26 @@ Instead of executing a builder shell, you may use `alpine-make`, or 1. Create builder environment as described: [Creating a builder environment](#creating-a-builder-environment) 2. Compile tracee using `ubuntu-make` - - * Build tracee binary + + * Build tracee binary: ```bash make -f builder/Makefile.tracee-make ubuntu-make ARG="tracee" ``` - * Show help for make file + * Show help for make file: ```bash make -f builder/Makefile.tracee-make ubuntu-make ARG="help" ``` - * Remove tracee binary + * Remove tracee binary ```bash make -f builder/Makefile.tracee-make ubuntu-make ARG="clean" ``` - * Build binaries for all + * Build binaries for all ```bash make -f builder/Makefile.tracee-make ubuntu-make ARG="all" diff --git a/docs/contributing/guidelines.md b/docs/contributing/guidelines.md index 6028142bf1d7..e20b5bdb86a3 100644 --- a/docs/contributing/guidelines.md +++ b/docs/contributing/guidelines.md @@ -46,7 +46,7 @@ To contribute to the code: 3. Before committing your changes, run the following command: 1. Check your PR: - ```console + ```bash make check-pr ``` @@ -58,12 +58,12 @@ To contribute to the code: 2. Fix Go and C source files formatting - ```console + ```bash make fix-fmt ``` After you run the fix, check your git status. - ```console + ```bash git status -s ``` From 3b7832354653bb7949df06166321d184bab74807 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Wed, 11 Dec 2024 13:24:34 +0000 Subject: [PATCH 08/15] add Kubernetes, Performance and Man docs to tracee --- docs/contributing/guidelines.md | 66 ++++++++++++++++++++++---------- docs/contributing/kubernetes.md | 48 +++++++++++++++++++++++ docs/contributing/performance.md | 33 ++++++++++++++++ mkdocs.yml | 2 + 4 files changed, 128 insertions(+), 21 deletions(-) create mode 100644 docs/contributing/kubernetes.md create mode 100644 docs/contributing/performance.md diff --git a/docs/contributing/guidelines.md b/docs/contributing/guidelines.md index e20b5bdb86a3..3c307e293f19 100644 --- a/docs/contributing/guidelines.md +++ b/docs/contributing/guidelines.md @@ -37,33 +37,57 @@ Check that everything is like you intent. And finally Submit a PR about the changes. -## Contributing to Code +## 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: -1. Clone the Tracee GitHub repository. -2. Make changes to code. -3. Before committing your changes, run the following command: - 1. Check your PR: +### Before You Commit + +Tracee relies on several generated files and has strict formatting requirements. Ensure you run the following commands before committing: + +1. Man Pages Generation: If you've modified core code or documentation that impacts the man pages, run: + + ```bash + make -f builder/Makefile.man + ``` + + 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 + ``` + + This regenerates the corresponding Go code. + +3. Pre-commit checks: Every time you're about to create a pull request, execute: + + ```bash + make check-pr + ``` + + 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. + +4. Fixing Code Formatting: If `check-fmt` reports issues, use: + + ```bash + make fix-fmt + ``` - ```bash - make check-pr - ``` + This automatically formats your Go and C code to meet project standards. Review the changes with `git status -s` before committing. - This command will run: - 1. `check-fmt` - Check for formatting changes - 2. `check-lint` - Lint golang code - 3. `check-code` - Static Check Go and C source files - 4. `format-pr` - Show PR commits +### Performance Considerations - 2. Fix Go and C source files formatting +Performance is a critical aspect of Tracee. - ```bash - make fix-fmt - ``` +To ensure your contributions maintain optimal performance, follow the guidelines in [Performance Considerations](./performance.md) page. - After you run the fix, check your git status. +### Kubernetes Considerations - ```bash - git status -s - ``` +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..8b9c3dc673cc --- /dev/null +++ b/docs/contributing/kubernetes.md @@ -0,0 +1,48 @@ +# 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 + ``` + +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/performance.md b/docs/contributing/performance.md new file mode 100644 index 000000000000..4271405153c0 --- /dev/null +++ b/docs/contributing/performance.md @@ -0,0 +1,33 @@ +# Performance Considerations + +1. **Profiling with Pyroscope:** Tracee integrates with Pyroscope for continuous profiling. When running Tracee locally for development or testing, use the --pyroscope command-line option. For example: + + ```bash + sudo ./dist/tracee --pyroscope + ``` + + This enables profiling data to be sent to a local Pyroscope 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 dasboard: + + ```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/mkdocs.yml b/mkdocs.yml index 99aacf50f77a..b734d453cd1e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -615,6 +615,8 @@ nav: - Contributing: - Overview: contributing/overview.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 From 363e7b21fa726f185c4e1533a6c2da97e07fd609 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Wed, 11 Dec 2024 17:02:03 +0000 Subject: [PATCH 09/15] add checkers docsto guidelines --- docs/contributing/building/environment.md | 2 +- docs/contributing/guidelines.md | 24 +++++++++++++++++++++++ 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/contributing/building/environment.md b/docs/contributing/building/environment.md index 88de2a387dd1..06ee34286ec3 100644 --- a/docs/contributing/building/environment.md +++ b/docs/contributing/building/environment.md @@ -128,7 +128,7 @@ Instead of executing a builder shell, you may use `alpine-make`, or > **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 your host is not an **Alpine Linux** or you are using the `alpine-tracee-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: +If you don't want to depend on host's libraries versions, or your host is not an **Alpine Linux** 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 diff --git a/docs/contributing/guidelines.md b/docs/contributing/guidelines.md index 3c307e293f19..117419d1e487 100644 --- a/docs/contributing/guidelines.md +++ b/docs/contributing/guidelines.md @@ -74,6 +74,8 @@ Tracee relies on several generated files and has strict formatting requirements. - `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` + 4. Fixing Code Formatting: If `check-fmt` reports issues, use: ```bash @@ -82,6 +84,28 @@ Tracee relies on several generated files and has strict formatting requirements. This automatically formats your Go and C code to meet project standards. Review the changes with `git status -s` before committing. +If you don't want to depend on host's libraries versions, or your host is not an **Alpine Linux**/**Ubuntu Linux** or you are using the `alpine-make`/`ubuntu-make` container as a replacement for `make`: + +you can run the equivalents checks in a container: + +* For `check-fmt`: + + ```bash + make -f builder/Makefile.checkers fmt-check + ``` + +* For `fix-fmt`: + + ```bash + make -f builder/Makefile.checkers fmt-fix + ``` + +* For `check-code`: + + ```bash + make -f builder/Makefile.checkers code-check + ``` + ### Performance Considerations Performance is a critical aspect of Tracee. From 0501e58731d1597a61cbacd506f01fedbae70305 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Wed, 11 Dec 2024 17:16:21 +0000 Subject: [PATCH 10/15] fix minor issues --- docs/contributing/guidelines.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/contributing/guidelines.md b/docs/contributing/guidelines.md index 117419d1e487..a425445c4eca 100644 --- a/docs/contributing/guidelines.md +++ b/docs/contributing/guidelines.md @@ -69,10 +69,10 @@ Tracee relies on several generated files and has strict formatting requirements. ``` 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. + - `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` @@ -88,19 +88,19 @@ If you don't want to depend on host's libraries versions, or your host is not an you can run the equivalents checks in a container: -* For `check-fmt`: +- For `check-fmt`: ```bash make -f builder/Makefile.checkers fmt-check ``` -* For `fix-fmt`: +- For `fix-fmt`: ```bash make -f builder/Makefile.checkers fmt-fix ``` -* For `check-code`: +- For `check-code`: ```bash make -f builder/Makefile.checkers code-check From a6b3995357077a4b9b1bf4cd3506dbbfb2597bcb Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Thu, 12 Dec 2024 19:13:57 +0000 Subject: [PATCH 11/15] resolve most changes --- docs/contributing/building/building.md | 6 ++++++ docs/contributing/building/environment.md | 2 +- docs/contributing/setup-development-machine-with-vagrant.md | 6 +++--- 3 files changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/contributing/building/building.md b/docs/contributing/building/building.md index a238dfedba5d..0316457800ae 100644 --- a/docs/contributing/building/building.md +++ b/docs/contributing/building/building.md @@ -120,3 +120,9 @@ ```bash DEBUG=1 make ``` + +9. Build with embedded metrics (pprof) by setting `METRICS=1` + + ```bash + METRICS=1 make + ``` diff --git a/docs/contributing/building/environment.md b/docs/contributing/building/environment.md index 06ee34286ec3..3cb7c8c74123 100644 --- a/docs/contributing/building/environment.md +++ b/docs/contributing/building/environment.md @@ -34,7 +34,7 @@ --scope follow ``` -Now, in your host's bash shell, execute a command. You will see all events +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 diff --git a/docs/contributing/setup-development-machine-with-vagrant.md b/docs/contributing/setup-development-machine-with-vagrant.md index 7f1b7d327080..3b76938e0a7a 100644 --- a/docs/contributing/setup-development-machine-with-vagrant.md +++ b/docs/contributing/setup-development-machine-with-vagrant.md @@ -34,13 +34,13 @@ cd tracee The VM can be provisioned for either a `dev` or `test` environment. The `dev` environment includes additional tools like MicroK8s, kubectl, and Helm. -- **Development Environment:** Use the default setting (no action needed), or explicitly set: +- **Development Environment:** Full development environment ```bash export VM_TYPE=dev ``` -- **Testing Environment:** +- **Testing Environment:** Smaller vagrant machine without k8s cumbersome to avoid conflicts with specific tests. ```bash export VM_TYPE=test @@ -70,7 +70,7 @@ Run the following command to start the VM: vagrant up ``` -Vagrant will download the base box (Ubuntu 22.04), provision the VM, and install all required dependencies. This process may take some time. +Vagrant will download the base box, provision the VM, and install all required dependencies. This process may take some time. ## Accessing the VM From ab51f00b3cae8b73690da9a577bd8ab96848c417 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Tue, 17 Dec 2024 20:32:39 +0000 Subject: [PATCH 12/15] improve metrics=1 docs --- docs/contributing/building/building.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/contributing/building/building.md b/docs/contributing/building/building.md index 0316457800ae..ae5bfb3a4699 100644 --- a/docs/contributing/building/building.md +++ b/docs/contributing/building/building.md @@ -115,13 +115,15 @@ >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 generation by setting `DEBUG=1` ```bash DEBUG=1 make ``` -9. Build with embedded metrics (pprof) by setting `METRICS=1` +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 From 540c8cefcaf6fb7efa1b21f2450c459c7ed4127f Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Tue, 17 Dec 2024 20:55:09 +0000 Subject: [PATCH 13/15] improve guidelines to use makefiles mostly --- docs/contributing/guidelines.md | 36 ++++++++++++++------------------- 1 file changed, 15 insertions(+), 21 deletions(-) diff --git a/docs/contributing/guidelines.md b/docs/contributing/guidelines.md index a425445c4eca..a5feac4fcbf2 100644 --- a/docs/contributing/guidelines.md +++ b/docs/contributing/guidelines.md @@ -46,6 +46,8 @@ To contribute to the code: 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 @@ -64,6 +66,8 @@ Tracee relies on several generated files and has strict formatting requirements. 3. Pre-commit checks: Every time you're about to create a pull request, execute: + **`NOTE:`** If your host machine dependencies doesn't align with tracee dependencies, This command have to run on a supported [environment](./building/environment.md) + ```bash make check-pr ``` @@ -74,37 +78,27 @@ Tracee relies on several generated files and has strict formatting requirements. - `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` - -4. Fixing Code Formatting: If `check-fmt` reports issues, use: - - ```bash - make fix-fmt - ``` - - This automatically formats your Go and C code to meet project standards. Review the changes with `git status -s` before committing. + **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 -If you don't want to depend on host's libraries versions, or your host is not an **Alpine Linux**/**Ubuntu Linux** or you are using the `alpine-make`/`ubuntu-make` container as a replacement for `make`: + - For `check-fmt`: -you can run the equivalents checks in a container: + ```bash + make -f builder/Makefile.checkers fmt-check + ``` -- For `check-fmt`: + - For `check-code`: - ```bash - make -f builder/Makefile.checkers fmt-check - ``` + ```bash + make -f builder/Makefile.checkers code-check + ``` -- For `fix-fmt`: +4. Fixing Code Formatting: If `check-fmt` reports issues, use: ```bash make -f builder/Makefile.checkers fmt-fix ``` -- For `check-code`: - - ```bash - make -f builder/Makefile.checkers code-check - ``` + This automatically formats your Go and C code to meet project standards. Review the changes with `git status -s` before committing. ### Performance Considerations From c14fbca45588337fd4f86820278abcc906419758 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Sun, 22 Dec 2024 11:41:44 +0000 Subject: [PATCH 14/15] update make help --- Makefile | 2 +- docs/contributing/building/building.md | 6 +++++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 715af62e6697..7bf4b2097052 100644 --- a/Makefile +++ b/Makefile @@ -318,13 +318,13 @@ help: @echo " $$ make test-unit # run unit tests" @echo " $$ make test-types # run unit tests for types module" @echo " $$ make test-integration # run integration tests" - @echo " $$ make test-signatures # opa test (tracee-rules)" @echo "" @echo "# flags" @echo "" @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 ae5bfb3a4699..203a156d0d86 100644 --- a/docs/contributing/building/building.md +++ b/docs/contributing/building/building.md @@ -54,10 +54,12 @@ $ make tracee-ebpf # build ./dist/tracee-ebpf $ make tracee-rules # build ./dist/tracee-rules $ make tracee-bench # build ./dist/tracee-bench + $ make tracee-gptdocs # build ./dist/tracee-gptdocs $ make signatures # build ./dist/signatures $ 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 @@ -68,19 +70,21 @@ $ 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 $ make test-unit # run unit tests $ make test-types # run unit tests for types module $ make test-integration # run integration tests - $ make test-signatures # opa test (tracee-rules) # flags $ 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 From 4aae9c7d944afa313c1e15506a9a7606737063d2 Mon Sep 17 00:00:00 2001 From: ShohamBit Date: Sun, 22 Dec 2024 18:09:55 +0000 Subject: [PATCH 15/15] add help text --- docs/contributing/kubernetes.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/contributing/kubernetes.md b/docs/contributing/kubernetes.md index 8b9c3dc673cc..dc4965cf9dd7 100644 --- a/docs/contributing/kubernetes.md +++ b/docs/contributing/kubernetes.md @@ -14,6 +14,24 @@ 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: