cassh

SSH Key & Certificate Manager for GitHub

For individuals and enterprises alike

Whether you're a solo developer managing personal projects or an enterprise team with hundreds of engineers,
cassh brings security best practices to your SSH workflow — without the complexity.

---

Get Started in 60 Seconds

Personal GitHub.com users — no server required:

# 1. Install GitHub CLI (if you haven't)
brew install gh
gh auth login

# 2. Install cassh
brew tap shawntz/cassh
brew install --cask cassh

# 3. Launch cassh — setup wizard opens automatically — done!

Enterprise users — see Server Setup for CA and Entra configuration.

---

Why cassh?

For Individual Developers

You might think: "I already use gh to upload my SSH key — why do I need this?"

The gh CLI is great for the initial setup, but it doesn't manage your keys:

The Problem	Without cassh	With cassh
Key lifecycle	Keys live forever until you manually delete them	Automatic rotation (4 hours to 90 days)
Laptop lost/stolen	Your key still works until you notice and revoke it	Key auto-expires per your policy
Shared/work computer	That SSH key might still be there months later	Set short rotation for shared environments
Multiple machines	Different keys everywhere, no central management	Same workflow on every Mac
SSH config	Manually edit ~/.ssh/config for each account	Automatic configuration

Security isn't just for enterprises. Your personal GitHub account has access to your private repos, your contributions to other projects, and possibly deploy keys. Treat it accordingly.

For Enterprise Teams

Permanent SSH keys are a security liability:

Scenario	With Permanent Keys	With cassh
Laptop lost	Manual revocation required, often missed	Certificate expires automatically
Employee offboarding	Hunt down and revoke all their keys	Certificates expire within hours
Compliance audit	"When was this key last rotated?"	Full lifecycle tracking
Key compromise	Blast radius until detected	Limited to certificate validity window

cassh issues 12-hour certificates signed by your internal CA. No revocation lists to manage, no keys to track, no manual intervention needed.

---

One App, All Your GitHub Accounts

Most developers juggle multiple GitHub accounts — work and personal, or multiple organizations. cassh manages them all from a single menu bar app.

• Enterprise connections use certificates that auto-expire
• Personal connections use keys with configurable rotation
• Each connection gets its own SSH key and config entry
• Status at a glance — green means you're good, yellow means expiring soon, red means action needed

---

Features

Feature	Personal	Enterprise
One-click setup wizard	✓	✓
Automatic SSH config	✓	✓
Per-connection Git identity	✓	✓
Menu bar status indicator	✓	✓
Key/cert rotation	✓ (configurable)	✓ (12h default)
Multi-account support	✓	✓
Revoke & renew from menu bar	✓	✓
Dotfiles-friendly config	✓	✓
Microsoft Entra SSO	—	✓
CA-signed certificates	—	✓
MDM deployment (PKG)	—	✓

---

How It Works

Personal Flow (GitHub.com)

Download cassh → Launch → Setup Wizard → Enter GitHub username → Done

Behind the scenes:

1. cassh generates an Ed25519 SSH key
2. Uploads it to GitHub via gh ssh-key add
3. Configures ~/.ssh/config automatically
4. Tracks key age and rotates per your policy
5. On rotation: deletes old key from GitHub, generates new key, uploads new key

Enterprise Flow (GitHub Enterprise)

Click menu bar → Generate Certificate → SSO login → Certificate installed

Behind the scenes:

1. Opens browser to your cassh server
2. Authenticates via Microsoft Entra ID
3. Server signs your public key with the CA (includes login@HOSTNAME extension)
4. Certificate returned and installed automatically via cassh:// URL scheme
5. Certificate expires in 12 hours — repeat as needed

Setup: Just paste any SSH clone URL from your GitHub Enterprise (e.g., user_123@github.company.com:org/repo.git) and cassh extracts the hostname and SCIM-provisioned username automatically.

---

Quick Start

Personal Users

1. Install prerequisites:

   brew install gh
   gh auth login

2. Install cassh via Homebrew:

   brew tap shawntz/cassh
   brew install --cask cassh

3. Launch — the setup wizard opens automatically

4. Add Personal Account — enter your GitHub username, choose rotation policy

5. Done! — git clone your repos and go

