sudo-proxy

sudo-proxy

一个 MCP 服务，可让 Agent 执行具有特权的修改性命令—— 在本地或通过 SSH 执行——每条命令都必须由人工按键确认， 且永远不会存储任何凭据。

用于 AI Agent 集成的特权命令执行代理，带有 MCP 服务。 它通过 Unix 套接字接收请求，显示只需按一次键的 TUI 提示 以供人工批准，然后通过 sudo 提权。在 Claude Code 或任何 MCP 客户端中 配置 sudo-proxy-mcp，模型便可运行特权命令——每条命令 都需获得明确的人工批准。

⚠️ 尚未经过独立审计。 本仓库中的安全保障说明 均由项目自行编写。安全审查人员：REVIEWING.md 是一份 15 分钟 的入门指南，介绍可证伪的声明、信任边界，以及我们没有 安全保障的部分。报告问题：SECURITY.md。

架构

AI model ──► sudo-proxy-mcp ──► Unix socket ──► sudo-proxy ──► TUI Y/N ──► sudo
             (MCP server)         │
                                  │
                            local socket, or SSH tunnel
                        (start_server spawns sudo-proxy --host
                         which sets up the tunnel and remote
                         server)

TUI 提示会请求批准（按一次键即可），然后由 sudo 处理 权限提升。密码提示会显示在同一终端中。本地和远程主机的 流程完全相同。非特权模式会直接以当前用户身份运行命令，但仍受 同一个 Y/N 确认关卡控制——参见 docs/usage.md。

为什么不直接使用 Bash 工具？

	Bash 工具	sudo-proxy MCP
权限提升	不支持	通过 sudo 提权并需人工批准
人工审查	无——立即执行	每条命令都需通过 TUI 的 Y/N 确认关卡（特权和非特权命令均如此）
超时	最长 10 分钟，无用户提示	TUI 提示 60 秒 + 可配置的总超时时间
远程主机	不支持	SSH 隧道，并在远程终端显示 TUI
环境	继承 shell 环境变量	仅使用经过清理的允许列表
审计记录	无	服务会记录每个请求（使用 -v）

当模型需要安装软件包、编辑系统文件、管理服务或运行其他命令时， sudo-proxy 可以填补这一空缺——始终让人工参与其中，即使 Claude Code 以 --dangerously-skip-permissions 运行也是如此。

它刻意不用于以比 Bash 工具更少审查的方式运行非特权命令：针对本地 机器的非特权命令会被拒绝并交由 Bash 工具处理（Bash 工具已经应用 你的权限规则），而 127.0.0.1 之类的环回地址别名也无法绕过这一限制。 sudo-proxy 负责权限提升和远程主机上的命令；在远程主机上， 非特权命令也受同样的确认关卡控制。只有在你有意于 hosts.json 中将主机标记为 符合条件，并且每个会话确认一次后，才会放宽逐条命令的确认要求 （此授权永远不会持久保存）。参见 REVIEWING.md 中的不变量 G7。

关于它与 mcp-firewall、沙箱、polkit、doas 及其他相关工具的关系， 请参见 docs/comparison.md。

功能与非功能

sudo-proxy 的功能：

• 逐条命令由人工批准 — 每条命令执行前都会经过单键 Y/N TUI 审批，无论命令是否需要特权，且无法绕过。
• 真正的权限提升，通过 sudo 实现 — 可安装软件包、编辑系统文件、管理服务；不限于只读诊断。
• 本地和远程使用同一流程 — 无论命令在本机运行，还是通过 SSH 隧道在远程主机上运行，都会显示相同的审批 TUI。
• 不存储任何机密 — sudo 密码需在终端中即时输入；不会缓存、静态加密或写入磁盘。
• 明确的 argv — 命令会按原样传递和显示，不进行 shell 字符串插值。
• 经过净化的环境 — 使用固定的允许列表，而非继承 shell 环境。
• 审计记录 — 服务端会记录每项请求（-v）。
• 支持 --dangerously-skip-permissions — 即使 Agent 自身的权限提示已禁用，人工审批关卡仍会生效。

sudo-proxy 有意不提供的功能：

• 不存储或管理凭据 — 它不是密码缓存或机密管理器。
• 不支持无人值守执行 — 没有自动批准模式；每条命令都必须经人工批准，否则不会运行。
• 不是沙箱 — 它授予真实权限，而非隔离权限或伪造权限。
• 不是策略引擎或 ACL — 按键批准的人工就是策略；无需编写或维护规则。
• 不只读 — 不限于安全诊断命令的允许列表。
• 不提供托管服务 — 它在你自己的机器上运行；命令绝不会经由第三方中继传输。
• 不是通用远程 shell — 不支持持久交互式会话、SFTP 浏览器或集群管理器；只支持经过审批的一次性命令。

