epithet

Epithet makes SSH certificates easy

Epithet is an SSH certificate authority that replaces static authorized_keys with short-lived certificates (2-10 minutes). It creates on-demand SSH agents for each outbound connection, enabling real-time policy enforcement without touching your target hosts.

Quick start

1. Build epithet:

git clone https://github.com/epithet-ssh/epithet.git
cd epithet
make build

2. Start the agent:

epithet agent \
  --ca-url https://your-ca.example.com \
  --auth "epithet auth oidc --issuer https://accounts.google.com --client-id YOUR_CLIENT_ID"

3. Add to your SSH config (~/.ssh/config):

Include ~/.epithet/run/*/ssh-config.conf

4. SSH as normal:

ssh server.example.com

First connection opens your browser for authentication (~2-5 seconds). Subsequent connections use cached tokens (~100-200ms).

How it works

When you run ssh server.example.com, OpenSSH's Match exec triggers epithet match, which asks the broker for a certificate. The broker handles authentication (via browser-based OIDC or a custom auth plugin), requests a signed certificate from the CA (which checks policy in real-time), and spins up a per-connection SSH agent with the short-lived certificate. See architecture for detailed sequence diagrams.

Components:

• Broker (epithet agent): Daemon managing authentication state and certificate lifecycle. Creates per-connection SSH agents.
• CA Server (epithet ca): Signs SSH certificates after validating tokens against a policy server.
• Policy Server (epithet policy): Makes authorization decisions - who can access what hosts as which users.
• Per-connection Agents: In-process SSH agents, one per unique connection, serving short-lived certificates.

Commands

Documentation

• Architecture - How epithet works under the hood
• Policy Server Guide - Setup and configuration for the policy server
• Authentication - Auth plugin protocol and custom plugins
• OIDC Setup - Provider-specific OIDC configuration (Google, Okta, Azure AD)

Development

make build    # Build all binaries
make test     # Run tests
make clean    # Clean build artifacts

Requirements: Go 1.25+

License

Apache 2.0