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-url 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 opens your browser for authentication (~2-5 seconds). Subsequent connections reuse the refreshed token.
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 Server (
epithet ca): Coordinates inventory authentication and policy evaluation, and signs SSH certificates after policy authorization. - Inventory Server (
epithet inventory): Validates OIDC tokens, maps directory IDs, and supplies user and host facts from static files. See the inventory guide. - Policy Server (
epithet policy): Evaluates normalized facts and makes authorization decisions - who can access what hosts as which users.
Documentation
- Architecture - How epithet works under the hood
- Policy Server Guide - Setup and configuration for the policy server
- 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
|
|
|
internal
|
|
|
inventorytest
Package inventorytest builds real inventory services for integration tests.
|
Package inventorytest builds real inventory services for integration tests. |
|
pkg
|
|
|
auth/oidc
Package oidc performs OIDC/OAuth2 authentication and returns an ID token.
|
Package oidc performs OIDC/OAuth2 authentication and returns an ID token. |
|
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. |
|
directory
Package directory owns the user and group facts supplied to authorization.
|
Package directory owns the user and group facts supplied to authorization. |
|
facts
Package facts defines normalized authentication, user, and host data shared by inventory resolution and policy evaluation, without transport metadata.
|
Package facts defines normalized authentication, user, and host data shared by inventory resolution and policy evaluation, without transport metadata. |
|
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. |
|
inventory
Package inventory owns host facts and static loading.
|
Package inventory owns host facts and static loading. |
|
inventoryapi
Package inventoryapi defines the v2 resolver protocol independently of Writ and storage implementations.
|
Package inventoryapi defines the v2 resolver protocol independently of Writ and storage implementations. |
|
inventoryserver
Package inventoryserver serves CA-authenticated resolution reads.
|
Package inventoryserver serves CA-authenticated resolution reads. |
|
oidctest
Package oidctest provides a minimal in-process OIDC provider for tests.
|
Package oidctest provides a minimal in-process OIDC provider for tests. |
|
policyserver/writpolicy
Package writpolicy implements the policy server's PolicyEvaluator over a compiled writ policy, an inventory, and registries of requirement handlers, flag sources, and notify targets.
|
Package writpolicy implements the policy server's PolicyEvaluator over a compiled writ policy, an inventory, and registries of requirement handlers, flag sources, and notify targets. |
|
principal
Package principal implements Epithet's deterministic SSH certificate principal schemes.
|
Package principal implements Epithet's deterministic SSH certificate principal schemes. |
|
serviceauth
Package serviceauth mints and verifies short-lived, request-bound JWTs that authenticate CA requests to private services.
|
Package serviceauth mints and verifies short-lived, request-bound JWTs that authenticate CA requests to private services. |
|
tlsconfig
Package tlsconfig provides shared TLS configuration for HTTP clients.
|
Package tlsconfig provides shared TLS configuration for HTTP clients. |
|
wire
Package wire holds every type that crosses a process boundary (CA, policy server, CA client).
|
Package wire holds every type that crosses a process boundary (CA, policy server, CA client). |
|
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, a direct port of the retired Rust spike's ast.rs (the porting reference named by SPEC §12.11).
|
Package ast is the parsed form of a writ policy file, a direct port of the retired Rust spike's ast.rs (the porting reference named by SPEC §12.11). |
|
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/parser
Package parser turns writ policy source into the AST.
|
Package parser turns writ policy source into the AST. |
|
test
|
|
Click to show internal directories.
Click to hide internal directories.