MCP SSH Orchestrator
Zero-Trust SSH Orchestration for AI Assistants
Enforce declarative policy-as-code and audited access for Claude Desktop, Cursor, and any MCP-aware client.
Launch in minutes with Docker + MCP tooling, deny-by-default controls, and hardened SSH key management.
这解决了什么问题?
想象一下: 你的AI助手(Claude、ChatGPT等)可以访问你的服务器,但你害怕它会做什么。 rm -rf /?删除数据库?更改防火墙规则?
现在想象一下: 你的人工智能已经控制了对你的基础设施的可审计访问。它可以检查日志、重启服务和管理您的车队, 但前提是你的安全策略允许。
这正是MCP SSH Orchestrator所提供的: 人工智能驱动的服务器管理的强大功能,包括默认拒绝访问控制、IP分配列表、主机密钥验证和由声明性YAML策略作为代码支持的全面审计日志记录(config/servers.yml, config/credentials.yml, config/policy.yml).
为何这很重要
零信任安全模型
- 默认情况下拒绝:除非明确允许,否则不会运行任何内容
- 网络控制:IP allowlists防止横向移动
- 命令白名单:只有批准的命令才能执行
- 声明性策略作为代码:版本化的YAML文件定义了主机、凭据和允许的命令
- 全面的审计跟踪:每个操作都以JSON格式记录
防止常见的攻击媒介
- 危险命令被阻止:
rm -rf,dd,文件删除 - 网络隔离:服务器无法访问外部互联网
- 无特权升级:在容器中以非root身份运行
- 资源限制:CPU和内存上限可防止DOS
生产就绪审计和安全
- OWASP LLM Top 10保护:缓解LLM07(不安全的插件设计)、LLM08(过度代理)、LLU01(快速注入)
- MITRE ATT&CK对齐:防止T1071(应用层协议)、T1659(内容注入)
- 结构化JSON审计日志:使用时间戳、哈希值和IP地址完成审计跟踪
- 法医准备就绪:命令哈希、IP跟踪、详细元数据
- 实时监控:长时间运行的任务的进度日志
这是给谁的?
Homelab爱好者
- 使用AI自动化日常服务器维护
- 安全管理Proxmox、TrueNAS、Docker主机
- 在不失去SSH安全性的情况下获取故障排除帮助
安全工程师
- 审计和控制人工智能对基础设施的访问
- 使用声明性策略作为代码配置实现零信任原则
- 通过结构化日志记录满足合规要求
DevOps团队
- 让AI处理日常任务:日志检查、服务重启、更新
- 通过对话式界面管理服务器组
- 在保持安全标准的同时减少人工劳动
平台工程师
- 实现基于人工智能的基础设施管理
- 为开发人员提供安全的自助服务访问
- 安全地弥合人工智能和基础设施之间的差距
真实世界用例
场景1:家庭实验室自动化(家庭实验室爱好者)
你说: 克劳德,我的Proxmox主机运行缓慢。你能检查我所有虚拟机上的磁盘使用情况和内存吗
发生了什么
- 政策允许
df -h和free -m在Proxmox主机上 - 网络检查:私有IP分配列表允许访问
- 基于标记的执行检查所有标记的主机
proxmox - 命令安全执行,无破坏性操作
- 存储在JSON日志中的完整审计跟踪
场景2:事件响应(DevOps团队)
你说: “我们看到500个错误。请检查所有生产web服务器上的nginx日志,并向我显示最后100行错误。”
发生了什么
- 基于标签的执行:
tail -n 100 /var/log/nginx/error.log运行在所有web-prod服务器 - 强制网络隔离:不允许外部API调用或出口
- 通过MCP上下文事件实时传输进度日志
- 结构化输出聚合结果以实现快速分类
- 完整的审计跟踪,带有事件后审查的时间戳
场景3:全机队维护(平台工程师)
你说: 更新所有临时服务器上的系统包,但在运行升级之前,请先向我展示会发生什么变化
发生了什么
- 使用
ssh_plan预览apt list --upgradable穿过staging标记主机 - 查看模拟运行输出以查看待处理的更新
- 策略验证
apt update && apt upgrade -y允许在舞台上表演 - 基于标记的执行在所有临时服务器上并行运行升级
- 审计日志跟踪哪些服务器已更新以及何时更新
快速开始
1.准备本地配置(一次性)```bash
Optional: bootstrap everything with the compose helper script
(runs from the repo root or from your target config directory)
./compose/setup.sh enduser
Or download it separately
curl -fsSLO https://raw.githubusercontent.com/samerfarida/mcp-ssh-orchestrator/main/compose/setup.sh
chmod +x setup.sh
./setup.sh enduser
如果您更喜欢手动布局,请按照以下步骤操作。```bash
# Pull the latest release
docker pull ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
# Create directories for config, keys, and secrets
mkdir -p ~/mcp-ssh/{config,keys,secrets}
# Copy example configs to get started quickly
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
# Add your SSH key (replace with your private key file)
cp ~/.ssh/id_ed25519 ~/mcp-ssh/keys/
chmod 0400 ~/mcp-ssh/keys/id_ed25519
# (Optional) Pin trusted hosts and prepare secret files
cp ~/.ssh/known_hosts ~/mcp-ssh/keys/known_hosts
# Option 1: Individual secret files (Docker secrets compatible)
cat > ~/mcp-ssh/secrets/prod_db_password.txt <<'EOF'
CHANGE-ME
EOF
chmod 600 ~/mcp-ssh/secrets/prod_db_password.txt
# Option 2: Consolidated .env file (recommended for easier management)
cat > ~/mcp-ssh/secrets/.env <<'EOF'
# SSH Passwords
prod_db_password=CHANGE-ME
lab_password=CHANGE-ME-TOO
# SSH Key Passphrases
prod_key_passphrase=CHANGE-ME-PASSPHRASE
EOF
chmod 600 ~/mcp-ssh/secrets/.env
# Note: .env file supports KEY=value format, comments, and quoted values
# See docs/wiki/06.2-credentials.yml.md for details
2.启动编排器容器```bash
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:latest
稍后重新启动 `docker start mcp-ssh-orchestrator`更喜欢一次性容器?使用 `docker run -i --rm ...` 相反。
### 3.连接您的MCP客户端
- **光标:** 添加 `~/.cursor/mcp.json````json
{
"mcpServers": {
"mcp-ssh-orchestrator": {
"command": "docker",
"args": ["start", "-a", "mcp-ssh-orchestrator"],
"env": {"PYTHONUNBUFFERED": "1"}
}
}
}
- 克劳德桌面(macOS): 更新 `~/Library/Application Support/Claude/claude_desktop_config.json````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:latest"
]
}
}
}
(Windows路径: `%APPDATA%\\Claude\\claude_desktop_config.json`.)
更多示例(Docker桌面、多环境、SDK使用)在 集成指南.
### 4.测试连接```bash
# List configured hosts through the MCP server
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:latest
Cursor/Claude现在应该将编排器显示为已连接。跳到 用法食谱 用于指导场景。
安全工作原理(技术细节)
策略即代码工作流:
config/servers.yml, config/credentials.yml,以及 config/policy.yml 在启动时解析,在每次启动时强制执行 ssh_* 工具调用,并在结构化审计日志中镜像,这样你在Git中查看的声明性文件就可以控制你的AI可以执行什么。
纵深防御架构```mermaid
graph TB
subgraph "Layer 1: Transport Security"
L1A[stdio Communication]
L1B[Container Isolation]
end
subgraph "Layer 2: Network Security"
L2A[IP Allowlists]
L2B[Host Key Verification]
end
subgraph "Layer 3: Policy Security"
L3A[Deny-by-Default]
L3B[Pattern Matching]
end
subgraph "Layer 4: Application Security"
L4A[Non-Root Execution]
L4B[Resource Limits]
end
L1A --> L2A
L1B --> L2B
L2A --> L3A
L2B --> L3B
L3A --> L4A
L3B --> L4B
style L1A fill:#e1f5ff
style L1B fill:#e1f5ff
style L2A fill:#d4edda
style L2B fill:#d4edda
style L3A fill:#fff3cd
style L3B fill:#fff3cd
style L4A fill:#f8d7da
style L4B fill:#f8d7da
### 什么被阻止```yaml
# Dangerous commands automatically denied
deny_substrings:
# Destructive operations
- "rm -rf /"
- ":(){ :|:& };:"
- "mkfs "
- "dd if=/dev/zero"
- "shutdown -h"
- "reboot"
- "userdel "
- "passwd "
# Lateral movement / egress tools
- "ssh "
- "scp "
- "rsync -e ssh"
- "curl "
- "wget "
- "nc "
- "nmap "
- "telnet "
- "kubectl "
- "aws "
- "gcloud "
- "az "
# Network isolation enforced
network:
allow_cidrs:
- "10.0.0.0/8" # Only private IPs
- "192.168.0.0/16"
block_ips: [] # Explicit IP blocks (if needed)
允许的内容(示例)```yaml
Safe, read-only commands (using simple_binaries)
rules:
- action: "allow"
aliases:
- "*"
tags:
- "observability"
simple_binaries:
- uptime
- whoami
- hostname
simple_max_args: 6
Disk and memory inspection (using structured rules)
- action: "allow"
aliases: - "*"
tags: -
"observability"
binary: "df"
arg_prefix: ["-h"]
allow_extra_args: false -
action: "allow"
aliases: - "*"
tags: - "observability"
binary: "free"
arg_prefix: ["-m"]
allow_extra_args: false
Log inspection (using structured rules with path restrictions)
- action: "allow"
aliases: - "*"
tags: - "observability"
binary: "tail"
arg_prefix: ["-n", "200"]
allow_extra_args: false
path_args:
indices: [3]
patterns: - "/var/log/*"
Service management (controlled)
- action: "allow"
aliases: - "web-*"
- "db-*"
tags: - "production"
-
"critical-service"
binary: "systemctl"
arg_prefix: ["restart", "nginx"]
allow_extra_args: false -
action: "allow"
aliases: - "web-*"
- "db-*"
tags: - "production"
- "critical-service"
binary: "systemctl"
arg_prefix: ["status"]
allow_extra_args: true
### 防范真实威胁
MCP SSH Orchestrator直接解决了MCP生态系统中记录的漏洞:
- **CVE-2025-49596**:本地主机暴露的MCP服务→ 仅通过stdio运输缓解
- **CVE-2025-6514**:MCP服务器中的命令注入→ 通过基于策略的验证减轻
- **43%的MCP服务器** 存在命令注入缺陷→ 零信任安全模型
**完整的安全模型文档** | **安全风险分析**
## 文档
### 完整文档Wiki
|第节|你将学到什么|
|---------|-------------------|
| **快速入门和示例** |实例和常见工作流程|
| **建筑** |引擎盖下的工作原理|
| **安全模型** |零信任设计和控制|
| **配置** |设置主机、凭据、策略|
| **可观察性和审计** |记录、监控、合规|
| **部署** |生产设置指南|
## 供应链完整性
**已签名的发布工件**:GitHub Release中的每个tarball/zip都附带了由维护者密钥生成的分离GPG签名(`openpgp4fpr:6775BF3F439A2A8A198DE10D4FC5342A979BD358`).导入密钥并在解包前进行验证:```bash
gpg --receive-keys 4FC5342A979BD358
gpg --verify mcp-ssh-orchestrator-v1.3.0.tar.gz.asc mcp-ssh-orchestrator-v1.3.0.tar.gz
Cosign签名的容器图像:下面的图片 ghcr.io/samerfarida/mcp-ssh-orchestrator 在发布工作流中通过Sigstore无密钥签名进行签名。部署前验证签名(和可选证明):bash
COSIGN_EXPERIMENTAL=1 cosign verify \
--certificate-identity-regexp "https://github.com/samerfarida/mcp-ssh-orchestrator/.github/workflows/release.yml@.*" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
ghcr.io/samerfarida/mcp-ssh-orchestrator:latest
图像摘要和签名与GitHub Packages中的每个标签一起发布,因此您可以在促进环境之间的构建时固定确切的引用(包装饲料).
OpenSSF记分卡:存储库维护一个自动记分卡运行,以跟踪依赖关系、构建设置、分支保护等方面的安全状况(记分卡摘要).
AI能用它做什么?(MCP工具)
你的AI助手有13个内置安全功能的强大工具:
探索与规划
ssh_list_hosts-查看所有可用服务器ssh_describe_host-获取主机详细信息和标签ssh_plan- 运行前测试命令 (干运行模式)
执行
ssh_run-在一台服务器上执行单个命令ssh_run_on_tag-在多个服务器上运行命令(例如,所有“web”服务器)ssh_run_async-在后台启动长时间运行的任务
监控与控制
ssh_get_task_status-检查异步任务的进度ssh_get_task_output-实时流输出ssh_get_task_result-完成后获得最终结果ssh_cancel-安全停止正在运行的同步任务ssh_cancel_async_task-安全停止正在运行的异步任务
管理
ssh_reload_config-无需重新启动即可更新主机/凭据ssh_ping-验证与主机的连接
MCP资源+上下文
ssh://hosts–发现经过净化的主机清单(别名、标签、描述、凭据存在)ssh://host/{alias}–在不暴露凭据的情况下检查单个主机ssh://host/{alias}/tags–获取仅标记视图以计划标记执行ssh://host/{alias}/capabilities–每个主机的衍生策略摘要、限制和示例命令权限
上下文感知日志记录: 轻量级流 ctx.debug / ctx.info 支持的客户端中的事件(任务开始、完成、取消) ssh_run, ssh_run_on_tag、配置重新加载和异步任务轮询——所有这些都不会暴露原始命令或秘密。
LLM友好提示: 政策/网络拒绝(和 ssh_plan 预览)包含有用的提示,以便助手自动重试 ssh_plan,查阅编排器提示, 或者询问策略/网络更新是否合适 而不是循环执行被阻止的命令。
完整的工具参考和示例
了解更多
关键差异化因素
- 生产就绪安全:OpenSSF记分卡7.5+分
- 零信任架构:默认情况下拒绝,例外情况下允许
- OWASP LLM十大保护:缓解不安全的插件设计、过度代理、快速注入
- MITRE ATT&CK已对齐:防止内容注入和未经授权的协议使用
- 注重安全:建立在针对真实CVE的安全第一原则之上(CVE-2025-49596,CVE-2025-6514)
- 易于集成:适用于Claude、ChatGPT和任何MCP客户端
- 开源:Apache 2.0许可,社区驱动
用户在说什么
> “最后,我可以让Claude毫无顾虑地管理我的Proxmox集群!” -Homelab管理员
>
> “这就是基础设施即代码应该是的。人工智能访问的声明性安全。” -平台工程师
>
> “结构化的审计日志使事件响应变得更加容易。” -安全工程师
贡献
我们欢迎捐款!查看我们的 贡献指南 用于:
- 开发设置
- 行为准则
- 如何提交PR
- 架构决策
许可证
Apache 2.0-请参阅 许可证 了解详情。
链接
- GitHub存储库 -在GitHub上为我们点赞!
- 问题追踪器 -报告错误或请求功能
- 更新日志 -版本历史和发行说明
- MCP规范 -了解MCP
- Docker MCP安全指南 -安全最佳实践
Ready to give AI secure server access?
Start with our Usage Cookbook →
