tracexec

一个用于跟踪 execve{,at} 和执行前行为的小工具。

tracexec 可以帮助你了解在执行命令时程序是如何被执行的。

它对于调试构建系统、理解 shell 脚本的实际行为、查明专有软件运行了哪些程序等非常有用。

功能展示

带伪终端的 TUI 模式

在带伪终端的 TUI 模式下，你可以轻松查看 exec 事件的详细信息，并与伪终端内的进程进行交互。

跟踪 setuid 二进制文件

使用 root 权限，你还可以跟踪 setuid 二进制文件并了解它们的工作原理。 但请注意，这与 seccomp-bpf 优化不兼容，因此性能会大大降低。

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

也可以进行嵌套的 setuid 二进制文件跟踪：一个实际用例是跟踪 extra-x86_64-build（Arch Linux 的需要 sudo 的构建工具）：

在这个实际例子中，我们可以很容易看到 _FORTIFY_SOURCE 从 2 重新定义为 3，这导致了编译器错误。

将 tracexec 用作调试器启动器

tracexec 还可以用作调试器启动器，使程序调试变得更容易。例如，调试由 shell/python 脚本执行的程序（可能使用管道作为程序的标准输入输出）并不简单或方便。以下视频展示了如何使用 tracexec 启动 gdb 来调试由 shell 脚本通过管道连接的两个简单程序。

https://github.com/kxxt/tracexec/assets/18085551/72c755a5-0f2f-4bf9-beb9-98c8d6b5e5fd

请阅读 gdb-launcher 示例以获取更多详情。

日志模式

在日志模式下，默认情况下，tracexec 会打印文件名、argv 以及环境变量和文件描述符的差异。

示例：tracexec log -- bash（在交互式 bash shell 中）

使用 --show-cmdline 重构命令行

$ tracexec log --show-cmdline -- <command>
# 示例：
$ tracexec log --show-cmdline -- firefox

尝试在重构的命令行中重现标准输入输出

可以使用 --stdio-in-cmdline 和 --fd-in-cmdline 来（希望能）重现进程使用的标准输入输出。

但请注意，当涉及管道、套接字等时，结果可能不准确。

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

使用 --show-interpreter 显示 shebang 指示的解释器

并使用 --show-cwd 显示当前工作目录。

$ tracexec log --show-interpreter --show-cwd -- <command>
# 示例：运行 Arch Linux makepkg
$ tracexec log --show-interpreter --show-cwd -- makepkg -f

安装

从源码安装

通过 cargo：

cargo install tracexec --bin tracexec

Arch Linux 用户也可以通过官方仓库使用 pacman -S tracexec 安装。

二进制文件

你可以从发布页面下载二进制文件

使用方法

通用 CLI 帮助：

execve{,at} 和执行前行为的跟踪器，调试器启动器。

用法: tracexec [选项] <命令>

命令:
  log                   以日志模式运行 tracexec
  tui                   以 TUI 模式运行 tracexec，默认情况下 stdin/out/err 重定向到 /dev/null
  generate-completions  为 tracexec 生成 shell 补全
  collect               收集 exec 事件并导出
  help                  打印此消息或给定子命令的帮助

选项:
      --color <COLOR>      控制是否启用彩色输出。此标志对 TUI 模式无效。[默认: auto] [可能的值: auto, always, never]
  -C, --cwd <CWD>          在执行任何操作之前将当前目录更改为此路径
  -P, --profile <PROFILE>  从此路径加载配置文件
      --no-profile         不加载配置文件
  -u, --user <USER>        以指定用户身份运行。此选项仅在以 root 身份运行 tracexec 时可用
  -h, --help               打印帮助
  -V, --version            打印版本

TUI 模式：

以 TUI 模式运行 tracexec，默认情况下 stdin/out/err 重定向到 /dev/null

用法: tracexec tui [选项] -- <CMD>...

参数:
  <CMD>...  要执行的命令

