CLI Workflow

Commands for authentication, certificate renewal, and status.

Installation

pip install ephemera-cli

Setup

Initialize your SSH configuration to use Ephemera:

ephemera init

This configures your ~/.ssh/config to use certificates from the CA.

Authentication

Login to the CA server:

ephemera login

You will be prompted for WebAuthn (hardware key) or TOTP verification.

YubiKey / WebAuthn Setup

Ephemera uses WebAuthn-compatible hardware keys (such as YubiKey) to enforce physical presence for SSH certificate issuance and sudo approval. Technical details are available in the WebAuthn Guide.

1. Run authentication — Run ephemera login.
2. Hardware Verification — When prompted, insert and touch your YubiKey.
3. Binding — The credential is registered and cryptographically bound to your account.
4. Access — Future SSH renewals and sudo approvals require physical presence.

Certificate Renewal

Request a new short-lived certificate:

ephemera renew

Certificates expire in 5 minutes by default. Renewal requires fresh MFA.

Status

Check current certificate and sudo state:

ephemera status

Shows certificate expiry, current user, and JIT sudo availability.

Sudo History

View privilege escalation events:

ephemera sudo-history

Policy Configuration

Access control is managed through policy.yaml. Example configuration: 

# 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

Connect

After renewal, connect normally:

ssh user@your-server

OpenSSH uses the certificate automatically. No key file management required.