Ephemera : Autoridade Certificadora SSH Zero-Trust

Ephemera é uma Autoridade Certificadora SSH leve e auto-hospedada, projetada para impor acesso Zero-Trust à infraestrutura. Ela substitui chaves SSH estáticas por certificados de curta duração, integra WebAuthn MFA com suporte a hardware e mantém trilhas de auditoria criptograficamente verificáveis.

[!NOTE] Fonte Canônica: Codeberg
Espelho GitHub: GitHub (para disponibilidade e hospedagem)

Arquitetura de Alto Nível

graph LR
    subgraph Client["User (Operator)"]
        SSH["SSH Client"]
        HW["Hardware Key<br/>WebAuthn / YubiKey"]
    end

    subgraph Auth["Authentication Boundary"]
        MFA["WebAuthn MFA<br/><i>Human presence required</i>"]
        OIDC["OIDC<br/><i>Optional</i>"]
    end

    subgraph CA["Ephemera SSH Certificate Authority"]
        CORE["Self-hosted CA<br/>Air-gap capable"]
        POLICY["Policy Engine<br/><i>Governance at issuance</i>"]
        BUDGET["Trust Budgeting<br/><i>Optional</i>"]
    end

    subgraph Targets["Target Servers"]
        NATIVE["Native OpenSSH<br/>TrustedUserCAKeys"]
        NOAGENT["No agents<br/>No SSH proxy"]
    end

    subgraph Audit["Audit & Recovery"]
        LOG["Tamper-Evident<br/>Audit Log"]
        BACKUP["Encrypted Backups<br/>Shamir Recovery"]
    end

    Client --> Auth
    Auth -->|"Short-lived cert"| CA
    CA -->|"Certificate expires<br/>automatically"| Targets
    CA -.->|"Post-fact integrity"| Audit

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

O que o Ephemera faz: Governa quem pode receber acesso e por quanto tempo.
O que o Ephemera NÃO faz: Monitoramento em tempo de execução, proxy MITM, inspeção de comandos.
Aplicação: Integralmente dentro do OpenSSH nativo — nenhum agente Ephemera nos servidores de destino.
Rotação de chaves: Desnecessária — os certificados expiram automaticamente.

O Que É o Ephemera

O Ephemera é uma Autoridade Certificadora SSH auto-hospedada construída sobre os recursos nativos do OpenSSH. Ele substitui chaves SSH de longa duração por certificados de curta duração emitidos no momento exato (just-in-time), com presença física explícita e escalonamento de privilégios auditável.

Ele foi projetado para equipes que desejam governança SSH centralizada sem proxies MITM, protocolos personalizados ou dependências de nuvem.

O Que o Ephemera Não É

• Não é um proxy SSH ou gateway MITM
• Não é um substituto do PAM
• Não é uma ferramenta de monitoramento em tempo de execução ou análise de comportamento
• Não é um serviço de nuvem
• Não é uma plataforma SIEM ou de detecção

Status do Projeto

Funcionalidade principal de CA SSH: Pronta para produção
Trust Budgeting: Experimental (opt-in, sujeito a alterações)

Os recursos experimentais são claramente isolados e desabilitados por padrão.

Por Que Ephemera?

O SSH tradicional depende de chaves privadas de longa duração espalhadas por laptops e servidores. Quando uma chave vaza, o acesso persiste até que você a descubra e rotacione as chaves em todos os lugares. O Ephemera substitui chaves estáticas por certificados de curta duração que expiram automaticamente, reduzindo a janela de uso indevido de meses para minutos.

Posicionamento

Ideal Para

• Implantações Soberanas: Equipes que exigem propriedade total de sua CA sem dependências externas de nuvem.
• Ambientes Isolados (Air-Gapped): Projetado para operar sem acesso à internet de saída após a implantação.
• Sobrecarga Mínima: Organizações que precisam de segurança SSH robusta sem a complexidade de gerenciar uma plataforma completa de segredos.

Não Adequado Para

• Consolidação de IAM Empresarial: Se você precisa de integração profunda com hierarquias complexas de AD/LDAP, Teleport ou HashiCorp Vault são mais adequados.
• Preferência por Serviço Gerenciado: O Ephemera é auto-hospedado e não oferece uma variante SaaS.

Principais Capacidades

Acesso Just-in-Time: Os certificados expiram em minutos (padrão de 5m), reduzindo a janela de oportunidade para credenciais roubadas.

Aplicação de WebAuthn: A emissão de certificados exige interação física de MFA (FIDO2) via YubiKey ou TouchID.

Recuperação Soberana: Backups criptografados são protegidos pelo Compartilhamento de Segredo de Shamir, exigindo quórum para restaurar.

Auditoria Verificável: Todas as ações da CA são registradas em um ledger encadeado por Merkle para um histórico à prova de adulteração.

RBAC Granular: Um mecanismo de políticas baseado em YAML define acesso com base em papéis, recursos e condições.

Experimental: Trust Budgeting (Opt-in)

O Ephemera inclui um primitivo de governança experimental e opt-in chamado Trust Budgeting.

O Trust Budgeting limita a autoridade privilegiada acumulada no momento da emissão de certificados, tratando o acesso como um recurso finito e visível. Cada emissão de certificado consome um orçamento explícito. Quando o orçamento é esgotado, a emissão normal é interrompida até que o orçamento seja redefinido ou um caminho de emergência separado (break-glass) seja utilizado.

Este mecanismo:

• opera apenas no momento da emissão de certificados
• não introduz monitoramento em tempo de execução nem agentes
• está desabilitado por padrão
• não é uma garantia de segurança

O Trust Budgeting é experimental e pode ser alterado ou removido.

Documentação: docs/trust_budgeting.md

GateBridge: Avaliação de Política em Modo Sombra

O Ephemera inclui o GateBridge, um sistema de avaliação sombra que valida decisões de política contra um mecanismo alternativo (Gate0) sem afetar o comportamento em produção.

Garantias do Modo Sombra

• Fail-Open: Se o Gate0 falhar, travar ou expirar, a emissão em produção continua inalterada.
• Sem Repetições (Retries): Uma única tentativa por avaliação — sem loops de repetição.
• Sem Fallbacks: O mecanismo de políticas YAML é sempre a autoridade.
• Apenas Observacional: O Gate0 nunca bloqueia nem modifica a emissão de certificados.

Esquema do Log (policy-shadow.log)

Cada entrada contém:

Endpoint de Saúde

GET /api/admin/gate0/status

Retorna:

{
  "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
  }
}

Rollback

O GateBridge pode ser desabilitado por meio de uma flag de configuração. O modo sombra é fail-open e não afeta decisões de autorização.

Compatibilidade

Nenhuma mudança que quebre a interface de linha de comando do Gate0. Os logs sombra ganham novos campos, mas continuam sendo analisáveis por versões anteriores.

Início Rápido

Objetivo: Emitir seu primeiro certificado SSH em menos de 5 minutos.

1. Iniciar o Ephemera

# Clone and start
git clone https://github.com/Qarait/ephemera.git
cd ephemera
docker compose up -d

Nota: A senha mestra da CA é gerada automaticamente e persistida na primeira execução.
Para produção, defina CA_MASTER_PASSWORD em um arquivo .env antes de iniciar.

[!IMPORTANT] Implantações em Produção: Use o backend SoftHSM para isolamento de chaves com suporte a hardware. A chave privada da CA nunca toca o disco. Consulte o Guia de Configuração PKCS#11.

2. Acessar o Painel

Abra http://localhost:3000 no seu navegador.

Credenciais padrão:

• Usuário: admin
• Senha: Consulte os logs do Docker:
  root@kitploit:~

  docker compose logs ephemera | grep "Password:"
  

3. Emitir Seu Primeiro Certificado

1. Conclua a configuração do WebAuthn MFA (requer chave de hardware ou TouchID)
2. Clique em "Request Certificate"
3. Seu certificado é válido por 5 minutos

Arquivos Compose Alternativos:

• docker-compose.dev.yml — Desenvolvimento com builds locais e syslog
• docker-compose.test.yml — Inclui um destino SSH para testes de ponta a ponta

2. Configuração do Cliente (A Mágica)

# Install the CLI from source
git clone https://github.com/Qarait/ephemera.git
cd ephemera
pip install .

# Initialize your SSH config
ephemera init

# Login to the CA
ephemera login

# Issue your first certificate
ephemera renew

# Check your status
ephemera status

# Connect securely!
ssh user@your-server

Recuperação de Desastres (Backup Criptografado)

O Ephemera oferece um mecanismo de backup seguro que criptografa seus dados críticos (chaves da CA, banco de dados) com uma senha aleatória e, em seguida, divide essa senha em fragmentos (shards) Shamir. Isso garante que nenhuma pessoa isolada possa restaurar o backup, mas um quórum pode.

Criar Backup

# Create encrypted backup and split password into 5 shards (threshold 3)
ephemera backup-create --k 3 --n 5 --out-dir ./backup

Isso gera:

• ephemera_backup.enc (O arquivo criptografado)
• backup_shard_1_of_5.json, etc. (Os fragmentos da senha)

Nota: Armazene os fragmentos em locais seguros e separados. Guarde o arquivo de backup criptografado em local seguro (ele é inútil sem os fragmentos).

Restaurar Backup

# Restore using the encrypted file and any 3 shards
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

Exemplo de Configuração (policy.yaml)

O Ephemera usa um poderoso mecanismo de políticas baseado em YAML para Controle de Acesso Baseado em Papéis (RBAC).

# Define Roles
roles:
  developer:
    can_request_cert: true
    max_cert_duration: 300  # 5 minutes
    allowed_principals: ["dev-user"]
    
  admin:
    can_request_cert: true
    max_cert_duration: 3600 # 1 hour
    allowed_principals: ["root", "admin"]
    can_approve_sudo: true

# Define Rules
rules:
  # Developers can only access dev servers
  - role: developer
    resource: "dev-*"
    action: "ssh"
    effect: allow

  # Admins can access everything with MFA
  - role: admin
    resource: "*"
    action: "ssh"
    effect: allow
    conditions:
      mfa_required: true

Documentação

• Visão Geral da Documentação
• Consulte ARCHITECTURE.md para detalhes de design.
• Consulte SECURITY_MODEL.md para suposições de ameaças e limites de confiança.
• Consulte SECURITY_SPECIFICATIONS.md para especificações técnicas detalhadas.
• Consulte PRODUCTION_READY.md para checklists de endurecimento (hardening) e operações.
• Consulte docs/ para guias adicionais.

Segurança

Consulte SECURITY.md para informações sobre divulgação responsável.

Quer contribuir? Confira nossas Pequenas Tarefas para Novos Contribuidores.

[!TIP] O modelo de ameaças e as suposições de segurança estão documentados aqui. Feedbacks e críticas são bem-vindos.