Ephemera: Autoridad Certificadora SSH de Cero Confianza

Ephemera es una Autoridad Certificadora (CA) SSH ligera y autoalojada, diseñada para imponer acceso de Cero Confianza (Zero-Trust) para infraestructura. Reemplaza las claves SSH estáticas con certificados de corta duración, integra MFA WebAuthn respaldado por hardware y mantiene registros de auditoría criptográficamente verificables.

[!NOTE] Fuente Canónica: Codeberg
Espejo en GitHub: GitHub (por disponibilidad y alojamiento)

Arquitectura de Alto Nivel

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

Qué hace Ephemera: Gobierna quién puede recibir acceso y por cuánto tiempo.
Qué NO hace Ephemera: Monitoreo en tiempo de ejecución, proxy MITM, inspección de comandos.
Aplicación: Íntegramente dentro de OpenSSH nativo — sin agente de Ephemera en los servidores de destino.
Rotación de claves: No es necesaria — los certificados expiran automáticamente.

Qué es Ephemera

Ephemera es una Autoridad Certificadora SSH autoalojada construida sobre las funciones nativas de OpenSSH. Reemplaza las claves SSH de larga duración con certificados de corta duración emitidos justo a tiempo (just-in-time), con presencia física explícita y escalamiento de privilegios auditable.

Está diseñado para equipos que desean una gobernanza SSH centralizada sin proxies MITM, protocolos personalizados o dependencias en la nube.

Qué no es Ephemera

• No es un proxy SSH ni una puerta de enlace MITM
• No es un reemplazo de PAM
• No es una herramienta de monitoreo en tiempo de ejecución ni de análisis de comportamiento
• No es un servicio en la nube
• No es una plataforma SIEM ni de detección

Estado del Proyecto

Funcionalidad principal de CA SSH: Lista para producción
Trust Budgeting: Experimental (opt-in, sujeto a cambios)

Las funciones experimentales están claramente aisladas y deshabilitadas por defecto.

¿Por qué Ephemera?

El SSH tradicional depende de claves privadas de larga duración distribuidas entre portátiles y servidores. Una vez que una clave se filtra, el acceso persiste hasta que la detectas y rotas las claves en todas partes. Ephemera reemplaza las claves estáticas con certificados de corta duración que caducan automáticamente, reduciendo la ventana de uso indebido de meses a minutos.

Posicionamiento

Ideal Para

• Implementaciones Soberanas: Equipos que requieren propiedad total de su CA sin dependencias externas en la nube.
• Entornos Aislados (Air-Gapped): Diseñado para operar sin acceso a internet saliente una vez implementado.
• Sobrecarga Mínima: Organizaciones que necesitan una seguridad SSH sólida sin la complejidad de gestionar una plataforma completa de secretos.

No Adecuado Para

• Consolidación de IAM Empresarial: Si necesitas una integración profunda con jerarquías complejas de AD/LDAP, Teleport o HashiCorp Vault son más adecuados.
• Preferencia por Servicios Gestionados: Ephemera es autoalojado y no ofrece una variante SaaS.

Capacidades Clave

Acceso Just-in-Time: Los certificados caducan en minutos (5m por defecto), reduciendo la ventana de oportunidad para credenciales robadas.

Aplicación de WebAuthn: La emisión de certificados requiere interacción MFA física (FIDO2) mediante YubiKey o TouchID.

Recuperación Soberana: Las copias de seguridad cifradas están protegidas mediante Shamir's Secret Sharing, requiriendo un quórum para restaurar.

Auditoría Verificable: Todas las acciones de la CA se registran en un libro de contabilidad encadenado con Merkle para un historial a prueba de manipulación.

RBAC Granular: Un motor de políticas basado en YAML define el acceso según roles, recursos y condiciones.

Experimental: Trust Budgeting (Opt-in)

Ephemera incluye un primitivo de gobernanza experimental y opt-in llamado Trust Budgeting.

Trust Budgeting limita la autoridad privilegiada acumulada en el momento de la emisión de certificados, tratando el acceso como un recurso finito y visible. Cada emisión de certificado consume un presupuesto explícito. Cuando el presupuesto se agota, la emisión normal se detiene hasta que el presupuesto se restablece o se utiliza una ruta de emergencia separada (break-glass).

Este mecanismo:

• opera únicamente en el momento de la emisión de certificados
• no introduce monitoreo en tiempo de ejecución ni agentes
• está deshabilitado por defecto
• no es una garantía de seguridad

