Skip to content

README.md

Latest commit

 

History

History
139 lines (97 loc) · 4.54 KB

README.md

File metadata and controls

139 lines (97 loc) · 4.54 KB
Raw

Epithet makes SSH certificates easy

Epithet is an SSH certificate authority that replaces static authorized_keys with short-lived certificates (2-10 minutes) and authentication over OIDC. It creates on-demand SSH agents for each outbound connection, enabling real-time policy enforcement with standard OpenSSH.

Community

Very small right now, but we have a mailing list!

Installation

macOS

Install with Homebrew on Apple Silicon or Intel Macs:

brew install epithet-ssh/tap/epithet

FreeBSD

Packages are available for FreeBSD 15 on amd64. Run the following as root to install the repository signing key and configure the signed package repository:

install -d -m 0755 /usr/local/etc/pkg/keys /usr/local/etc/pkg/repos
fetch -o /usr/local/etc/pkg/keys/epithet.pub https://pkg.epithet.dev/keys/epithet.pub
chmod 0644 /usr/local/etc/pkg/keys/epithet.pub
cat > /usr/local/etc/pkg/repos/Epithet.conf <<'EOF'
Epithet: {
    url: "https://pkg.epithet.dev/${ABI}/latest",
    signature_type: "pubkey",
    pubkey: "/usr/local/etc/pkg/keys/epithet.pub",
    enabled: yes
}
EOF
pkg update -r Epithet
pkg install -r Epithet epithet

Keep the literal ${ABI} in the repository URL. The package includes server rc.d scripts, disabled by default; installation does not start a server.

Arch Linux

Packages are available for x86_64. Import and trust the repository signing key:

curl -fsS --proto '=https' https://pkg.epithet.dev/keys/epithet-arch.asc | sudo pacman-key --add -
sudo pacman-key --lsign-key EDF8AFF765FBCD24AE3E2D0B1146870201C33C51

Add the following to /etc/pacman.conf, keeping the literal $arch:

[epithet]
SigLevel = Required
Server = https://pkg.epithet.dev/arch/$arch

Then update the system and install Epithet:

sudo pacman -Syu epithet

From source

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

Add the resulting epithet binary to your PATH.

Quick start

1. Install Epithet.

2. Start the agent:

epithet agent --ca https://your-ca.example.com/

The agent discovers its OIDC issuer and client ID from the CA's Link header on the root response — nothing to configure locally.

3. Tag the hosts this profile should handle, then include the generated config (~/.ssh/config):

Host *.example.com
    Tag epithet

Include ~/.epithet/run/*/ssh-config.conf   # must come after Tag lines

4. SSH as normal:

ssh server.example.com

First connection authenticates through your browser (~2-5 seconds). In an SSH session, Epithet automatically uses the OIDC device flow instead. Subsequent connections reuse the refreshed token.

To scope the agent to a shell or another command, pass that command to the agent. It starts only after the broker is ready, and the agent exits when the command exits:

epithet agent zsh

The child uses the same generated ~/.ssh/config setup shown above. Use --login-method browser or --login-method device to override automatic login-method selection.

How it works

When you run ssh server.example.com, OpenSSH's Match tagged triggers epithet match for hosts you've tagged in your own ssh config. epithet match asks the broker for a certificate. The broker authenticates in-process via OIDC, 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:

  • Agent (epithet agent): Daemon managing OIDC authentication state and certificate lifecycle. Creates per-connection SSH agents.
  • CA (epithet ca): Authenticates users, reads facts, evaluates Writ, and signs SSH certificates.
  • Directory / Inventory (epithet directory, epithet inventory): Independently replaceable user and host fact services. Backends own storage, mutation invariants, and audit.
  • Control (epithet control): Control plan, handles administration, SCIM provisioning, and host enrollment.

Documentation

Requires OpenSSH 9.4+ on the client (for Tag/Match tagged; see below).

License

Apache 2.0