rootpilot-ssh-diagnose

rootpilot-ssh-diagnose

これは、RootPilotをオープンソース化し、お好みのLLMと組み合わせて使えるバージョンです。フル製品には、較正済みの診断（標準的な障害シナリオ29件で89.7％、正常なホストで誤警報ゼロ）、アラートをトリガーとする自動診断、履歴、複数ホスト管理が追加されます → rootpilotx.com · デプロイ用リポジトリ：rootpilot-release

Claude DesktopやClaude Code、ご自身で用意したクライアントなど、あらゆるMCPクライアントから、SSH経由でサーバーの読み取り専用診断情報を安全に収集できるMCPサーバーです。読み取り専用コマンドの固定ホワイトリストから証拠を収集し、推論はモデルが行います。サーバーはホワイトリスト外のコマンドを実行せず、ホストに変更を加えることもありません。

理由

サーバーに問題が起きると、SSHでログインして、df -h、docker ps、dmesg | grep -i oom、free -mといった同じ20個ほどのコマンドを実行し、出力を目で確認することになります。このサーバーを使うと、それを会話形式で行えます。LLMが必要な証拠だけを要求し、秘密情報を伏せた構造化出力を受け取って、根本原因を推論します。主導権はあなたにあります。SSHで自分のホストに接続する以外、情報があなたのマシンから外部に送られることはありません。

セキュリティモデル（最初にお読みください）

• 読み取り専用のホワイトリスト。 組み込みコマンドは全部で38個あり（get_whitelistですべて確認できます）、任意のコマンドを実行するツールはありません。確認プロンプトを付けた場合でも同様です。どのコマンドも状態の確認のみを行います。
• 注入可能な値はコンテナ名のみで、コマンドに使われる前に^[a-zA-Z0-9_.-]+$で検証されます。web; rm -rf /はエスケープされるのではなく、拒否されます。
• モデルに届く前に、出力から秘密情報を伏せます。 KEY=value形式の秘密情報、Bearer／Basicトークン、sk-／ghp_／AKIA…形式のキー、PEM秘密鍵ブロック、URLに埋め込まれた認証情報が対象です。docker inspectの環境変数値も伏せられます。
• コマンドごとのタイムアウト（15秒）と出力の切り詰めにより、処理の停止や出力の氾濫を防ぎます。
• 認証情報はローカルに保持されます。 ホスト定義は自分で管理するファイルに保存され、パスワードがログに記録されることはありません。

30秒でセットアップ

MCPクライアントにサーバーを追加します。Claude Desktopの場合（claude_desktop_config.json）：

{
  "mcpServers": {
    "rootpilot-ssh-diagnose": {
      "command": "npx",
      "args": ["-y", "@rootpilot/mcp-ssh-diagnose"],
      "env": {
        "RP_HOSTS": "/Users/me/.rootpilot-mcp/hosts.json"
      }
    }
  }
}

次に、hosts.jsonを作成します（hosts.example.jsonを参照）。

[
  { "name": "prod-1", "host": "1.2.3.4", "port": 22, "user": "rootpilot",
    "auth": { "type": "key", "keyPath": "~/.ssh/rootpilot_key" } },
  { "name": "prod-2", "host": "10.0.0.5", "user": "ops",
    "auth": { "type": "password", "password": "..." } }
]

クライアントを再起動します。「prod-1を診断して」と尋ねてください（またはdiagnose-hostプロンプトを実行します）。

最小権限のアカウントを使用してください。 rootを使い回すのではなく、診断専用の読み取り専用SSHユーザーを作成してください。コマンドは状態を読み取るだけですが、アカウントにもその権限を反映させてください。

ツール

ツール	引数	動作
list_hosts	probe?	設定済みのホストを一覧表示します。probeを指定すると、SSHの接続可能性もテストします
get_whitelist	—	実行可能なコマンドをあなたとモデルが正確に監査できるよう、38個すべてのコマンド（キー、目的、テンプレート）を返します
collect	host、keys[]（≤8）、container?	指定したホワイトリスト内のコマンドを実行し、秘密情報を伏せて切り詰めた出力を返します
collect_base	host	基本概要（docker_ps、df、df_inode、free、uptime、dmesg_oom、docker_daemon）を取得するショートカットです
container_deep_dive	host、container	1つのコンテナに対して、docker_logs、docker_inspect（秘密情報を伏せます）、container_state、docker_statsを取得するショートカットです

2つのプロンプトが標準で用意されています。diagnose-host（証拠を重視した根本原因の診断手順）と**health-check**（簡易チェック）です。

設定

環境変数	デフォルト	目的
RP_HOSTS	—	hosts.jsonへのパス（必須）
RP_PROBE_URL	https://cloudflare.com	外部接続／DNSのプローブ先
RP_NO_PROMO	—	1に設定すると、フル製品への案内を1行表示する機能を無効にします

仕組み

  your MCP client (the LLM)
        │  "collect df, docker_ps, dmesg_oom from prod-1"
        ▼
  rootpilot-ssh-diagnose  ──ssh──▶  your server
        │  renders a whitelisted template, runs it read-only,
        │  redacts secrets, truncates, returns structured output
        ▼
  the LLM reasons about root cause from the evidence

このサーバーは意図的に、独自の分析を一切行いません。組み込みの LLM 呼び出しも、複数ラウンドにわたるオーケストレーションもありません。この境界こそが重要です。シンプルで監査可能な証拠収集ツールです。症状に応じてどの証拠を収集するかを判断し、追加のラウンドを重ねながら障害シナリオライブラリと照合して評価する、調整された診断は、完全版の RootPilot 製品が担います。

FAQ

サーバーに変更を加えることはありますか？ いいえ。すべてのコマンドは読み取り専用で、任意のコマンドを実行するツールもありません。ホワイトリスト全体は get_whitelist で確認できます。

データはどこに送られますか？ このサーバー（お使いのマシン上で実行）とホスト間の SSH 通信以外には送られません。コマンドの出力は MCP クライアントのモデルに渡されます。テレメトリーはありません。

どの LLM を使用しますか？ このサーバー独自の LLM はありません。お好きなものをご用意ください。推論は MCP クライアントが実行するモデルが行います。

Windows サーバーや踏み台ホストを管理できますか？ v1 では対応していません。直接 SSH 接続できる Linux ホストを対象としています。

RootPilot との違いは何ですか？ このツールは証拠を収集し、あなた（またはモデル）がその都度解釈します。RootPilot には、調整された診断、アラートを契機とする自動診断、ホストごとの履歴（「カルテ」）、複数ホストの管理機能が追加されています。rootpilotx.com をご覧ください。

開発

npm install
npm run build      # compile to dist/
npm test           # whitelist / injection / redaction / timeout tests
npm run typecheck

ライセンス

MIT — LICENSE をご覧ください。