Trust Budgeting es experimental y puede cambiar o eliminarse.

Documentación: docs/trust_budgeting.md

GateBridge: Evaluación de Políticas en Sombra

Ephemera incluye GateBridge, un sistema de evaluación en sombra que valida las decisiones de política contra un motor alternativo (Gate0) sin afectar el comportamiento en producción.

Garantías del Modo Sombra

• Fail-Open: Si Gate0 falla, se bloquea o se agota el tiempo de espera, la emisión en producción continúa sin verse afectada.
• Sin Reintentos: Un único intento por evaluación — sin bucles de reintento.
• Sin Respaldos: El motor de políticas YAML es siempre la autoridad.
• Solo Observacional: Gate0 nunca bloquea ni modifica la emisión de certificados.

Esquema de Registro (policy-shadow.log)

Cada entrada contiene:

Endpoint de Salud

GET /api/admin/gate0/status

Devuelve:

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

Reversión

GateBridge se puede deshabilitar mediante una bandera de configuración. El modo sombra es fail-open y no afecta las decisiones de autorización.

Compatibilidad

No hay cambios que rompan la interfaz CLI de Gate0. Los registros en sombra ganan nuevos campos, pero siguen siendo analizables hacia atrás.

Inicio Rápido

Objetivo: Emitir tu primer certificado SSH en menos de 5 minutos.

1. Iniciar Ephemera

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

Nota: La contraseña maestra de la CA se genera automáticamente y se persiste en el primer arranque.
Para producción, establece CA_MASTER_PASSWORD en un archivo .env antes de iniciar.

[!IMPORTANT] Implementaciones de Producción: Usa el backend SoftHSM para aislamiento de claves respaldado por hardware. La clave privada de la CA nunca toca el disco. Consulta la Guía de Configuración PKCS#11.

2. Acceder al Panel

Abre http://localhost:3000 en tu navegador.

Credenciales por defecto:

• Usuario: admin
• Contraseña: Revisa los registros de Docker:
  root@kitploit:~

  docker compose logs ephemera | grep "Password:"
  

3. Emitir Tu Primer Certificado

1. Completa la configuración de MFA WebAuthn (requiere clave de hardware o TouchID)
2. Haz clic en "Solicitar Certificado"
3. Tu certificado es válido por 5 minutos

Archivos Compose Alternativos:

• docker-compose.dev.yml — Desarrollo con compilaciones locales y syslog
• docker-compose.test.yml — Incluye un objetivo SSH para pruebas de extremo a extremo

2. Configuración del Cliente (La Magia)

# 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

Recuperación ante Desastres (Copia de Seguridad Cifrada)

Ephemera proporciona un mecanismo de copia de seguridad seguro que cifra tus datos críticos (claves de la CA, base de datos) con una contraseña aleatoria y luego divide esa contraseña en fragmentos de Shamir. Esto asegura que ninguna persona pueda restaurar la copia de seguridad, pero un quórum sí puede.

Crear Copia de Seguridad

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

Esto produce:

• ephemera_backup.enc (El archivo cifrado)
• backup_shard_1_of_5.json, etc. (Los fragmentos de la contraseña)

Nota: Guarda los fragmentos en ubicaciones separadas y seguras. Guarda el archivo de copia de seguridad cifrado de forma segura (es inútil sin los fragmentos).

Restaurar Copia de Seguridad

# 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

Ejemplo de Configuración (policy.yaml)

Ephemera utiliza un potente motor de políticas basado en YAML para el Control de Acceso Basado en Roles (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

Documentación

• Descripción General de Documentación en Vivo
• Consulta ARCHITECTURE.md para detalles de diseño.
• Consulta SECURITY_MODEL.md para supuestos de amenazas y límites de confianza.
• Consulta SECURITY_SPECIFICATIONS.md para especificaciones técnicas detalladas.
• Consulta PRODUCTION_READY.md para listas de verificación de endurecimiento y operaciones.
• Consulta docs/ para guías adicionales.

Seguridad

Consulta SECURITY.md para información sobre divulgación responsable.

¿Quieres contribuir? Revisa nuestras Tareas Pequeñas para Nuevos Contribuyentes.

[!TIP] El modelo de amenazas y los supuestos de seguridad están documentados aquí. Los comentarios y las críticas son bienvenidos.