Ephemera : 零信任SSH证书颁发机构 (Zero-Trust SSH Certificate Authority)

Ephemera 是一个轻量级、自托管的SSH证书颁发机构，旨在为基础设施实施零信任访问。它用短生命周期证书替换静态SSH密钥，集成硬件支持的WebAuthn多因素认证（MFA），并维护密码学可验证的审计追踪。

[!NOTE] 主源仓库: Codeberg
GitHub镜像: GitHub（用于可用性和托管）

高层架构

graph LR
    subgraph Client["用户（操作者）"]
        SSH["SSH客户端"]
        HW["硬件密钥<br/>WebAuthn / YubiKey"]
    end

    subgraph Auth["认证边界"]
        MFA["WebAuthn MFA<br/><i>需要人类存在</i>"]
        OIDC["OIDC<br/><i>可选</i>"]
    end

    subgraph CA["Ephemera SSH证书颁发机构"]
        CORE["自托管CA<br/>可气隙部署"]
        POLICY["策略引擎<br/><i>发放时的治理</i>"]
        BUDGET["信任预算<br/><i>可选</i>"]
    end

    subgraph Targets["目标服务器"]
        NATIVE["原生OpenSSH<br/>TrustedUserCAKeys"]
        NOAGENT["无代理<br/>无SSH代理"]
    end

    subgraph Audit["审计与恢复"]
        LOG["防篡改<br/>审计日志"]
        BACKUP["加密备份<br/>Shamir恢复"]
    end

    Client --> Auth
    Auth -->|"短生命周期证书"| CA
    CA -->|"证书自动过期"| Targets
    CA -.->|"事后完整性"| Audit

    style Auth fill:#e8f5e9,stroke:#2e7d32
    style CA fill:#e3f2fd,stroke:#1565c0
    style Audit fill:#fff3e0,stroke:#ef6c00

Ephemera 的功能： 控制谁可以获取访问权限以及访问时长。
Ephemera 不做什么： 运行时监控、中间人代理、命令检查。
执行方式： 完全在原生OpenSSH内部——目标服务器上无需Ephemera代理。
无需密钥轮换： 证书会自动过期。

Ephemera 是什么

Ephemera 是一个基于原生OpenSSH功能构建的自托管SSH证书颁发机构。它将长期存在的SSH密钥替换为即时发放的短生命周期证书，并要求明确的人体存在和可审计的权限提升。

它专为希望实现集中化SSH治理但又不想使用中间人代理、自定义协议或云依赖的团队而设计。

Ephemera 不是什么

• 不是一个SSH代理或MITM网关
• 不是一个PAM替代品
• 不是一个运行时监控或行为分析工具
• 不是一个云服务
• 不是一个SIEM或检测平台

项目状态

核心SSH CA功能：生产就绪
信任预算：实验性（可选启用，可能变更）

实验性功能已明确隔离，并在默认情况下禁用。

为什么选择 Ephemera？

传统SSH依赖于分布在笔记本电脑和服务器上的长期私钥。一旦密钥泄露，访问权限将持续存在，直到你发现并到处轮换密钥。Ephemera 用自动过期的短生命周期证书替换静态密钥，将误用窗口从数月缩短到数分钟。

定位

最适合

• 主权部署：需要完全拥有CA且不依赖外部云服务的团队。
• 气隙环境：设计为部署后无需出站互联网访问即可运行。
• 最小开销：需要强大SSH安全性但又不想管理完整秘密平台的组织。

不适合

• 企业IAM整合：如果需要与复杂的AD/LDAP层次结构深度集成，Teleport 或 HashiCorp Vault 更合适。
• 偏好托管服务：Ephemera 是自托管的，不提供SaaS版本。

关键能力

即时访问：证书在数分钟内过期（默认5分钟），减少凭证被盗用的机会窗口。

WebAuthn强制：证书发放需要通过YubiKey或TouchID进行物理MFA（FIDO2）交互。

主权恢复：加密备份通过Shamir秘密共享保护，需要法定人数才能恢复。

可验证审计：所有CA操作都记录在Merkle链式账本中，提供防篡改历史。

细粒度RBAC：基于YAML的策略引擎根据角色、资源和条件定义访问权限。

实验性：信任预算（可选启用）

Ephemera 包含一个可选的实验性治理原语，称为信任预算。

信任预算通过将访问视为有限、可见的资源，在证书发放时限制累积的特权权限。每次证书发放都会消耗明确的预算。当预算耗尽时，正常发放停止，直到预算重置或使用单独的紧急（打破玻璃）路径。

该机制：

• 仅在证书发放时运作
• 不引入运行时监控或代理
• 默认禁用
• 不是安全保证

信任预算为实验性，可能变更或移除。

文档：docs/trust_budgeting.md

GateBridge：影子策略评估

