{"id":15190183,"url":"https://github.com/coder/exectrace","last_synced_at":"2025-10-27T13:30:36.441Z","repository":{"id":44749055,"uuid":"433157920","full_name":"coder/exectrace","owner":"coder","description":"Simple eBPF-based exec snooping on Linux packaged as a Go library.","archived":false,"fork":false,"pushed_at":"2024-04-16T07:50:25.000Z","size":1858,"stargazers_count":29,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-02-06T12:11:47.469Z","etag":null,"topics":["ebpf","exec","execsnoop","linux"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-29T18:42:29.000Z","updated_at":"2025-01-20T21:55:20.000Z","dependencies_parsed_at":"2024-09-27T20:06:08.326Z","dependency_job_id":"ab3fdec5-f831-4f2c-bb59-fc548889ee0d","html_url":"https://github.com/coder/exectrace","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder%2Fexectrace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder%2Fexectrace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder%2Fexectrace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder%2Fexectrace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coder","download_url":"https://codeload.github.com/coder/exectrace/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238497666,"owners_count":19482296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ebpf","exec","execsnoop","linux"],"created_at":"2024-09-27T20:05:47.482Z","updated_at":"2025-10-27T13:30:30.917Z","avatar_url":"https://github.com/coder.png","language":"Go","readme":"# exectrace [![Go Reference](https://pkg.go.dev/badge/github.com/coder/exectrace.svg)](https://pkg.go.dev/github.com/coder/exectrace)\n\nSimple [eBPF](https://ebpf.io/)-based exec snooping on Linux packaged as a Go\nlibrary.\n\nexectrace loads a pre-compiled [eBPF program](./bpf/handler.c) into the running\nkernel to receive details about the `exec` family of syscalls.\n\n## Coder\n\nexectrace provides workspace process logging for Coder v1 and\n[Coder v2](https://github.com/coder/coder) (aka. Coder OSS).\n\nDocumentation for how to setup workspace process logging for Coder v1 users can\nbe found\n[here](https://coder.com/docs/v1/v1.38/admin/workspace-management/process-logging).\n\nDocumentation for Coder v2 users can be found in\n[enterprise/README.md](enterprise/README.md).\n\n## Requirements\n\nexectrace only supports Go 1.16+ and Linux kernel 5.8+ (due to the use of\n`BPF_MAP_TYPE_RINGBUF`). Additionally, the kernel config\n`CONFIG_DEBUG_INFO_BTF=y` is required.\n\nTo validate this config is enabled, run either of the following commands\ndirectly on the system:\n\n```console\n$ cat /proc/config.gz | gunzip | grep CONFIG_DEBUG_INFO_BTF\n```\n\n```console\n$ cat \"/boot/config-$(uname -r)\" | grep CONFIG_DEBUG_INFO_BTF\n```\n\n## Installation\n\n```console\n$ go get -u github.com/coder/exectrace\n```\n\n## Quickstart\n\nYou will need root access, `CAP_SYS_ADMIN` or `CAP_BPF`, to run eBPF programs on\nyour system.\n\n\u003e Use `go run -exec sudo ./cmd/program` to compile a program and start it with\n\u003e `sudo`\n\n```console\n$ go install -u github.com/coder/exectrace/cmd/exectrace\n$ exectrace --help\n...\n\n$ sudo exectrace\n2021/12/01 16:42:02 Waiting for events..\n[1188921, comm=\"node\", uid=1002, gid=1003, filename=/bin/sh] /bin/sh -c 'which ps'\n[1188922, comm=\"sh\", uid=1002, gid=1003, filename=/usr/bin/which] which ps\n```\n\n## Usage\n\nexectrace exposes a minimal API surface. Call `exectrace.New(nil)` and then you\ncan start reading events from the returned `Tracer`.\n\nIt is important that you close the tracer to avoid leaking kernel resources, so\nwe recommend implementing a simple signal handler like the one in this example:\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"os\"\n\t\"os/signal\"\n\t\"syscall\"\n\n\t\"github.com/coder/exectrace\"\n)\n\nfunc main() {\n\ttracer, err := exectrace.New(nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer tracer.Close()\n\n\tgo func() {\n\t\tsigs := make(chan os.Signal, 1)\n\t\tsignal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)\n\t\t\u003c-sigs\n\t\ttracer.Close()\n\t}()\n\n\tfor {\n\t\tevent, err := tracer.Read()\n\t\tif err != nil {\n\t\t\tpanic(err)\n\t\t}\n\n\t\tfmt.Printf(\"%+v\\n\", event)\n\t}\n}\n```\n\n\u003e For a full usage example, refer to this\n\u003e [comprehensive program](./cmd/exectrace/main.go) that uses the library.\n\n## Development\n\nYou will need the following:\n\n- Docker (the Makefile runs clang within a Docker container for reproducibility)\n- Golang 1.20+\n- `golangci-lint`\n- `prettier`\n- `shellcheck`\n\nSince the eBPF program is packaged using `go:embed`, you will need to compile\nthe program and include it in the repo.\n\nIf you change the files in the `bpf` directory, run `make` and ensure that you\ninclude the `.o` files you changed in your commit (CI will verify that you've\ndone this correctly).\n\n## Status: stable\n\nThis library is ready to use as-is. It has been used in production for years and\nhas received minimal maintenance over that time period.\n\nIn April 2024, a system to send logs from the kernel to userspace was added\nwhich can make discovering potential issues in production/development much\neasier.\n\nThe API will likely not be further modified as we have no need for additional\nfields/features. We will continue to maintain the library as needed.\n\n## See also\n\n- [`canonical/etrace`](https://github.com/canonical/etrace) - Go binary that\n  uses ptrace and tracks the processes that a command launches for debugging and\n  analysis\n- [`shirou/gopsutil`](https://github.com/shirou/gopsutil) - Go library that has\n  methods for listing process details and getting information about the system\n\n---\n\nDual licensed under the MIT and GPL 2.0 licenses. See [LICENSE](LICENSE).\n\nCode in the enterprise directory has a different license. See\n[LICENSE.enterprise](LICENSE.enterprise).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoder%2Fexectrace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoder%2Fexectrace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoder%2Fexectrace/lists"}