选项:
      --seccomp-bpf <SECCOMP_BPF>
          控制是否启用 seccomp-bpf 优化，这可以大大提高性能 [默认: auto] [可能的值: auto, on, off]
      --successful-only
          仅显示成功的调用
      --fd-in-cmdline
          [实验性] 尝试在命令行中重现文件描述符。如果涉及管道、套接字等，可能会导致无法执行的命令行。
      --stdio-in-cmdline
          [实验性] 尝试在命令行中重现标准输入输出。如果涉及管道、套接字等，可能会导致无法执行的命令行。
      --resolve-proc-self-exe
          解析 /proc/self/exe 符号链接
      --no-resolve-proc-self-exe
          不解析 /proc/self/exe 符号链接
      --tracer-delay <TRACER_DELAY>
          轮询之间的延迟，以微秒为单位。启用 seccomp-bpf 时默认为 500，否则为 1。
      --show-all-events
          设置默认过滤器以显示所有事件。此选项可与 --filter-exclude 结合使用以排除一些不需要的事件。
      --filter <FILTER>
          设置事件的默认过滤器。[默认: warning,error,exec,tracee-exit]
      --filter-include <FILTER_INCLUDE>
          除默认过滤器外，还包括此处指定的事件。[默认: <空>]
      --filter-exclude <FILTER_EXCLUDE>
          从默认过滤器中排除此处指定的事件。[默认: <空>]
  -t, --tty
          分配一个伪终端并在 TUI 旁边显示
  -f, --follow
          保持事件列表滚动到底部
      --terminate-on-exit
          TUI 退出时终止，而不是等待根子进程退出
      --kill-on-exit
          TUI 退出时杀死进程，而不是等待根子进程退出
  -A, --active-pane <ACTIVE_PANE>
          设置 TUI 启动时使用的默认活动窗格 [可能的值: terminal, events]
  -L, --layout <LAYOUT>
          设置 TUI 启动时的布局 [可能的值: horizontal, vertical]
  -F, --frame-rate <FRAME_RATE>
          设置 TUI 的帧率（默认为 60）
  -D, --default-external-command <DEFAULT_EXTERNAL_COMMAND>
          设置使用"分离、停止并运行命令"功能时要运行的默认外部命令
  -b, --add-breakpoint <BREAKPOINTS>
          向跟踪器添加新的断点。此选项可多次使用。格式为 <syscall-stop>:<pattern-type>:<pattern>，其中 syscall-stop 可以是 sysenter 或 sysexit，pattern-type 可以是 argv-regex、in-filename 或 exact-filename。例如，sysexit:in-filename:/bash
  -h, --help
          打印帮助

日志模式：

以日志模式运行 tracexec

用法: tracexec log [选项] -- <CMD>...

参数:
  <CMD>...  要执行的命令