Ephemera 包含 GateBridge，一个影子评估系统，在不影响生产行为的情况下，验证策略决策与备用引擎（Gate0）的一致性。

影子模式保证

• 故障开放：如果Gate0失败、崩溃或超时，生产发放不受影响。
• 无重试：每次评估仅尝试一次 —— 无重试循环。
• 无回退：YAML策略引擎始终是权威的。
• 仅观测：Gate0从不阻止或修改证书发放。

日志架构 (policy-shadow.log)

每条记录包含：

健康端点

GET /api/admin/gate0/status

返回：

{
  "bridge_version": "1.0.0",
  "gate0_version": "v0.2.1",
  "policy_hash": "sha256:8f4b...",
  "status": "healthy",
  "last_mismatch": null,
  "telemetry": {
    "latency_p50_ms": 2.3,
    "latency_p95_ms": 5.1,
    "latency_p99_ms": 8.7
  }
}

回退

GateBridge 可以通过配置标志禁用。影子模式是故障开放的，不会影响授权决策。

兼容性

Gate0 CLI接口没有破坏性变更。影子日志会增加新字段，但向后兼容可解析。

快速开始

目标： 在5分钟内签发你的第一张SSH证书。

1. 启动 Ephemera

# 克隆并启动
git clone https://github.com/Qarait/ephemera.git
cd ephemera
docker compose up -d

注意： CA主密码在首次运行时会自动生成并持久化。
对于生产环境，在启动前将 CA_MASTER_PASSWORD 设置在 .env 文件中。

[!IMPORTANT] 生产部署：使用SoftHSM后端实现硬件支持的密钥隔离。CA私钥永远不会接触磁盘。参见 PKCS#11 Setup Guide。

2. 访问仪表板

在浏览器中打开 http://localhost:3000。

默认凭据：

• 用户名： admin
• 密码： 查看Docker日志：
  root@kitploit:~

  docker compose logs ephemera | grep "Password:"
  

3. 签发你的第一张证书

1. 完成WebAuthn MFA设置（需要硬件密钥或TouchID）
2. 点击“请求证书”
3. 你的证书有效期为5分钟

备选Compose文件：

• docker-compose.dev.yml — 开发环境，本地构建和syslog
• docker-compose.test.yml — 包含SSH目标，用于端到端测试

2. 客户端设置（神奇之处）

# 从源码安装CLI
git clone https://github.com/Qarait/ephemera.git
cd ephemera
pip install .

# 初始化你的SSH配置
ephemera init

# 登录到CA
ephemera login

# 签发第一张证书
ephemera renew

# 检查你的状态
ephemera status

# 安全连接！
ssh user@your-server

灾难恢复（加密备份）

Ephemera 提供一种安全的备份机制，用随机密码加密你的关键数据（CA密钥、数据库），然后将密码拆分为Shamir碎片。这确保没有任何单个人可以恢复备份，但法定人数可以。

创建备份

# 创建加密备份，并将密码拆分为5个碎片（阈值为3）
ephemera backup-create --k 3 --n 5 --out-dir ./backup

这会生成：

• ephemera_backup.enc（加密归档包）
• backup_shard_1_of_5.json 等（密码碎片）

注意： 将碎片分别存放在不同的安全位置。将加密备份文件安全存放（没有碎片则无用）。

恢复备份

# 使用加密文件和任意3个碎片恢复
ephemera backup-restore --backup ./backup/ephemera_backup.enc --shards ./backup/backup_shard_1_of_5.json ./backup/backup_shard_2_of_5.json ./backup/backup_shard_4_of_5.json --out-dir ./restored

配置示例 (policy.yaml)

Ephemera 使用强大的基于YAML的策略引擎进行基于角色的访问控制（RBAC）。

# 定义角色
roles:
  developer:
    can_request_cert: true
    max_cert_duration: 300  # 5分钟
    allowed_principals: ["dev-user"]
    
  admin:
    can_request_cert: true
    max_cert_duration: 3600 # 1小时
    allowed_principals: ["root", "admin"]
    can_approve_sudo: true

# 定义规则
rules:
  # 开发者只能访问开发服务器
  - role: developer
    resource: "dev-*"
    action: "ssh"
    effect: allow

  # 管理员可以访问所有资源，但需要MFA
  - role: admin
    resource: "*"
    action: "ssh"
    effect: allow
    conditions:
      mfa_required: true

文档

• 实时文档概览
• 架构详情请参见 ARCHITECTURE.md。
• 威胁假设和信任边界请参见 SECURITY_MODEL.md。
• 深度技术规范请参见 SECURITY_SPECIFICATIONS.md。
• 加固和运维检查清单请参见 PRODUCTION_READY.md。
• 更多指南请参见 docs/。

安全

负责任地披露信息请参见 SECURITY.md。

想贡献？请查看我们的 新贡献者小任务。

[!TIP] 威胁模型和安全假设已记录在此处。欢迎提供反馈和批评。