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安全指南 - 安全最佳实践。