{"id":13598715,"url":"https://github.com/kxxt/tracexec","last_synced_at":"2025-04-14T05:19:23.334Z","repository":{"id":203928169,"uuid":"708418087","full_name":"kxxt/tracexec","owner":"kxxt","description":"Tracer for execve{,at} and pre-exec behavior, launcher for debuggers.","archived":false,"fork":false,"pushed_at":"2025-04-08T02:10:41.000Z","size":28422,"stargazers_count":311,"open_issues_count":21,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-14T05:19:02.000Z","etag":null,"topics":["command-line-tool","debugger","ebpf","exec","execve","ptrace","strace","tracer","tracexec","tui"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kxxt.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2023-10-22T14:06:18.000Z","updated_at":"2025-04-02T21:41:06.000Z","dependencies_parsed_at":null,"dependency_job_id":"554205c2-ce63-4d29-81ee-bee37b29ed49","html_url":"https://github.com/kxxt/tracexec","commit_stats":{"total_commits":863,"total_committers":5,"mean_commits":172.6,"dds":0.004634994206257237,"last_synced_commit":"e98dbcfa365c9464a6ae4d2f08b3b366522d145c"},"previous_names":["kxxt/tracexec"],"tags_count":59,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kxxt%2Ftracexec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kxxt%2Ftracexec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kxxt%2Ftracexec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kxxt%2Ftracexec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kxxt","download_url":"https://codeload.github.com/kxxt/tracexec/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248824733,"owners_count":21167351,"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":["command-line-tool","debugger","ebpf","exec","execve","ptrace","strace","tracer","tracexec","tui"],"created_at":"2024-08-01T17:00:55.341Z","updated_at":"2025-04-14T05:19:23.309Z","avatar_url":"https://github.com/kxxt.png","language":"Rust","readme":"# tracexec\n\nA small utility for tracing execve{,at} and pre-exec behavior.\n\ntracexec helps you to figure out what and how programs get executed when you execute a command.\n\nIt's useful for debugging build systems, understanding what shell scripts actually do, figuring out what programs\ndoes a proprietary software run, etc.\n\n- [Installation Guide](INSTALL.md)\n\n## Showcases\n\n### TUI mode with pseudo terminal\n\nIn TUI mode with a pseudo terminal, you can view the details of exec events and interact with the processes\nwithin the pseudo terminal at ease.\n\n![TUI demo](https://github.com/kxxt/tracexec/blob/main/screenshots/tui-demo.gif?raw=true)\n\n### Tracing setuid binaries\n\nWith root privileges, you can also trace setuid binaries and see how they work.\nBut do note that this is not compatible with seccomp-bpf optimization so it is much less performant.\nYou can use eBPF mode which is more performant in such scenarios.\n\n```\nsudo tracexec --user $(whoami) tui -t -- sudo ls\n```\n\n![Tracing sudo ls](https://github.com/kxxt/tracexec/blob/main/screenshots/tracing-sudo.png?raw=true)\n\nNested setuid binary tracing is also possible: A real world use case is to trace `extra-x86_64-build`(Arch Linux's build tool that requires sudo):\n\n![Tracing extra-x86_64-build](https://github.com/kxxt/tracexec/blob/main/screenshots/tracing-nested-setuid.gif?raw=true)\n\nIn this real world example, we can easily see that `_FORTIFY_SOURCE` is redefined from `2` to `3`, which lead to a compiler error.\n\n### Use tracexec as a debugger launcher\n\ntracexec can also be used as a debugger launcher to make debugging programs easier. For example, it's not trivial or convenient\nto debug a program executed by a shell/python script(which can use pipes as stdio for the program). The following video shows how to\nuse tracexec to launch gdb to detach two simple programs piped together by a shell script.\n\nhttps://github.com/kxxt/tracexec/assets/18085551/72c755a5-0f2f-4bf9-beb9-98c8d6b5e5fd\n\nPlease [read the gdb-launcher example](https://github.com/kxxt/tracexec/blob/main/demonstration/gdb-launcher/README.md) for more details.\n\n### eBPF mode\n\nThe eBPF mode is currently experimental.\nIt is known to work on Linux 6.6 lts and 6.10 and probably works on all 6.x kernels.\nFor kernel versions less than 6.2, you'll need to enable `ebpf-no-rcu-kfuncs` feature.\nIt won't work on kernel version \u003c 5.17.\n\nThe following examples shows how to use eBPF in TUI mode.\nThe `eBPF` command also supports regular `log` and `collect` subcommands.\n\n#### System-wide Exec Tracing\n\n```bash\nsudo -E tracexec ebpf tui\n```\n[ebpf-system-wide-tui.webm](https://github.com/user-attachments/assets/12cec4ef-8884-4580-a93a-c9144ec7102b)\n\n#### Follow Fork mode with eBPF\n\n```bash\nsudo -E tracexec --user $(whoami) ebpf tui -t -- bash\n```\n\n[ebpf-follow-forks.webm](https://github.com/user-attachments/assets/997e1992-df85-4d45-ae68-faf693c6b99b)\n\n### Log mode\n\nIn log mode, by default, `tracexec` will print filename, argv and the diff of the environment variables and file descriptors.\n\nexample: `tracexec log -- bash` (In an interactive bash shell)\n\n[![asciicast](https://asciinema.org/a/sNptWG6De3V5xwUvXJAxWlO3i.svg)](https://asciinema.org/a/sNptWG6De3V5xwUvXJAxWlO3i)\n\n### Reconstruct the command line with `--show-cmdline`\n\n```bash\n$ tracexec log --show-cmdline -- \u003ccommand\u003e\n# example:\n$ tracexec log --show-cmdline -- firefox\n```\n\n[![asciicast](https://asciinema.org/a/AWTG4iHaFPMcEGCVtqAl44YFW.svg)](https://asciinema.org/a/AWTG4iHaFPMcEGCVtqAl44YFW)\n\n### Try to reproduce stdio in the reconstructed command line\n\n`--stdio-in-cmdline` and `--fd-in-cmdline` can be used to reproduce(hopefully) the stdio used by a process.\n\nBut do note that the result might be inaccurate when pipes, sockets, etc are involved.\n\n```bash\ntracexec log --show-cmdline --stdio-in-cmdline -- bash\n```\n\n[![asciicast](https://asciinema.org/a/NkBTaoNHS7P7bolO0hNuRwGlQ.svg)](https://asciinema.org/a/NkBTaoNHS7P7bolO0hNuRwGlQ)\n\n### Show the interpreter indicated by shebang with `--show-interpreter`\n\nAnd show the cwd with `--show-cwd`.\n\n```bash\n$ tracexec log --show-interpreter --show-cwd -- \u003ccommand\u003e\n# example: Running Arch Linux makepkg\n$ tracexec log --show-interpreter --show-cwd -- makepkg -f\n```\n\n[![asciicast](https://asciinema.org/a/7jDtrlNRx5XUnDXeDBsMRj09p.svg)](https://asciinema.org/a/7jDtrlNRx5XUnDXeDBsMRj09p)\n\n## Usage\n\nGeneral CLI help:\n\n```bash\nTracer for execve{,at} and pre-exec behavior, launcher for debuggers.\n\nUsage: tracexec [OPTIONS] \u003cCOMMAND\u003e\n\nCommands:\n  log                   Run tracexec in logging mode\n  tui                   Run tracexec in TUI mode, stdin/out/err are redirected to /dev/null by default\n  generate-completions  Generate shell completions for tracexec\n  collect               Collect exec events and export them\n  ebpf                  Experimental ebpf mode\n  help                  Print this message or the help of the given subcommand(s)\n\nOptions:\n      --color \u003cCOLOR\u003e      Control whether colored output is enabled. This flag has no effect on TUI mode. [default: auto] [possible values: auto, always, never]\n  -C, --cwd \u003cCWD\u003e          Change current directory to this path before doing anything\n  -P, --profile \u003cPROFILE\u003e  Load profile from this path\n      --no-profile         Do not load profiles\n  -u, --user \u003cUSER\u003e        Run as user. This option is only available when running tracexec as root\n  -h, --help               Print help\n  -V, --version            Print version\n\n```\n\nTUI Mode:\n\n```bash\nRun tracexec in TUI mode, stdin/out/err are redirected to /dev/null by default\n\nUsage: tracexec tui [OPTIONS] -- \u003cCMD\u003e...\n\nArguments:\n  \u003cCMD\u003e...  command to be executed\n\nOptions:\n      --successful-only\n          Only show successful calls\n      --fd-in-cmdline\n          [Experimental] Try to reproduce file descriptors in commandline. This might result in an unexecutable cmdline if pipes, sockets, etc. are involved.\n      --stdio-in-cmdline\n          [Experimental] Try to reproduce stdio in commandline. This might result in an unexecutable cmdline if pipes, sockets, etc. are involved.\n      --resolve-proc-self-exe\n          Resolve /proc/self/exe symlink\n      --no-resolve-proc-self-exe\n          Do not resolve /proc/self/exe symlink\n      --seccomp-bpf \u003cSECCOMP_BPF\u003e\n          Controls whether to enable seccomp-bpf optimization, which greatly improves performance [default: auto] [possible values: auto, on, off]\n      --tracer-delay \u003cTRACER_DELAY\u003e\n          Delay between polling, in microseconds. The default is 500 when seccomp-bpf is enabled, otherwise 1.\n      --show-all-events\n          Set the default filter to show all events. This option can be used in combination with --filter-exclude to exclude some unwanted events.\n      --filter \u003cFILTER\u003e\n          Set the default filter for events. [default: warning,error,exec,tracee-exit]\n      --filter-include \u003cFILTER_INCLUDE\u003e\n          Aside from the default filter, also include the events specified here. [default: \u003cempty\u003e]\n      --filter-exclude \u003cFILTER_EXCLUDE\u003e\n          Exclude the events specified here from the default filter. [default: \u003cempty\u003e]\n  -t, --tty\n          Allocate a pseudo terminal and show it alongside the TUI\n  -f, --follow\n          Keep the event list scrolled to the bottom\n      --terminate-on-exit\n          Instead of waiting for the root child to exit, terminate when the TUI exits\n      --kill-on-exit\n          Instead of waiting for the root child to exit, kill when the TUI exits\n  -A, --active-pane \u003cACTIVE_PANE\u003e\n          Set the default active pane to use when TUI launches [possible values: terminal, events]\n  -L, --layout \u003cLAYOUT\u003e\n          Set the layout of the TUI when it launches [possible values: horizontal, vertical]\n  -F, --frame-rate \u003cFRAME_RATE\u003e\n          Set the frame rate of the TUI (60 by default)\n  -m, --max-events \u003cMAX_EVENTS\u003e\n          Max number of events to keep in TUI (0=unlimited)\n  -D, --default-external-command \u003cDEFAULT_EXTERNAL_COMMAND\u003e\n          Set the default external command to run when using \"Detach, Stop and Run Command\" feature in Hit Manager\n  -b, --add-breakpoint \u003cBREAKPOINTS\u003e\n          Add a new breakpoint to the tracer. This option can be used multiple times. The format is \u003csyscall-stop\u003e:\u003cpattern-type\u003e:\u003cpattern\u003e, where syscall-stop can be sysenter or sysexit, pattern-type can be argv-regex, in-filename or exact-filename. For example, sysexit:in-filename:/bash\n  -h, --help\n          Print help\n\n```\n\nLog Mode:\n\n```bash\nRun tracexec in logging mode\n\nUsage: tracexec log [OPTIONS] -- \u003cCMD\u003e...\n\nArguments:\n  \u003cCMD\u003e...  command to be executed\n\nOptions:\n      --more-colors\n          More colors\n      --less-colors\n          Less colors\n      --show-cmdline\n          Print commandline that (hopefully) reproduces what was executed. Note: file descriptors are not handled for now.\n      --no-show-cmdline\n          Don't print commandline that (hopefully) reproduces what was executed.\n      --show-interpreter\n          Try to show script interpreter indicated by shebang\n      --no-show-interpreter\n          Do not show script interpreter indicated by shebang\n      --foreground\n          Set the terminal foreground process group to tracee. This option is useful when tracexec is used interactively. [default]\n      --no-foreground\n          Do not set the terminal foreground process group to tracee\n      --diff-fd\n          Diff file descriptors with the original std{in/out/err}\n      --no-diff-fd\n          Do not diff file descriptors\n      --show-fd\n          Show file descriptors\n      --no-show-fd\n          Do not show file descriptors\n      --diff-env\n          Diff environment variables with the original environment\n      --no-diff-env\n          Do not diff environment variables\n      --show-env\n          Show environment variables\n      --no-show-env\n          Do not show environment variables\n      --show-comm\n          Show comm\n      --no-show-comm\n          Do not show comm\n      --show-argv\n          Show argv\n      --no-show-argv\n          Do not show argv\n      --show-filename\n          Show filename\n      --no-show-filename\n          Do not show filename\n      --show-cwd\n          Show cwd\n      --no-show-cwd\n          Do not show cwd\n      --decode-errno\n          Decode errno values\n      --no-decode-errno\n          Do not decode errno values\n      --successful-only\n          Only show successful calls\n      --fd-in-cmdline\n          [Experimental] Try to reproduce file descriptors in commandline. This might result in an unexecutable cmdline if pipes, sockets, etc. are involved.\n      --stdio-in-cmdline\n          [Experimental] Try to reproduce stdio in commandline. This might result in an unexecutable cmdline if pipes, sockets, etc. are involved.\n      --resolve-proc-self-exe\n          Resolve /proc/self/exe symlink\n      --no-resolve-proc-self-exe\n          Do not resolve /proc/self/exe symlink\n      --seccomp-bpf \u003cSECCOMP_BPF\u003e\n          Controls whether to enable seccomp-bpf optimization, which greatly improves performance [default: auto] [possible values: auto, on, off]\n      --tracer-delay \u003cTRACER_DELAY\u003e\n          Delay between polling, in microseconds. The default is 500 when seccomp-bpf is enabled, otherwise 1.\n      --show-all-events\n          Set the default filter to show all events. This option can be used in combination with --filter-exclude to exclude some unwanted events.\n      --filter \u003cFILTER\u003e\n          Set the default filter for events. [default: warning,error,exec,tracee-exit]\n      --filter-include \u003cFILTER_INCLUDE\u003e\n          Aside from the default filter, also include the events specified here. [default: \u003cempty\u003e]\n      --filter-exclude \u003cFILTER_EXCLUDE\u003e\n          Exclude the events specified here from the default filter. [default: \u003cempty\u003e]\n  -o, --output \u003cOUTPUT\u003e\n          Output, stderr by default. A single hyphen '-' represents stdout.\n  -h, --help\n          Print help\n\n```\n\nCollect and export data:\n\n```\nCollect exec events and export them\n\nUsage: tracexec collect [OPTIONS] --format \u003cFORMAT\u003e -- \u003cCMD\u003e...\n\nArguments:\n  \u003cCMD\u003e...  command to be executed\n\nOptions:\n      --successful-only              Only show successful calls\n      --fd-in-cmdline                [Experimental] Try to reproduce file descriptors in commandline. This might result in an unexecutable cmdline if pipes, sockets, etc. are involved.\n      --stdio-in-cmdline             [Experimental] Try to reproduce stdio in commandline. This might result in an unexecutable cmdline if pipes, sockets, etc. are involved.\n      --resolve-proc-self-exe        Resolve /proc/self/exe symlink\n      --no-resolve-proc-self-exe     Do not resolve /proc/self/exe symlink\n      --seccomp-bpf \u003cSECCOMP_BPF\u003e    Controls whether to enable seccomp-bpf optimization, which greatly improves performance [default: auto] [possible values: auto, on, off]\n      --tracer-delay \u003cTRACER_DELAY\u003e  Delay between polling, in microseconds. The default is 500 when seccomp-bpf is enabled, otherwise 1.\n  -F, --format \u003cFORMAT\u003e              the format for exported exec events [possible values: json-stream, json]\n  -p, --pretty                       prettify the output if supported\n  -o, --output \u003cOUTPUT\u003e              Output, stderr by default. A single hyphen '-' represents stdout.\n      --foreground                   Set the terminal foreground process group to tracee. This option is useful when tracexec is used interactively. [default]\n      --no-foreground                Do not set the terminal foreground process group to tracee\n  -h, --help                         Print help\n\n```\n\neBPF backend supports similar commands:\n\n```\nExperimental ebpf mode\n\nUsage: tracexec ebpf \u003cCOMMAND\u003e\n\nCommands:\n  log      Run tracexec in logging mode\n  tui      Run tracexec in TUI mode, stdin/out/err are redirected to /dev/null by default\n  collect  Collect exec events and export them\n  help     Print this message or the help of the given subcommand(s)\n\nOptions:\n  -h, --help  Print help\n\n```\n\n## Profile\n\n`tracexec` can be configured with a profile file. The profile file is a toml file that can be used to set fallback options.\n\nThe profile file should be placed at `$XDG_CONFIG_HOME/tracexec/` or `$HOME/.config/tracexec/` and named `config.toml`.\n\nA template profile file can be found at https://github.com/kxxt/tracexec/blob/main/config.toml\n\nAs a warning, the profile format is not stable yet and may change in the future. You may need to update your profile file when upgrading tracexec.\n\n## Known issues\n\n- Non UTF-8 strings are converted to UTF-8 in a lossy way, which means that the output may be inaccurate.\n- For eBPF backend, it might be impossible to show some details of the tracee, See https://mozillazg.com/2024/03/ebpf-tracepoint-syscalls-sys-enter-execve-can-not-get-filename-argv-values-case-en.html\n- The output is not stable yet, which means that the output may change in the future.\n- Test coverage is not good enough.\n- The pseudo terminal can't pass through certain key combinations and terminal features.\n\n## Origin\n\nThis project was born out of the need to trace the execution of programs.\n\nInitially I simply use `strace -Y -f -qqq -s99999 -e trace=execve,execveat \u003ccommand\u003e`.\n\nBut the output is still too verbose so that's why I created this project.\n\n## Credits\n\nThis project takes inspiration from [strace](https://strace.io/) and [lurk](https://github.com/JakWai01/lurk).\n","funding_links":[],"categories":["Rust","Development tools","💻 Apps"],"sub_categories":["Debugging","Other dialects and variants","⌨️ Development Tools"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkxxt%2Ftracexec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkxxt%2Ftracexec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkxxt%2Ftracexec/lists"}