MCP Ssh Orchestrator

🚀 MCP SSH Orchestrator

このプロジェクトは、AIアシスタントに対するゼロトラストのSSHオーケストレーションを提供します。Claude DesktopやCursorなどのMCP対応クライアントに対して、宣言的なポリシーと監査可能なアクセスを強制します。DockerとMCPツールを使用して数分で起動でき、デフォルトで拒否する制御と強化されたSSHキー管理を備えています。

🚀 クイックスタート

1. ローカル設定の準備（一度だけ）

# オプション: composeヘルパースクリプトですべてをブートストラップする
# （リポジトリのルートまたはターゲットの設定ディレクトリから実行）
./compose/setup.sh enduser

# または別途ダウンロードする
curl -fsSLO https://raw.githubusercontent.com/samerfarida/mcp-ssh-orchestrator/main/compose/setup.sh
chmod +x setup.sh
./setup.sh enduser

手動で設定する場合は、以下の手順に従ってください。

# 最新のリリースを取得する
docker pull ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3

# 設定、キー、シークレット用のディレクトリを作成する
mkdir -p ~/mcp-ssh/{config,keys,secrets}

# すぐに始められるようにサンプル設定をコピーする
cp examples/example-servers.yml ~/mcp-ssh/config/servers.yml
cp examples/example-credentials.yml ~/mcp-ssh/config/credentials.yml
cp examples/example-policy.yml ~/mcp-ssh/config/policy.yml

# SSHキーを追加する（あなたの秘密鍵ファイルに置き換える）
cp ~/.ssh/id_ed25519 ~/mcp-ssh/keys/
chmod 0400 ~/mcp-ssh/keys/id_ed25519

# （オプション）信頼できるホストを固定し、シークレットファイルを準備する
cp ~/.ssh/known_hosts ~/mcp-ssh/keys/known_hosts
cat > ~/mcp-ssh/secrets/prod_db_password.txt <<'EOF'
CHANGE-ME
EOF

2. オーケストレータコンテナを起動する

docker run -d --name mcp-ssh-orchestrator \
  -v ~/mcp-ssh/config:/app/config:ro \
  -v ~/mcp-ssh/keys:/app/keys:ro \
  -v ~/mcp-ssh/secrets:/app/secrets:ro \
  ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3

後でdocker start mcp-ssh-orchestratorで再起動します。使い捨てコンテナを好む場合は、代わりにdocker run -i --rm ...を使用してください。

3. MCPクライアントを接続する

• Cursor: ~/.cursor/mcp.jsonに追加します。

{
    "mcpServers": {
        "mcp-ssh-orchestrator": {
            "command": "docker",
            "args": ["start", "-a", "mcp-ssh-orchestrator"],
            "env": {"PYTHONUNBUFFERED": "1"}
        }
    }
}

• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.jsonを更新します。

{
    "mcpServers": {
        "ssh-orchestrator": {
            "command": "docker",
            "args": [
                "run", "-i", "--rm",
                "-v", "/Users/YOUR_USERNAME/mcp-ssh/config:/app/config:ro",
                "-v", "/Users/YOUR_USERNAME/mcp-ssh/keys:/app/keys:ro",
                "-v", "/Users/YOUR_USERNAME/mcp-ssh/secrets:/app/secrets:ro",
                "ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3"
            ]
        }
    }
}

（Windowsのパス: %APPDATA%\\Claude\\claude_desktop_config.json） より多くの例（Docker Desktop、マルチ環境、SDKの使用法）は、統合ガイドにあります。

4. 接続をテストする

# MCPサーバーを通じて構成されたホストをリストする
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"ssh_list_hosts","arguments":{}},"id":1}' | \
  docker run -i --rm \
    -v ~/mcp-ssh/config:/app/config:ro \
    -v ~/mcp-ssh/keys:/app/keys:ro \
    -v ~/mcp-ssh/secrets:/app/secrets:ro \
    ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3

Cursor/Claudeは、オーケストレータが接続されていることを表示するはずです。ガイド付きのシナリオについては、使用方法ブックにジャンプしてください。

✨ 主な機能

解決する問題

AIアシスタント（Claude、ChatGPTなど）がサーバーにアクセスできると、何をするか心配になることはよくあります。rm -rf /やデータベースの削除、ファイアウォールルールの変更などです。MCP SSH Orchestratorは、AIに対して、セキュリティポリシーが許可する場合にのみ、インフラストラクチャに対する管理可能で監査可能なアクセスを提供します。

重要性

ゼロトラストセキュリティモデル

• デフォルトで拒否: 明示的に許可されていない限り、何も実行されません。
• ネットワーク制御: IP許可リストにより、横方向の移動を防止します。
• コマンドホワイトリスト: 承認されたコマンドのみが実行できます。
• 包括的な監査トレイル: すべてのアクションがJSON形式でログに記録されます。

