MCP Ssh Orchestrator

🚀 MCP SSH Orchestrator

MCP SSH Orchestrator為AI助手提供零信任的SSH編排功能，可對Claude Desktop、Cursor等支持MCP的客戶端實施聲明式策略和可審計的訪問控制。藉助Docker和MCP工具，能在數分鐘內完成部署，並提供默認拒絕的訪問控制、IP白名單、主機密鑰驗證和全面的審計日誌記錄。

🚀 快速開始

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、文件刪除等。
• 網絡隔離：服務器無法訪問外部互聯網。
• 無權限提升：在容器中以非root用戶身份運行。
• 資源限制：CPU和內存上限可防止拒絕服務攻擊。

生產就緒的審計與安全

• 受OWASP LLM前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 進行解析以生成報告。

🔧 技術細節

深度防禦架構

第1層：傳輸安全    → 標準輸入輸出、容器隔離
第2層：網絡安全      → IP白名單、主機密鑰驗證  
第3層：策略安全        → 默認拒絕、模式匹配
第4層：應用程序安全  → 非root用戶執行、資源限制

阻止的操作

# 自動拒絕危險命令
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服務問題。
• CVE - 2025 - 6514：通過基於策略的驗證，緩解MCP服務器中的命令注入問題。
• 43%的MCP服務器 存在命令注入漏洞：採用零信任安全模型。

完整安全模型文檔 | 安全風險分析

📚 詳細文檔

完整文檔Wiki

📦 安裝指南

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應顯示已連接編排器。你可跳轉至 使用手冊 查看引導場景。

💻 使用示例

基礎用法

在實際使用中，可通過以下方式調用MCP SSH Orchestrator提供的工具。例如，查看所有可用服務器：

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

高級用法

在執行命令前先進行測試（幹運行模式）：

echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"ssh_plan","arguments":{"command": "uptime", "host": "your_host"}},"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

📄 許可證

本項目採用Apache 2.0許可證，詳情請參考 LICENSE。

🔗 相關鏈接

• GitHub倉庫 - 歡迎在GitHub上給我們加星！
• 問題跟蹤器 - 報告錯誤或請求功能。
• MCP規範 - 瞭解MCP。
• Docker MCP安全指南 - 安全最佳實踐。