选项：
      --more-colors
          更多颜色
      --less-colors
          更少颜色
      --show-cmdline
          打印（希望能）重现执行内容的命令行。注意：目前不处理文件描述符。
      --no-show-cmdline
          不打印（希望能）重现执行内容的命令行。
      --show-interpreter
          尝试显示由shebang指示的脚本解释器
      --no-show-interpreter
          不显示由shebang指示的脚本解释器
      --foreground
          将终端前台进程组设置为被跟踪进程。此选项在交互使用tracexec时很有用。[默认]
      --no-foreground
          不将终端前台进程组设置为被跟踪进程
      --diff-fd
          与原始标准输入/输出/错误比较文件描述符
      --no-diff-fd
          不比较文件描述符
      --show-fd
          显示文件描述符
      --no-show-fd
          不显示文件描述符
      --diff-env
          与原始环境比较环境变量
      --no-diff-env
          不比较环境变量
      --show-env
          显示环境变量
      --no-show-env
          不显示环境变量
      --show-comm
          显示comm
      --no-show-comm
          不显示comm
      --show-argv
          显示argv
      --no-show-argv
          不显示argv
      --show-filename
          显示文件名
      --no-show-filename
          不显示文件名
      --show-cwd
          显示当前工作目录
      --no-show-cwd
          不显示当前工作目录
      --decode-errno
          解码errno值
      --no-decode-errno
          不解码errno值
      --seccomp-bpf <SECCOMP_BPF>
          控制是否启用seccomp-bpf优化，这可以大幅提高性能 [默认：auto] [可选值：auto, on, off]
      --successful-only
          仅显示成功的调用
      --fd-in-cmdline
          [实验性] 尝试在命令行中重现文件描述符。如果涉及管道、套接字等，可能会导致无法执行的命令行。
      --stdio-in-cmdline
          [实验性] 尝试在命令行中重现标准输入/输出。如果涉及管道、套接字等，可能会导致无法执行的命令行。
      --resolve-proc-self-exe
          解析/proc/self/exe符号链接
      --no-resolve-proc-self-exe
          不解析/proc/self/exe符号链接
      --tracer-delay <TRACER_DELAY>
          轮询间隔，以微秒为单位。启用seccomp-bpf时默认为500，否则为1。
      --show-all-events
          将默认过滤器设置为显示所有事件。此选项可与--filter-exclude结合使用以排除一些不需要的事件。
      --filter <FILTER>
          设置事件的默认过滤器。[默认：warning,error,exec,tracee-exit]
      --filter-include <FILTER_INCLUDE>
          除默认过滤器外，还包括此处指定的事件。[默认：<空>]
      --filter-exclude <FILTER_EXCLUDE>
          从默认过滤器中排除此处指定的事件。[默认：<空>]
  -o, --output <OUTPUT>
          输出，默认为stderr。单个连字符'-'表示stdout。
  -h, --help
          打印帮助信息

收集并导出数据：

收集exec事件并导出它们

用法：tracexec collect [选项] --format <格式> -- <命令>...

参数：
  <命令>...  要执行的命令

选项：
      --seccomp-bpf <SECCOMP_BPF>    控制是否启用seccomp-bpf优化，这可以大幅提高性能 [默认：auto] [可选值：auto, on, off]
      --successful-only              仅显示成功的调用
      --fd-in-cmdline                [实验性] 尝试在命令行中重现文件描述符。如果涉及管道、套接字等，可能会导致无法执行的命令行。
      --stdio-in-cmdline             [实验性] 尝试在命令行中重现标准输入/输出。如果涉及管道、套接字等，可能会导致无法执行的命令行。
      --resolve-proc-self-exe        解析/proc/self/exe符号链接
      --no-resolve-proc-self-exe     不解析/proc/self/exe符号链接
      --tracer-delay <TRACER_DELAY>  轮询间隔，以微秒为单位。启用seccomp-bpf时默认为500，否则为1。
  -F, --format <格式>                导出exec事件的格式 [可选值：json-stream, json]
  -p, --pretty                       如果支持，美化输出
  -o, --output <OUTPUT>              输出，默认为stderr。单个连字符'-'表示stdout。
      --foreground                   将终端前台进程组设置为被跟踪进程。此选项在交互使用tracexec时很有用。[默认]
      --no-foreground                不将终端前台进程组设置为被跟踪进程
  -h, --help                         打印帮助信息

配置文件

`tracexec`可以通过配置文件进行配置。配置文件是一个toml文件，可用于设置默认选项。

配置文件应放置在`$XDG_CONFIG_HOME/tracexec/`或`$HOME/.config/tracexec/`目录下，命名为`config.toml`。

配置文件模板可以在 https://github.com/kxxt/tracexec/blob/main/config.toml 找到。

请注意，配置文件格式尚不稳定，未来可能会发生变化。升级tracexec时可能需要更新配置文件。

已知问题

- 非UTF-8字符串以有损方式转换为UTF-8，这意味着输出可能不准确。
- 输出格式尚不稳定，未来可能会发生变化。
- 测试覆盖率不够充分。
- 伪终端无法传递某些按键组合和终端功能。

起源

这个项目源于跟踪程序执行的需求。

最初我只是简单地使用`strace -Y -f -qqq -s99999 -e trace=execve,execveat <command>`。

但输出仍然过于冗长，所以我创建了这个项目。

致谢

本项目受到[strace](https://strace.io/)和[lurk](https://github.com/JakWai01/lurk)的启发。