Enterprise Users

See the Full Documentation for:

• Server Setup — CA keys, Entra app configuration
• Deployment — Fly.io, Render, Railway, VPS
• Client Distribution — MDM deployment with PKG

---

Configuration

cassh stores your connections in a simple TOML config file. The config is dotfiles-friendly — store it in ~/.config/cassh/config.toml to back up with your dotfiles.

# ~/.config/cassh/config.toml

[[connections]]
id = "personal-github"
type = "personal"
name = "Personal GitHub"
github_host = "github.com"
github_username = "yourusername"
ssh_key_path = "~/.ssh/cassh_personal_id_ed25519"
key_rotation_hours = 168  # Rotate every 7 days

[[connections]]
id = "enterprise-work"
type = "enterprise"
name = "Work GitHub"
server_url = "https://cassh.yourcompany.com"
github_host = "github.yourcompany.com"
github_username = "user_123"  # SCIM-provisioned username from SSH clone URL
ssh_key_path = "~/.ssh/cassh_work_id_ed25519"
ssh_cert_path = "~/.ssh/cassh_work_id_ed25519-cert.pub"

Git Identity: cassh can also manage per-connection git identities. When you add a connection, optionally specify your user.name and user.email. cassh uses Git's includeIf to automatically apply the correct identity based on the repo's remote URL. Your work repos use your work email, personal repos use your personal email — automatically.

See the Configuration Reference for all options, or check out config.example.toml for a complete example.

---

Roadmap

See the full roadmap for details.

Status	Feature
✅	GitHub Enterprise SSH certificates
✅	GitHub.com personal SSH key management
✅	Automatic key rotation with configurable policies
✅	Multi-account support (enterprise + personal)
✅	Setup wizard for first-run configuration
✅	macOS menu bar app with connection status
✅	Microsoft Entra ID (Azure AD) SSO
🚧	Policy integrity verification
📝	GitLab support
📝	Bitbucket support
📝	Linux support

Legend: ✅ Complete | 🚧 In Progress | 📝 Planned

---

Security

Caution

For Enterprise deployments:

• Protect your CA private key — it can sign certificates for anyone
• Use HTTPS — OAuth tokens are transmitted
• Restrict Entra app — limit which users can authenticate
• Review access logs regularly

Tip

For Personal users:

• Use a short rotation policy (4-24h) on shared or work computers
• Use a longer policy (7-90 days) on personal machines you control
• cassh stores keys in ~/.ssh/ with proper permissions (0600)

---

Architecture

GitHub Enterprise Flow (Certificates)

flowchart LR
    subgraph Client
        A[Menu Bar App]
    end

    subgraph Server
        B[cassh Server]
        C[Internal CA]
    end

    subgraph External
        D[Microsoft Entra ID]
        E[GitHub Enterprise]
    end

    A -->|1. Request cert| B
    B -->|2. OIDC auth| D
    D -->|3. Identity verified| B
    B -->|4. Sign pubkey| C
    C -->|5. SSH certificate| B
    B -->|6. Return cert| A
    A -->|7. SSH with cert| E

Loading

GitHub.com Personal Flow (SSH Keys)

flowchart LR
    subgraph Client
        A[Menu Bar App]
        B[gh CLI]
    end

    subgraph External
        C[GitHub.com]
    end

    A -->|1. Generate SSH key| A
    A -->|2. Upload via gh| B
    B -->|3. Add to GitHub| C
    A -->|4. SSH with key| C
    A -.->|5. On rotation: delete old, upload new| B

Loading

---

Support the Project

cassh is built and maintained by Shawn Schwartz, a PhD candidate in Psychology at Stanford. By day, he builds software for cognitive neuroscience research. By night, he builds security tools like this one.

If cassh saved you time or made your workflow more secure:

• Sponsor on GitHub
• Star this repo and share it with others

Every bit of support helps me justify the time spent on this free and open-source side project instead of my dissertation.

---

Why Open Source?

Security tooling should be auditable. You shouldn't have to trust a black box with your SSH authentication.

Contributions welcome! Check out CONTRIBUTING.md to get started.

---

License

Apache 2.0 — See LICENSE for details. © Shawn Schwartz, 2025.