sudo-proxy

sudo-proxy

エージェントが特権を要する変更コマンドを実行できる MCP サーバーです。 ローカルでも SSH 経由でも、実行するたびに人間によるキー入力が必要で、 認証情報が保存されることはありません。

AI エージェント連携用の MCP サーバーを備えた、特権コマンド実行プロキシです。Unix ソケット経由でリクエストを受け取り、人間による承認を求める1 キー入力の 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 プロンプトで承認を求め（1 キー入力）、その後 sudo が権限を昇格します。パスワードプロンプトは同じターミナルに表示されます。このフローはローカルホストとリモートホストで同一です。非特権モードでは、同じ Y/N ゲートを通して、現在のユーザーとしてコマンドを直接実行します。詳しくはdocs/usage.mdをご覧ください。

Bash ツールを使うだけではだめなのですか？

	Bash ツール	sudo-proxy MCP
権限昇格	不可	人間の承認を得た sudo
人間による確認	なし — 即時実行	すべてのコマンドで TUI の Y/N ゲート（特権・非特権を問わず）
タイムアウト	最大 10 分、ユーザープロンプトなし	TUI プロンプトは 60 秒、全体のタイムアウトは設定可能
リモートホスト	非対応	リモートターミナル上の TUI を使う SSH トンネル
環境	シェル環境変数を継承	サニタイズ済みの許可リストのみ
監査証跡	なし	サーバーが各リクエストをログに記録（-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 が行うこと：

• コマンドごとの人間による承認 — 特権の有無にかかわらず、すべてのコマンドに対して、キーを1回押すだけの Y/N TUI ゲートを設け、回避する方法はありません。
• sudo による実際の権限昇格 — パッケージのインストール、システムファイルの編集、サービスの管理が可能です。読み取り専用の診断に限られません。
• ローカルとリモートで同じフロー — コマンドをこのマシンで実行する場合も、SSH トンネル経由でリモートホスト上で実行する場合も、同じ承認 TUI を使用します。
• シークレットを保存しない — sudo パスワードはターミナルにその場で入力します。キャッシュ、保存時の暗号化、ディスクへの書き込みは一切行いません。
• 明示的な argv — コマンドはシェル文字列の補間なしで、実行時とまったく同じ形で渡され、表示されます。
• サニタイズされた環境 — 継承したシェル環境ではなく、固定の許可リストを使用します。
• 監査証跡 — 各リクエストはサーバーによって記録されます（-v）。
• --dangerously-skip-permissions でも動作 — エージェント自身の権限プロンプトが無効でも、人間によるゲートは機能します。

sudo-proxy が意図的に行わないこと：

• 認証情報を保存・管理しない — パスワードキャッシュでも、シークレットマネージャーでもありません。
• 無人実行を行わない — 自動承認モードはありません。人間が各コマンドを承認しなければ、コマンドは実行されません。
• サンドボックスではない — 隔離したり、実際とは異なる環境を装ったりするのではなく、実際の権限を付与します。
• ポリシーエンジンや ACL ではない — キーを押して承認する人間がポリシーです。作成・維持するルールはありません。
• 読み取り専用ではない — 安全な診断コマンドのホワイトリストに制限されません。
• ホスト型サービスではない — ご自身のマシン上で動作し、コマンドがサードパーティのリレーを経由することはありません。
• 汎用のリモートシェルではない — 永続的な対話型セッション、SFTP ブラウザー、フリートマネージャーはありません。承認付きの単発コマンドのみを実行します。

クイックスタート

バイナリをインストールします（Rust ツールチェーンが必要です。ビルド済みの静的バイナリはリリースにあります）。

cargo install sudo-proxy

または、cargo binstall を使って、コンパイルせずにビルド済みの静的バイナリを取得します。

cargo binstall sudo-proxy

cargo binstall は GitHub からリリースの tarball をダウンロードし、インストール前に 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 はターミナルのベルを鳴らし、質問行を点滅させます。これにより、デーモンのターミナルがフォーカスされていない、または画面外にある場合でも、リクエストを見落としません。ベルはターミナル独自の視覚ベル／緊急通知の設定（ビープ音、タスクバー／Dock の点滅、またはその両方）に従います。どちらの通知もデフォルトで有効です。ベルを消音するには SUDO_PROXY_NO_BELL を設定し、点滅を停止するには SUDO_PROXY_NO_BLINK を設定してください（NO_COLOR と同じオプトアウト方式です）。

MCP レジストリ

公式の MCP Registry に、 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 トンネル、エージェント転送
• 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、Rung 4）および ProVerif SSH チャネルモデル（Rung 4）。Kani による有界証明は src/proofs.rs にあります（Rung 3）
• docs/pkexec.md — --pkexec モードと polkit 認証キャッシュ（非推奨）
• docs/architecture.md — ソースの構成と実装状況
• docs/comparison.md — sudo-proxy と他のツールとの関係

AI 支援による開発

sudo-proxy は、Claude Code を使用した多大な AI 支援のもとで開発されました。AI が実質的に貢献したコミットには、具体的なモデル名を記した Co-Authored-By トレーラーが付いています。すべての設計上の決定、脅威モデリング、およびコミットされたすべての変更の最終形は、人間のメンテナーがレビューして承認しており、そのメンテナーがコードベースに対する責任を負っています。

この開示は、ソフトウェア開発における生成 AI の関与について透明性を確保する、業界で広がりつつある慣行に沿って行っています。これは、このプロジェクトが「AI 生成」であるという表明ではありません。このツールが実行時に強制するヒューマン・イン・ザ・ループの原則は、開発時にも適用されています。

ライセンス

MIT