README
¶
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 without touching your target hosts.
Quick start
1. Build epithet:
git clone https://github.com/epithet-ssh/epithet.git
cd epithet
make
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 locally, and signs SSH certificates. - Control (
epithet control): Handles administration, SCIM provisioning, and host enrollment using its own signing key. - Directory / Inventory (
epithet directory,epithet inventory): Independently replaceable user and host fact services. Backends own storage, mutation invariants, and audit. - Combined launcher (
epithet server): Supervises these four separate services and the public router. See deployment.
Documentation
- Architecture - How epithet works under the hood
- Directory and SCIM groups - identities, current group names, and database upgrades
- Writ Policy Guide - Authorization rules and configuration
- Fact Provider API - Implement a custom directory or inventory
- Destination-bound Principals - Interoperable principal derivation protocol
- Authentication - The OIDC token contract and in-process auth flow
- OIDC Setup - Provider-specific OIDC configuration (Google, Okta, Azure AD)
- Releasing - Notes on cutting releases
Requires OpenSSH 9.4+ on the client (for Tag/Match tagged; see below).
License
Apache 2.0
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
epithet
command
|
|
|
pkg
|
|
|
breakerpool
Package breakerpool provides a generic circuit breaker pool with priority-based failover.
|
Package breakerpool provides a generic circuit breaker pool with priority-based failover. |
|
facts
Package facts owns directory and inventory protocol types, service authentication, and typed clients.
|
Package facts owns directory and inventory protocol types, service authentication, and typed clients. |
|
facts/control
Package control authenticates public requests and authorizes administrative operations, then invokes fact services through their typed clients.
|
Package control authenticates public requests and authorizes administrative operations, then invokes fact services through their typed clients. |
|
facts/directory
Package directory owns managed identities, administration, and the user and group facts supplied to authorization.
|
Package directory owns managed identities, administration, and the user and group facts supplied to authorization. |
|
facts/directory/scim
Package scim adapts SCIM provisioning to the directory storage contract.
|
Package scim adapts SCIM provisioning to the directory storage contract. |
|
facts/directory/sqlitestore
Package sqlitestore implements the managed directory using embedded SQLite.
|
Package sqlitestore implements the managed directory using embedded SQLite. |
|
facts/inventory
Package inventory owns managed host facts, enrollment, patterns, and storage.
|
Package inventory owns managed host facts, enrollment, patterns, and storage. |
|
facts/inventory/sqlitestore
Package sqlitestore implements managed inventory using embedded SQLite.
|
Package sqlitestore implements managed inventory using embedded SQLite. |
|
facts/server
Package server serves built-in directory and inventory facts and their private management APIs.
|
Package server serves built-in directory and inventory facts and their private management APIs. |
|
facts/storage
Package storage owns the database settings shared by the built-in fact stores.
|
Package storage owns the database settings shared by the built-in fact stores. |
|
hostpattern
Package hostpattern implements the hostname-pattern language shared by inventory resolution and Writ host selectors.
|
Package hostpattern implements the hostname-pattern language shared by inventory resolution and Writ host selectors. |
|
oidc
Package oidc owns OIDC login, token verification, and Epithet identity mapping.
|
Package oidc owns OIDC login, token verification, and Epithet identity mapping. |
|
oidctest
Package oidctest provides a minimal in-process OIDC provider for tests.
|
Package oidctest provides a minimal in-process OIDC provider for tests. |
|
principal
Package principal implements Epithet's deterministic SSH certificate principal schemes.
|
Package principal implements Epithet's deterministic SSH certificate principal schemes. |
|
tlsconfig
Package tlsconfig provides shared TLS configuration for HTTP clients.
|
Package tlsconfig provides shared TLS configuration for HTTP clients. |
|
wire
Package wire contains shared certificate, discovery, host, and evaluation types.
|
Package wire contains shared certificate, discovery, host, and evaluation types. |
|
writ
Package writ is the facade over the writ policy language frontend: parse, check, and lower to the IL in one call.
|
Package writ is the facade over the writ policy language frontend: parse, check, and lower to the IL in one call. |
|
writ/ast
Package ast is the parsed form of a Writ policy file.
|
Package ast is the parsed form of a Writ policy file. |
|
writ/compile
Package compile checks a parsed writ file for well-formedness and lowers it to the IL.
|
Package compile checks a parsed writ file for well-formedness and lowers it to the IL. |
|
writ/diag
Package diag holds source positions and diagnostics for the writ policy language.
|
Package diag holds source positions and diagnostics for the writ policy language. |
|
writ/eval
Package eval is SPEC §8 as a pure function: order-independent evaluation of a compiled policy against one (user, host, account) request.
|
Package eval is SPEC §8 as a pure function: order-independent evaluation of a compiled policy against one (user, host, account) request. |
|
writ/il
Package il is writ's intermediate language: the compiled rule format per SPEC §10–11.
|
Package il is writ's intermediate language: the compiled rule format per SPEC §10–11. |
|
writ/object
Package object defines the provider-independent objects consumed by Writ.
|
Package object defines the provider-independent objects consumed by Writ. |
|
writ/parser
Package parser turns writ policy source into the AST.
|
Package parser turns writ policy source into the AST. |
|
writpolicy
Package writpolicy evaluates supplied user and host facts against a compiled Writ policy, with registries of requirement handlers, flag sources, and notify targets.
|
Package writpolicy evaluates supplied user and host facts against a compiled Writ policy, with registries of requirement handlers, flag sources, and notify targets. |
|
test
|
|
|
catest
Package catest supplies controllable evaluators for CA boundary tests.
|
Package catest supplies controllable evaluators for CA boundary tests. |
|
controltest
Package controltest runs the real public control service and private backends.
|
Package controltest runs the real public control service and private backends. |
Click to show internal directories.
Click to hide internal directories.