快速开始

安装二进制文件（需要 Rust 工具链；预编译的静态二进制文件见 Releases）：

cargo install sudo-proxy

或者通过 cargo binstall 获取预编译的静态二进制文件，无需编译：

cargo binstall sudo-proxy

cargo binstall 会从 GitHub 下载发布压缩包，并在安装前验证其 minisign 签名（公钥 RWT7gwtBU0v4puI76u0oYwMAT9nmYwGimSOnqJJ+kHExsjTDQj1eZkMW，密钥 ID A6F84B53410B83FB）；如果签名缺失或无效，就会中止安装。如果你更愿意从源代码构建，请使用 cargo install。

将 MCP 客户端指向此服务端 — 添加到项目的 .mcp.json 或 ~/.claude/claude_desktop_config.json：

{
  "mcpServers": {
    "sudo-proxy": {
      "command": "sudo-proxy-mcp"
    }
  }
}

安装为 Claude Code 插件

该仓库也是一个 Claude Code 插件，并提供自己的市场。无需手动编辑 .mcp.json：

/plugin marketplace add tarides/sudo-proxy
/plugin install sudo-proxy@tarides

此插件会注册 sudo-proxy MCP 服务，并附带一项技能，指导模型仅在处理需要特权或远程操作时使用 sudo-proxy、执行前先启动服务，并为每条命令编写清晰的描述，方便判断是否批准。它不会安装 sudo-proxy-mcp 二进制文件 — 该文件必须已在你的 PATH 中（参见上文的 cargo install / cargo binstall 步骤）。一个核心目的就是征求明确人工同意的工具，不应悄无声息地自行安装。

运行命令

然后，模型会启动服务端（打开一个显示审批 TUI 的终端），并通过它运行命令：

start_server()
execute({"argv": ["apt", "install", "nginx"], "description": "Install nginx"})

每次 execute 都会在 TUI 中显示完整命令；按 y 批准，按 N（默认选项）拒绝。对于远程主机，在 start_server 和 execute 中传入 host。

出现提示时，TUI 会鸣响终端铃声并闪烁问题行，以免在守护进程的终端失去焦点或显示在屏幕之外时错过请求。铃声会遵循终端自身的视觉铃声／紧急提示设置（发出提示音、任务栏／程序坞闪烁，或两者兼有）。默认情况下，这两种提示都会启用；设置 SUDO_PROXY_NO_BELL 可关闭铃声，设置 SUDO_PROXY_NO_BLINK 可停止闪烁（与 NO_COLOR 相同的选择退出方式）。

MCP 注册表

已列入官方 MCP 注册表， 名称为 mcp-name: io.github.tarides/sudo-proxy。

文档

• docs/install.md — 安装变体、远程部署、从源代码构建
• docs/mcp.md — MCP 工具（start_server、execute、status、stop_server、update_host）、配置、已知主机
• docs/usage.md — CLI 标志、非特权模式、SSH 隧道、Agent 转发
• docs/protocol.md — Unix 套接字上的 JSON 行协议
• docs/security.md — 安全模型；docs/security-audit.md — 特定时间点的审计；docs/threat-model.md — STRIDE + 攻击树；docs/formalisation-roadmap.md — 分阶段保障计划；docs/assurance-case.md — GSN 论证
• proofs/ — 机器验证模型：TLA+/PlusCal 审批状态机（TLC，第 4 级）和 ProVerif SSH 通道模型（第 4 级）；Kani 有界证明位于 src/proofs.rs（第 3 级）
• docs/pkexec.md — --pkexec 模式和 polkit 身份验证缓存（不推荐）
• docs/architecture.md — 源代码布局和实现状态
• docs/comparison.md — sudo-proxy 与其他工具的关系

AI 辅助开发

sudo-proxy 在开发过程中大量借助了 AI，使用了 Claude Code。AI 对提交有实质性贡献的提交， 会附带注明具体模型的 Co-Authored-By 署名行。所有设计决策、威胁建模以及 每项已提交更改的最终形式，都由人工维护者审查并批准；维护者对代码库负责。

本声明遵循软件开发中关于生成式 AI 参与情况透明度的新兴行业惯例。 这并不表示该项目是“AI 生成”的：该工具在运行时强制执行的人机协作原则， 同样也是构建该工具所遵循的原则。

许可证

MIT