graftcp：Linux 进程代理重定向工具

项目简介

graftcp 是一个运行在 Linux 上的命令行工具，它用 ptrace(2) 跟踪目标进程的 socket 系统调用，把该进程的 TCP 连接、UDP/53 DNS 查询以及可选的通用 UDP 流量重定向到 SOCKS5 或 HTTP 代理。

与 tsocks、proxychains、proxychains-ng 不同，graftcp 不依赖 LD_PRELOAD，因此静态链接的程序（例如大多数 Go 程序）同样可以被跟踪。

旧版 graftcp + graftcp-local 的双进程结构已经合并为单一命令：graftcp 是主入口，mgraftcp 作为兼容别名保留；不再有独立的本地守护进程，也不依赖 FIFO、/proc 扫描或 netlink 反查 socket。

主要功能

• 将任意进程的 TCP 连接重定向到 SOCKS5（支持 TCP 端点或 Unix socket 端点）或 HTTP 代理。
• 可选的 DNS 代理：把发往 UDP/53 的查询改走 DNS-over-TCP，并通过同一代理链路转发。
• 可选的通用 UDP 代理：通过 SOCKS5 UDP ASSOCIATE 或直连 UDP 转发。
• 黑白名单 IP 文件（-b / -w），精确控制哪些目标地址走代理。
• --select_proxy_mode 支持 auto、random、only_http_proxy、only_socks5、direct 等选路模式。
• 支持 --socks5_username / --socks5_password 认证，以及 -u 以指定用户身份运行命令。
• 支持配置文件，CLI 参数优先于配置文件。

安装与使用

构建需要 Go 和 C 工具链：

git clone https://github.com/hmgle/graftcp.git
cd graftcp
make
sudo make install

构建产物为 local/graftcp，同时生成兼容别名 local/mgraftcp。

常用示例：

./local/graftcp --socks5 127.0.0.1:1080 curl https://example.com
./local/graftcp --enable-dns --dns-server 1.1.1.1:53 curl https://example.com
./local/graftcp --http_proxy 127.0.0.1:8080 git clone https://github.com/hmgle/graftcp.git
./local/graftcp bash --rcfile <(echo 'PS1="(graftcp) $PS1"')

配置文件按以下顺序查找：--config 指定的文件、程序目录下的 graftcp.conf / mgraftcp.conf、$XDG_CONFIG_HOME 与 $HOME/.config 下的对应目录、/etc/graftcp/graftcp.conf 等。示例见仓库中的 example-graftcp.conf。配置键与命令行参数对应，例如 dns_proxy = true 等价于 --enable-dns，ignore_local = false 等价于 --not-ignore-local。

工作原理

1. graftcp 启动内嵌的本地监听器，并用 ptrace(2) 跟踪目标命令。
2. 对每次被拦截的 connect(2)，在进程内的路由表记录原始目标，并从 127.0.0.0/8 分配一个唯一的 loopback token IP。
3. 把被跟踪进程的目标地址改写成该 token IP 加上监听端口。
4. 监听器接受连接后，根据 token 还原原始目标，再按配置走 SOCKS5、HTTP 或直连。
5. 系统调用返回后，尽力恢复进程原有的 sockaddr 缓冲区内容。

注意事项

• 仅支持 Linux；macOS 不支持。
• ptrace(2) 权限限制依然适用，受阻时请检查 Yama 的 ptrace_scope、capabilities 或改用 root 运行。
• 在支持的内核上会自动安装 seccomp-BPF 过滤器，仅让 socket 相关系统调用陷入跟踪器，从而降低开销。
• 默认忽略本地目标，使用 --not-ignore-local 才能代理 loopback / 私有地址连接。
• DNS 代理与通用 UDP 代理默认关闭，分别用 --enable-dns 和 --enable-udp 开启；两者同时开启时 DNS 代理优先处理 UDP/53。
• HTTP 代理模式不支持通用 UDP；only_http_proxy 会拒绝通用 UDP 会话。
• 未配置任何代理时默认回退到 SOCKS5 127.0.0.1:1080。
• 在 Arch 上运行 graftcp yay 或 graftcp sudo ... 时，因子进程需要跟踪权限，可用 sudo graftcp sudo -u $USER yay，或给二进制授予 cap_sys_ptrace,cap_sys_admin 能力。
• IPv6 被简化为 IPv4-mapped loopback 路径，需要 IPV6_V6ONLY=1 的 socket 不在设计范围内。

---

本作品整理自 GitHub 开源项目 hmgle/graftcp，原作者 @hmgle，许可证 GPL-3.0。中文介绍由 AI 根据项目 README 整理，以原仓库为准。