Doppler SSH Skill

企业级 SSH 密钥管理方案，为 SSH MCP Server 提供安全的密钥管理。

本项目是基于 Cigarliu/ssh-mcp-server 的企业级密钥管理增强方案。 原项目提供了强大的 SSH/SFTP MCP 服务器功能，本项目专注于为其提供安全的密钥管理集成。

特性

• 🔐 Service Token 认证 - 生产环境推荐，最小权限原则
• 📁 文件挂载模式 - 比环境变量更安全（推荐）
• 🔑 环境变量模式 - 兼容传统部署
• 🧹 内存安全清除 - 使用后自动覆盖敏感数据
• 📊 审计日志 - 完整的密钥访问记录
• 🔄 密钥轮换 - 无需重启服务
• ⚠️ 危险变量检测 - 自动识别 RCE 风险

安装

从 PyPI 安装（推荐）

pip install doppler-ssh-skill

从源码安装

git clone https://github.com/example/doppler-ssh-skill.git
cd doppler-ssh-skill
pip install -e .

开发安装

pip install -e ".[dev]"

快速开始

步骤 1: 安装 Doppler CLI

# macOS / Linux
curl -Ls https://cli.doppler.com/install.sh | sh

# Windows (使用 PowerShell)
iwr -Uri https://doppler.com/install.ps1 -UseBasicParsing | iex

步骤 2: 登录 Doppler

doppler login

步骤 3: 创建项目并配置 Secrets

# 创建项目
doppler projects create ssh-mcp-server

# 创建配置环境
doppler configs create prod

# 添加 secrets
doppler secrets set SSHMCP_HOST_PROD_PASSWORD="your-password" --config prod
doppler secrets set SSHMCP_HOST_PROD_KEY_PASSPHRASE="key-passphrase" --config prod

# 生成 Service Token（生产环境必需）
doppler configs tokens create prod-token --config prod --plain

步骤 4: 在代码中使用

from doppler_ssh import DopplerSSHSkill, DopplerMode

# 方式 1: 文件挂载模式（推荐，最安全）
skill = DopplerSSHSkill(
    project="ssh-mcp-server",
    config="prod",
    mode=DopplerMode.MOUNT
)

with skill:
    host_config = skill.load_host_config("prod")
    print(f"Connected to {host_config.host}")
    skill.secure_clear(host_config)

# 方式 2: 环境变量模式
skill = DopplerSSHSkill(
    project="ssh-mcp-server",
    config="prod",
    mode=DopplerMode.ENV
)

with skill:
    host_config = skill.load_host_config("prod")
    print(f"Connected to {host_config.host}")
    skill.secure_clear(host_config)

步骤 5: 使用 CLI

# 验证配置
doppler-ssh-skill validate --config config.yaml

# 加载主机配置
doppler-ssh-skill load -p ssh-mcp-server -c prod --host prod

# 生成 secrets 模板
doppler-ssh-skill template -p ssh-mcp-server -c prod -o secrets.yaml

# 列出所有 secrets
doppler-ssh-skill list-secrets -p ssh-mcp-server

配置示例

完整配置文件 (config.yaml)

doppler:
  enabled: true
  mode: mount  # mount | env
  project: ssh-mcp-server
  config: prod
  mount_path: /run/secrets/ssh
  mount_max_reads: 1

hosts:
  prod:
    host: "192.168.1.100"
    port: 22
    username: "root"
    auth_source: "doppler"
    secret_prefix: "prod"
    auth_type: "password"

  staging:
    host: "192.168.1.101"
    port: 22
    username: "admin"
    auth_source: "doppler"
    secret_prefix: "staging"
    auth_type: "key"
    key_path: "~/.ssh/id_rsa"

  dev:
    host: "localhost"
    port: 22
    username: "developer"
    auth_source: "doppler"
    secret_prefix: "dev"
    auth_type: "password"

环境变量配置

# 必需的环境变量
export DOPPLER_TOKEN="dp.st.xxx"  # Service Token

# 可选配置
export DOPPLER_PROJECT="ssh-mcp-server"
export DOPPLER_CONFIG="prod"
export DOPPLER_MODE="mount"

Python 代码配置

from doppler_ssh import DopplerSSHSkill, DopplerMode

# 使用环境变量
skill = DopplerSSHSkill()