一般的な攻撃ベクトルの防止

• 危険なコマンドのブロック: rm -rf、dd、ファイルの削除など。
• ネットワーク分離: サーバーは外部インターネットにアクセスできません。
• 特権昇格の防止: コンテナ内で非ルートユーザーとして実行されます。
• リソース制限: CPUとメモリの上限により、DOS攻撃を防止します。

本番環境での監査とセキュリティ

• OWASP LLM Top 10対策: LLM07（不安全なプラグイン設計）、LLM08（過度の権限）、LLM01（プロンプトインジェクション）を軽減します。
• MITRE ATT&CK対応: T1071（アプリケーション層プロトコル）、T1659（コンテンツインジェクション）を防止します。
• 構造化されたJSON監査ログ: タイムスタンプ、ハッシュ、IPアドレスを含む完全な監査トレイル。
• フォレンジック対応: コマンドのハッシュ化、IP追跡、詳細なメタデータ。
• リアルタイム監視: 長時間実行されるタスクの進行状況ログ。

対象ユーザー

ホームラボ愛好者

• AIを使用して日常のサーバーメンテナンスを自動化します。
• Proxmox、TrueNAS、Dockerホストを安全に管理します。
• SSHセキュリティを損なうことなくトラブルシューティングの支援を受けます。

セキュリティエンジニア

• AIのインフラストラクチャへのアクセスを監査および制御します。
• ポリシーをコードとして実装して、ゼロトラスト原則を適用します。
• 構造化されたログによりコンプライアンス要件を満たします。

DevOpsチーム

• AIに日常のタスク（ログチェック、サービスの再起動、更新）を任せます。
• 会話型インターフェースを通じてサーバーのフリートを管理します。
• セキュリティ基準を維持しながら、手動作業を削減します。

プラットフォームエンジニア

• AIによるインフラストラクチャ管理を有効にします。
• 開発者に安全なセルフサービスアクセスを提供します。
• AIとインフラストラクチャの間のギャップを安全に埋めます。

実際の使用シナリオ

シナリオ1: ホームラボの自動化

あなたが言う: "Claude、ホームサーバーが遅いです。Proxmoxホストのディスク使用量を確認してくれますか？" 起こること:

• ポリシーチェック: そのホストではdf -hのみ許可されています。
• ネットワークチェック: ProxmoxのIPが許可リストに含まれています。
• コマンドが安全に実行されます。
• 監査ログに操作が記録されます。

シナリオ2: インシデント対応

あなたが言う: "すべてのWebサーバーのnginxログをエラーについて確認してください" 起こること:

• タグベースの実行により、すべてのWebサーバーでtail -f /var/log/nginx/error.logが実行されます。
• ネットワーク分離された実行（外部アクセスなし）。
• リアルタイムの進行状況ログにより、何が起こっているかがわかります。
• インシデント後のレビュー用の完全な監査トレイル。

シナリオ3: コンプライアンスと監査

セキュリティチームが知りたいこと: "誰がいつ何にアクセスしたか？" 起こること:

• JSON監査ログにより、すべてのアクションがタイムスタンプ付きで記録されます。
• コマンドのハッシュ化により、プライバシーが保護されながら、フォレンジックが可能になります。
• ネットワークコンプライアンスのためにIPアドレスが記録されます。
• jqで簡単に解析してレポートを作成できます。

📚 ドキュメント

💻 使用例

基本的な使用法

# ローカル設定の準備
./compose/setup.sh enduser

高度な使用法

# 手動での設定
docker pull ghcr.io/samerfarida/mcp-ssh-orchestrator:0.3.3
mkdir -p ~/mcp-ssh/{config,keys,secrets}
cp examples/example-servers.yml ~/mcp-ssh/config/servers.yml
cp examples/example-credentials.yml ~/mcp-ssh/config/credentials.yml
cp examples/example-policy.yml ~/mcp-ssh/config/policy.yml
cp ~/.ssh/id_ed25519 ~/mcp-ssh/keys/
chmod 0400 ~/mcp-ssh/keys/id_ed25519
cp ~/.ssh/known_hosts ~/mcp-ssh/keys/known_hosts
cat > ~/mcp-ssh/secrets/prod_db_password.txt <<'EOF'
CHANGE-ME
EOF

🔧 技術詳細

深度防御アーキテクチャ

Layer 1: トランスポートセキュリティ    → stdio、コンテナ分離
Layer 2: ネットワークセキュリティ      → IP許可リスト、ホストキー検証  
Layer 3: ポリシーセキュリティ        → デフォルトで拒否、パターンマッチング
Layer 4: アプリケーションセキュリティ  → 非ルート実行、リソース制限

ブロックされるもの

