Movatterモバイル変換


[0]ホーム

URL:


Skip to content

Navigation Menu

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up

Tracer for execve{,at} and pre-exec behavior, launcher for debuggers.

License

NotificationsYou must be signed in to change notification settings

kxxt/tracexec

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

A small utility for tracing execve{,at} and pre-exec behavior.

tracexec helps you to figure out what and how programs get executed when you execute a command.

It's useful for debugging build systems, understanding what shell scripts actually do, figuring out what programsdoes a proprietary software run, etc.

Showcases

TUI mode with pseudo terminal

In TUI mode with a pseudo terminal, you can view the details of exec events and interact with the processeswithin the pseudo terminal at ease.

TUI demo

Tracing setuid binaries

With root privileges, you can also trace setuid binaries and see how they work.But do note that this is not compatible with seccomp-bpf optimization so it is much less performant.You can use eBPF mode which is more performant in such scenarios.

sudo tracexec --user $(whoami) tui -t -- sudo ls

Tracing sudo ls

Nested setuid binary tracing is also possible: A real world use case is to traceextra-x86_64-build(Arch Linux's build tool that requires sudo):

Tracing extra-x86_64-build

In this real world example, we can easily see that_FORTIFY_SOURCE is redefined from2 to3, which lead to a compiler error.

Use tracexec as a debugger launcher

tracexec can also be used as a debugger launcher to make debugging programs easier. For example, it's not trivial or convenientto debug a program executed by a shell/python script(which can use pipes as stdio for the program). The following video shows how touse tracexec to launch gdb to detach two simple programs piped together by a shell script.

gdb-launcher.mp4

Pleaseread the gdb-launcher example for more details.

eBPF mode

The eBPF mode is currently experimental.It is known to work on Linux 6.6 lts and 6.10 and probably works on all 6.x kernels.For kernel versions less than 6.2, you'll need to enableebpf-no-rcu-kfuncs feature.It won't work on kernel version < 5.17.

The following examples shows how to use eBPF in TUI mode.TheeBPF command also supports regularlog andcollect subcommands.

System-wide Exec Tracing

sudo -E tracexec ebpf tui
ebpf-system-wide-tui.webm

Follow Fork mode with eBPF

sudo -E tracexec --user$(whoami) ebpf tui -t -- bash
ebpf-follow-forks.webm

Log mode

In log mode, by default,tracexec will print filename, argv and the diff of the environment variables and file descriptors.

example:tracexec log -- bash (In an interactive bash shell)

asciicast

Reconstruct the command line with--show-cmdline

$ tracexec log --show-cmdline --<command># example:$ tracexec log --show-cmdline -- firefox

asciicast

Try to reproduce stdio in the reconstructed command line

--stdio-in-cmdline and--fd-in-cmdline can be used to reproduce(hopefully) the stdio used by a process.

But do note that the result might be inaccurate when pipes, sockets, etc are involved.

tracexec log --show-cmdline --stdio-in-cmdline -- bash

asciicast

Show the interpreter indicated by shebang with--show-interpreter

And show the cwd with--show-cwd.

$ tracexec log --show-interpreter --show-cwd --<command># example: Running Arch Linux makepkg$ tracexec log --show-interpreter --show-cwd -- makepkg -f

asciicast

Usage

General CLI help:

Tracerfor execve{,at} and pre-exec behavior, launcherfor debuggers.Usage: tracexec [OPTIONS]<COMMAND>Commands:  log                   Run tracexecin logging mode  tui                   Run tracexecin TUI mode, stdin/out/err are redirected to /dev/null by default  generate-completions  Generate shell completionsfor tracexec  collect               Collectexec events andexport them  ebpf                  Experimental ebpf modehelp                  Print this message or thehelp of the given subcommand(s)Options:      --color<COLOR>      Control whether colored output is enabled. This flag has no effect on TUI mode. [default: auto] [possible values: auto, always, never]  -C, --cwd<CWD>          Change current directory to this path before doing anything  -P, --profile<PROFILE>  Load profile from this path      --no-profile         Do not load profiles  -u, --user<USER>        Run as user. This option is only available when running tracexec as root  -h, --help               Printhelp  -V, --version            Print version

TUI Mode:

Run tracexecin TUI mode, stdin/out/err are redirected to /dev/null by defaultUsage: tracexec tui [OPTIONS] --<CMD>...Arguments:<CMD>...command to be executedOptions:      --successful-only          Only show successful calls      --fd-in-cmdline          [Experimental] Try to reproduce file descriptorsin commandline. This might resultin an unexecutable cmdlineif pipes, sockets, etc. are involved.      --stdio-in-cmdline          [Experimental] Try to reproduce stdioin commandline. This might resultin an unexecutable cmdlineif pipes, sockets, etc. are involved.      --resolve-proc-self-exe          Resolve /proc/self/exe symlink      --no-resolve-proc-self-exe          Do not resolve /proc/self/exe symlink      --seccomp-bpf<SECCOMP_BPF>          Controls whether toenable seccomp-bpf optimization, which greatly improves performance [default: auto] [possible values: auto, on, off]      --tracer-delay<TRACER_DELAY>          Delay between polling,in microseconds. The default is 500 when seccomp-bpf is enabled, otherwise 1.      --show-all-events          Set the default filter to show all events. This option can be usedin combination with --filter-exclude to exclude some unwanted events.      --filter<FILTER>          Set the default filterfor events. [default: warning,error,exec,tracee-exit]      --filter-include<FILTER_INCLUDE>          Aside from the default filter, also include the events specified here. [default:<empty>]      --filter-exclude<FILTER_EXCLUDE>          Exclude the events specified here from the default filter. [default:<empty>]  -t, --tty          Allocate a pseudo terminal and show it alongside the TUI  -f, --follow          Keep the event list scrolled to the bottom      --terminate-on-exit          Instead of waitingfor the root child to exit, terminate when the TUI exits      --kill-on-exit          Instead of waitingfor the root child to exit,kill when the TUI exits  -A, --active-pane<ACTIVE_PANE>          Set the default active pane to use when TUI launches [possible values: terminal, events]  -L, --layout<LAYOUT>          Set the layout of the TUI when it launches [possible values: horizontal, vertical]  -F, --frame-rate<FRAME_RATE>          Set the frame rate of the TUI (60 by default)  -m, --max-events<MAX_EVENTS>          Max number of events to keepin TUI (0=unlimited)  -D, --default-external-command<DEFAULT_EXTERNAL_COMMAND>          Set the default externalcommand to run when using"Detach, Stop and Run Command" featurein Hit Manager  -b, --add-breakpoint<BREAKPOINTS>          Add a new breakpoint to the tracer. This option can be used multiple times. The format is<syscall-stop>:<pattern-type>:<pattern>, 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  -h, --help          Printhelp

Log Mode:

Run tracexecin logging modeUsage: tracexec log [OPTIONS] --<CMD>...Arguments:<CMD>...command to be executedOptions:      --more-colors          More colors      --less-colors          Less colors      --show-cmdline          Print commandline that (hopefully) reproduces what was executed. Note: file descriptors are not handledfor now.      --no-show-cmdline          Don't print commandline that (hopefully) reproduces what was executed.      --show-interpreter          Try to show script interpreter indicated by shebang      --no-show-interpreter          Do not show script interpreter indicated by shebang      --foreground          Set the terminal foreground process group to tracee. This option is useful when tracexec is used interactively. [default]      --no-foreground          Do not set the terminal foreground process group to tracee      --diff-fd          Diff file descriptors with the original std{in/out/err}      --no-diff-fd          Do not diff file descriptors      --show-fd          Show file descriptors      --no-show-fd          Do not show file descriptors      --diff-env          Diff environment variables with the original environment      --no-diff-env          Do not diff environment variables      --show-env          Show environment variables      --no-show-env          Do not show environment variables      --show-comm          Show comm      --no-show-comm          Do not show comm      --show-argv          Show argv      --no-show-argv          Do not show argv      --show-filename          Show filename      --no-show-filename          Do not show filename      --show-cwd          Show cwd      --no-show-cwd          Do not show cwd      --decode-errno          Decode errno values      --no-decode-errno          Do not decode errno values      --successful-only          Only show successful calls      --fd-in-cmdline          [Experimental] Try to reproduce file descriptors in commandline. This might result in an unexecutable cmdline if pipes, sockets, etc. are involved.      --stdio-in-cmdline          [Experimental] Try to reproduce stdio in commandline. This might result in an unexecutable cmdline if pipes, sockets, etc. are involved.      --resolve-proc-self-exe          Resolve /proc/self/exe symlink      --no-resolve-proc-self-exe          Do not resolve /proc/self/exe symlink      --seccomp-bpf <SECCOMP_BPF>          Controls whether to enable seccomp-bpf optimization, which greatly improves performance [default: auto] [possible values: auto, on, off]      --tracer-delay <TRACER_DELAY>          Delay between polling, in microseconds. The default is 500 when seccomp-bpf is enabled, otherwise 1.      --show-all-events          Set the default filter to show all events. This option can be used in combination with --filter-exclude to exclude some unwanted events.      --filter <FILTER>          Set the default filter for events. [default: warning,error,exec,tracee-exit]      --filter-include <FILTER_INCLUDE>          Aside from the default filter, also include the events specified here. [default: <empty>]      --filter-exclude <FILTER_EXCLUDE>          Exclude the events specified here from the default filter. [default: <empty>]  -o, --output <OUTPUT>          Output, stderr by default. A single hyphen'-' represents stdout.  -h, --help          Print help

Collect and export data:

Collect exec events and export themUsage: tracexec collect [OPTIONS] --format <FORMAT> -- <CMD>...Arguments:  <CMD>...  command to be executedOptions:      --successful-only              Only show successful calls      --fd-in-cmdline                [Experimental] Try to reproduce file descriptors in commandline. This might result in an unexecutable cmdline if pipes, sockets, etc. are involved.      --stdio-in-cmdline             [Experimental] Try to reproduce stdio in commandline. This might result in an unexecutable cmdline if pipes, sockets, etc. are involved.      --resolve-proc-self-exe        Resolve /proc/self/exe symlink      --no-resolve-proc-self-exe     Do not resolve /proc/self/exe symlink      --seccomp-bpf <SECCOMP_BPF>    Controls whether to enable seccomp-bpf optimization, which greatly improves performance [default: auto] [possible values: auto, on, off]      --tracer-delay <TRACER_DELAY>  Delay between polling, in microseconds. The default is 500 when seccomp-bpf is enabled, otherwise 1.  -F, --format <FORMAT>              the format for exported exec events [possible values: json-stream, json]  -p, --pretty                       prettify the output if supported  -o, --output <OUTPUT>              Output, stderr by default. A single hyphen '-' represents stdout.      --foreground                   Set the terminal foreground process group to tracee. This option is useful when tracexec is used interactively. [default]      --no-foreground                Do not set the terminal foreground process group to tracee  -h, --help                         Print help

eBPF backend supports similar commands:

Experimental ebpf modeUsage: tracexec ebpf <COMMAND>Commands:  log      Run tracexec in logging mode  tui      Run tracexec in TUI mode, stdin/out/err are redirected to /dev/null by default  collect  Collect exec events and export them  help     Print this message or the help of the given subcommand(s)Options:  -h, --help  Print help

Profile

tracexec can be configured with a profile file. The profile file is a toml file that can be used to set fallback options.

The profile file should be placed at$XDG_CONFIG_HOME/tracexec/ or$HOME/.config/tracexec/ and namedconfig.toml.

A template profile file can be found athttps://github.com/kxxt/tracexec/blob/main/config.toml

As 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.

Known issues

Origin

This project was born out of the need to trace the execution of programs.

Initially I simply usestrace -Y -f -qqq -s99999 -e trace=execve,execveat <command>.

But the output is still too verbose so that's why I created this project.

Credits

This project takes inspiration fromstrace andlurk.


[8]ページ先頭

©2009-2025 Movatter.jp