# 显式指定参数
skill = DopplerSSHSkill(
    project="ssh-mcp-server",
    config="prod",
    mode=DopplerMode.MOUNT,
    mount_path="/run/secrets/ssh",
    mount_max_reads=1,
    timeout=30,
    cache_ttl=300
)

安全特性

1. Service Token（生产环境必需）

# 生成只读 Service Token
doppler configs tokens create prod-token --config prod --plain

# 导出到环境变量
export DOPPLER_TOKEN="dp.st.xxx"

2. 文件挂载模式（最安全）

# 使用 doppler run 的 --mount 参数
doppler run \
  --mount /run/secrets/ssh \
  --mount-max-reads 1 \
  -- python -m doppler_ssh run

3. 内存安全清除

# 自动清除内存中的 secrets
skill.secure_clear(host_config)

# 清除所有敏感数据
skill.clear_all()

4. 危险变量检测

自动检测并拒绝以下危险变量名：

• LD_PRELOAD, LD_LIBRARY_PATH - Linux RCE
• DYLD_INSERT_LIBRARIES - macOS RCE
• PYTHONWARNINGS, NODE_OPTIONS - 语言级 RCE

致谢

• Cigarliu/ssh-mcp-server - 原项目，提供强大的 SSH/SFTP MCP 服务器功能
• Doppler - 密钥管理服务

故障排查

常见问题

1. DopplerTokenError: Invalid token

原因: Service Token 无效或已过期

解决方案:

# 重新生成 Token
doppler configs tokens create new-token --config prod --plain

# 更新环境变量
export DOPPLER_TOKEN="dp.st.xxx"

2. SecretNotFoundError: Secret not found

原因: Secret 名称不匹配

解决方案:

# 检查 Secret 名称格式
# 预期格式: SSHMCP_HOST_{HOST}_{SECRET_NAME}
# 例如: SSHMCP_HOST_PROD_PASSWORD

# 列出所有 secrets
doppler secrets list --config prod

# 或使用 CLI
doppler-ssh-skill list-secrets -p ssh-mcp-server -c prod

3. PermissionDeniedError: Mount path not accessible

原因: 文件挂载路径权限不足

解决方案:

# 检查挂载路径权限
ls -la /run/secrets/ssh

# 或切换到环境变量模式
export DOPPLER_MODE=env

4. ConnectionTimeoutError: Connection timed out

原因: 网络超时或主机不可达

解决方案:

# 增加超时时间
skill = DopplerSSHSkill(timeout=60)

# 或在配置中设置
# timeout: 60

5. MountReadLimitExceeded

原因: 文件挂载读取次数超限

解决方案:

# 增加最大读取次数
doppler run --mount-max-reads 10 -- your-command

调试模式

# 启用调试日志
export DOPPLER_SSH_DEBUG=1

# 或使用 CLI
doppler-ssh-skill validate --config config.yaml -v

日志查看

# 查看详细日志
doppler-ssh-skill load -p ssh-mcp-server -c prod --host prod --verbose

架构

┌─────────────────────────────────────────┐
│         Doppler SSH Skill               │
├─────────────────────────────────────────┤
│  ┌─────────┐    ┌─────────────────┐    │
│  │  Mount  │    │   Environment   │    │
│  │  Mode   │ or │     Mode        │    │
│  └────┬────┘    └────────┬────────┘    │
│       │                  │             │
│       ▼                  ▼             │
│  ┌─────────────────────────────────┐   │
│  │      SecretResolver             │   │
│  │  - normalize_host_name()        │   │
│  │  - build_secret_name()          │   │
│  └─────────────────────────────────┘   │
│                   │                    │
│                   ▼                    │
│  ┌─────────────────────────────────┐   │
│  │      SecurityManager            │   │
│  │  - validate_token_type()        │   │
│  │  - secure_clear_string()        │   │
│  │  - mask_secrets_in_logs()       │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘

开发

# 克隆仓库
git clone https://github.com/example/doppler-ssh-skill.git
cd doppler-ssh-skill

# 安装依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 代码格式化
black src/
ruff check src/

# 类型检查
mypy src/

许可证

MIT License - 详见 LICENSE

参考

• Doppler 官方文档
• Doppler CLI 指南
• Doppler Service Tokens