# 危険なコマンドは自動的に拒否されます
deny_substrings:
  # 破壊的な操作
  - "rm -rf /"
  - ":(){ :|:& };:"
  - "mkfs "
  - "dd if=/dev/zero"
  - "shutdown -h"
  - "reboot"
  - "userdel "
  - "passwd "
  # 横方向の移動 / エグレスツール
  - "ssh "
  - "scp "
  - "rsync -e ssh"
  - "curl "
  - "wget "
  - "nc "
  - "nmap "
  - "telnet "
  - "kubectl "
  - "aws "
  - "gcloud "
  - "az "

# ネットワーク分離が強制されます
network:
  allow: ["10.0.0.0/8"]  # プライベートIPのみ
  deny: ["0.0.0.0/0"]     # パブリックインターネットへのアクセスは禁止

許可されるもの（例）

# 安全な読み取り専用コマンド
rules:
  - action: "allow"
    aliases:
      - "*"
    tags:
      - "observability"
    commands:
      - "uptime*"
      - "df -h*"
      - "free -m*"

  # ログ検査（安全）
  - action: "allow"
    aliases:
      - "*"
    tags:
      - "observability"
    commands:
      - "tail -n 200 /var/log/*"
      - "grep -n * /var/log/*"
      - "journalctl --no-pager -n 100 *"

  # サービス管理（制御された）
  - action: "allow"
    aliases:
      - "web-*"
      - "db-*"
    tags:
      - "production"
      - "critical-service"
    commands:
      - "systemctl restart nginx"
      - "systemctl status nginx"
      - "systemctl status postgresql"

実際の脅威からの保護

MCP SSH Orchestratorは、MCPエコシステムにおける既知の脆弱性に対処します。

• CVE-2025-49596: ローカルホストに公開されたMCPサービス → stdioのみのトランスポートにより軽減
• CVE-2025-6514: MCPサーバーにおけるコマンドインジェクション → ポリシーベースの検証により軽減
• 43%のMCPサーバーにコマンドインジェクションの欠陥があります → ゼロトラストセキュリティモデル

完全なセキュリティモデルドキュメント | セキュリティリスク分析

AIでできること（MCPツール）

AIアシスタントは、組み込みのセキュリティを備えた13の強力なツールを利用できます。

探索と計画

• ssh_list_hosts - 利用可能なすべてのサーバーを表示
• ssh_describe_host - ホストの詳細とタグを取得
• ssh_plan - 実行前にコマンドをテスト（ドライランモード）

実行

• ssh_run - 1つのサーバーで単一のコマンドを実行
• ssh_run_on_tag - 複数のサーバーでコマンドを実行（例: すべての"web"サーバー）
• ssh_run_async - 長時間実行されるタスクをバックグラウンドで開始

監視と制御

• ssh_get_task_status - 非同期タスクの進行状況を確認
• ssh_get_task_output - 出力をリアルタイムでストリーミング
• ssh_get_task_result - 完了したときに最終結果を取得
• ssh_cancel - 実行中のタスクを安全に停止

管理

• ssh_reload_config - 再起動せずにホスト/資格情報を更新
• ssh_ping - ホストへの接続を確認

例付きの完全なツールリファレンス

もっと学ぶ

主な差別化要素

• 本番環境に対応したセキュリティ: OpenSSF Scorecard 7.5以上のスコア
• ゼロトラストアーキテクチャ: デフォルトで拒否、例外で許可
• OWASP LLM Top 10対策: 不安全なプラグイン設計、過度の権限、プロンプトインジェクションを軽減
• MITRE ATT&CK対応: コンテンツインジェクションと不正なプロトコルの使用を防止
• セキュリティに重点を置いた設計: 実際のCVE（CVE-2025-49596、CVE-2025-6514）に対するセキュリティ第一の原則に基づいて構築
• 簡単な統合: Claude、ChatGPT、およびすべてのMCPクライアントと互換性があります
• オープンソース: Apache 2.0ライセンス、コミュニティ主導

ユーザーの声

"やっと、ClaudeにProxmoxクラスタを管理させても心配する必要がなくなりました！" - ホームラボ管理者

"これこそが、インフラストラクチャ即コードが本当にあるべき姿です。AIアクセスに対する宣言的なセキュリティです。" - プラットフォームエンジニア

"構造化された監査ログにより、インシデント対応が格段に楽になりました。" - セキュリティエンジニア

コントリビュート

コントリビューションを歓迎します！コントリビュートガイドを参照して、以下の内容を確認してください。

• 開発環境のセットアップ
• 行動規範
• プルリクエストの提出方法
• アーキテクチャの決定

📄 ライセンス

Apache 2.0 - 詳細はLICENSEを参照してください。

リンク

• GitHubリポジトリ - GitHubでスターをつけてください！
• イシュートラッカー - バグを報告または機能をリクエスト
• MCP仕様 - MCPについて学ぶ
• Docker MCPセキュリティガイド - セキュリティのベストプラクティス