Threat Model

Structured threat analysis following the AWS Threat Composer methodology

This threat model documents the threats Vouch is designed to address, the assumptions the design relies on, and the mitigations in place. It follows the STRIDE (opens in new tab) framework and is structured after the AWS Threat Composer (opens in new tab) methodology.

For background on Vouch’s security controls, see the Security Model page. For system design details, see the Architecture Overview page.

System description

Vouch is a credential broker that replaces long-lived developer secrets (AWS access keys, SSH private keys, GitHub PATs) with short-lived, hardware-backed credentials. The system has three components:

• Vouch CLI + Agent — runs on the developer’s machine, holds session state in memory, and serves credentials to tools via standard protocols (credential helper, SSH agent).
• Vouch Server — validates FIDO2 assertions, issues OIDC tokens, signs SSH certificates, and brokers credentials from external services.
• External services — AWS STS, GitHub Apps, SSH hosts, container registries, and other services that consume Vouch-issued credentials.

Dataflow

┌──────────┐  FIDO2 assertion   ┌──────────────┐  kms:Sign (ES256)  ┌─────────┐
│  YubiKey │─-─────────────────►│ Vouch Server │──────────────────-►│ AWS KMS │
└──────────┘                    │              │◄──────────────────-┤         │
                                │              │  JWT signature     └─────────┘
┌──────────┐  session token     │              │
│Vouch CLI │◄────────────────-──┤              │  kms:Sign (Ed25519)
│ + Agent  │  (DPoP-bound)      │              │──────────────────-►┌─────────┐
│          │                    │              │◄──────────────────-┤ AWS KMS │
│          │  OIDC ID token     │              │  SSH cert signature└─────────┘
│          │──────────────────-►│              │
│          │  STS credentials   │              │  GitHub App key
│          │◄── ── ── ── ── ──--┤              │──────────────────-►┌─────────┐
│          │  (via AWS STS)     │              │◄─────────────────-─┤ GitHub  │
│          │                    │              │  installation token│ API     │
│          │  SSH cert request  │              │                    └─────────┘
│          │──────────────────-►│              │
│          │  signed SSH cert   │              │
│          │◄──────────────────-┤              │
└──────────┘                    └──────────────┘
      │
      │  short-lived credential
      ▼
┌──────────────────┐
│ Tool (aws, ssh,  │
│ git, docker)     │
└──────────────────┘

Data flows:

1. Login — YubiKey signs FIDO2 assertion → CLI sends to server over TLS → server validates against enrolled public key → server evaluates device posture policies (if active) → returns a DPoP-bound session token, which the CLI persists to its config file (owner-only permissions) and hands to the agent for in-memory caching. The server never issues refresh tokens — a new session requires a fresh FIDO2 assertion.
2. AWS credential — CLI presents session token + DPoP proof → server issues OIDC ID token (signed via KMS ES256) → CLI calls AWS STS AssumeRoleWithWebIdentity → STS returns temporary credentials.
3. SSH certificate — CLI sends signing request with session token → server delegates to KMS Ed25519 CA → returns signed SSH certificate → agent serves via SSH agent protocol.
4. GitHub token — CLI requests token with session token → server exchanges GitHub App credentials for installation access token → returns short-lived token to CLI.

All CLI ↔ server traffic uses TLS 1.3 (TLS 1.2 is accepted, restricted to BCP 195 AEAD cipher suites). Authenticated credential-API requests carry HTTP Message Signatures (RFC 9421 (opens in new tab)) for request-level integrity; OAuth endpoints are protected by private_key_jwt client assertions and DPoP proofs instead. Brokered AWS credentials live only in agent memory. The session token is persisted to the CLI config file and the SSH key and certificate to ~/.ssh/, all with owner-only file permissions.

Assets

Threat actors

Trust boundaries

┌─────────────────────────────────────────────────────────────────────┐
│  Developer Workstation                                              │
│                                                                     │
│  ┌───────────┐    Unix socket    ┌────────────┐                     │
│  │ Vouch CLI │◄─────────────────►│ Vouch Agent│                     │
│  └─────┬─────┘  (owner-only)     └─────┬──────┘                     │
│        │                               │                            │
│  ┌─────┴─────┐                   ┌─────┴─────-─┐                    │
│  │  YubiKey  │                   │ In-memory   │                    │
│  │  (FIDO2)  │                   │ credentials │                    │
│  └───────────┘                   └────────────-┘                    │
│                                                                     │
└──────────────────────────┬──────────────────────────────────────────┘
                           │ TLS 1.3/1.2
              ─────────────┼──────────── Network boundary
                           │
┌──────────────────────────┴──────────────────────────────────────────┐
│  Vouch Server                                                       │
│                                                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────┐         │
│  │ FIDO2 RP     │  │ OIDC Provider│  │ SSH CA (Ed25519)   │         │
│  │ (assertion   │  │ (ES256 via   │  │ (signing via       │         │
│  │  validation) │  │  AWS KMS)    │  │  AWS KMS)          │         │
│  └──────────────┘  └──────────────┘  └────────────────────┘         │
│                                                                     │
│  ┌──────────────┐  ┌──────────────┐                                 │
│  │ User store   │  │ Audit log    │                                 │
│  │ (public keys,│  │ (auth events,│                                 │
│  │  metadata)   │  │  issuance)   │                                 │
│  └──────────────┘  └──────────────┘                                 │
│                                                                     │
└──────────────────────────┬──────────────────────────────────────────┘
                           │ TLS 1.3/1.2
              ─────────────┼──────────── Service boundary
                           │
┌──────────────────────────┴──────────────────────────────────────────┐
│  External Services                                                  │
│                                                                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────────┐       │
│  │ AWS STS  │  │ GitHub   │  │ SSH Hosts│  │ Container      │       │
│  │          │  │ Apps API │  │          │  │ Registries     │       │
│  └──────────┘  └──────────┘  └──────────┘  └────────────────┘       │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Three trust boundaries separate the system:

1. Hardware boundary — The YubiKey’s secure element. Private keys are generated on-device and cannot be extracted.
2. Workstation boundary — The developer’s machine. The agent process, Unix socket, and in-memory credentials are protected by OS-level user isolation.
3. Network boundary — All communication between CLI and server, and between server and external services, uses TLS 1.3, with TLS 1.2 accepted using BCP 195-restricted AEAD cipher suites.

Assumptions

These assumptions underpin the threat model. If an assumption is violated, the mitigations that depend on it no longer hold.

Threats

Threats are organized using the STRIDE (opens in new tab) categories. Each threat follows the AWS Threat Composer grammar (opens in new tab): a [threat source] with [prerequisites] can [threat action], leading to [threat impact], negatively impacting [impacted assets].

Spoofing

Mitigations:

• T-S1: FIDO2 origin binding prevents the YubiKey from signing assertions for unregistered domains. Even if a developer visits a phishing site, the authenticator will not produce a valid assertion. → FIDO2 security properties
• T-S2: YubiKey PINs provide a second factor — physical possession alone is insufficient. Keys should be reported lost immediately, and the enrolled credential should be removed from the user’s account. Session lifetime (8 hours) limits the window.
• T-S4: SCIM tokens are stored as SHA-256 hashes — a database read cannot recover them. Domain validation restricts user creation to the organization’s verified domains, every provisioning operation is audited (scim_operation), tokens are revocable at any time from /admin/scim-tokens, and audit-trail read access must be explicitly granted when a token is minted. → SCIM Provisioning
• T-S5: Domain verification requires publishing a DNS TXT record, and ownership is re-proven continuously — verified domains are re-checked daily and unverify after 3 consecutive failures. A claimed domain affects only future enrollments; existing users never change organizations. All domain lifecycle transitions are audited. The residual risk is accepted: DNS control is the industry-standard proof of domain ownership (assumption A11). → Email Domains

T-S3 (use of a still-active session after delayed offboarding) was re-categorized as elevation of privilege — see T-E4. The former employee’s identity is genuine; it is the authorization that is stale.

Tampering

Mitigations:

• T-T1: All CLI-to-server communication uses TLS 1.3 (TLS 1.2 accepted with BCP 195 AEAD ciphers only). HTTP Message Signatures (RFC 9421 (opens in new tab)) provide request-level integrity on the credential API — the CLI signs requests to /v1/ endpoints using the FAPI key pair, and the server rejects any in-scope request with an invalid or missing signature (deny-by-default). OAuth endpoints are protected by private_key_jwt client assertions and DPoP proofs instead. DPoP (RFC 9449 (opens in new tab)) binds tokens to the client’s key pair — intercepted tokens cannot be used from a different machine, and presenting a DPoP-bound token as a plain Bearer token is rejected. For browser-based OIDC applications, PAR (RFC 9126 (opens in new tab)) transmits authorization parameters server-side, keeping sensitive data out of URLs and browser history.
• T-T2: Platform signing keys (OIDC ES256/RS256 and SSH CA Ed25519) are managed by AWS KMS and cannot be extracted or modified — server compromise does not expose signing key material, though signing authority while the attacker retains access cannot be removed by key secrecy (that impersonation outcome is T-E3). Per-organization issuer keys are the exception: they are generated in software and stored sealed under document-level encryption, so recovering them requires the runtime document-decryption capability (KMS-gated, restricted to attested instances) rather than a database dump alone; staged and emergency key rotation exist to respond to suspected exposure. The document encryption private key is KMS-wrapped, with the key policy restricting decryption to NitroTPM-attested EC2 instances. The server stores no user credentials for external services — AWS and GitHub tokens are brokered on demand; the standing exception is the GitHub App private key, held in server configuration to authenticate as the App. Infrastructure controls (network isolation, access auditing) provide defense in depth. → Shared responsibility
• T-T3: Release binaries include SLSA Build Level 3 (opens in new tab) provenance and SBOM attestations (Sigstore-backed, built in a dedicated reusable workflow and verifiable with gh attestation verify --signer-workflow) plus SHA256 checksums, and releases are independently rebuilt to verify reproducibility. APT and DNF repositories are GPG-signed and verified automatically by the package manager; Homebrew installs are pinned by SHA256 checksum. → Supply chain security
• T-T4: Document-level encryption binds each record to its row and document type, preventing ciphertext relocation, but sealing requires only the public key — encryption alone does not authenticate writers. Integrity of enrollment records therefore rests on database access control and infrastructure hardening (assumption A7). Enrollment and key-registration events are audited, making unexpected credential changes detectable, and the SIEM export preserves that trail off-server; remediation is per-user credential revocation.

Repudiation

Mitigations:

• T-R1: Every credential issuance is tied to a hardware-verified FIDO2 identity. The Vouch server logs all authentication events and credential exchanges. AWS CloudTrail records STS credential usage with the Vouch-issued identity as the principal.
• T-R2: Audit logs should be continuously pulled into an immutable, external log store via the SIEM export API (OCSF projection, cursor-based polling) so that server compromise cannot erase the trail. → Shared responsibility

Information disclosure

Mitigations:

• T-I1: DPoP binds tokens to the CLI’s key pair — a token stolen in transit or from a backup cannot be used from another machine, and no refresh tokens exist to steal. Against a local attacker running as the user, DPoP is a weaker boundary: the client key pair itself is reachable (OS keychain, or the file fallback in headless environments), so the effective bounds are credential lifetime, server-side revocation, and device posture policies. Brokered AWS credentials live only in agent memory and are never written to disk (no ~/.aws/credentials). The session token is persisted to the CLI config file and the SSH key and certificate to ~/.ssh/, all with owner-only permissions. Session lifetime is limited to 8 hours (SSH certificates expire with the session), and AWS STS credentials expire within 1 hour. Full endpoint compromise with kernel access is out of scope (see assumption A5).
• T-I2: TLS encrypts all traffic in transit (1.3 preferred, 1.2 restricted to BCP 195 AEAD suites). DPoP provides an additional layer — even if a token is somehow intercepted, it cannot be replayed from another client.
• T-I3: OIDC discovery is public by design (required for AWS OIDC federation). The exposed information (issuer URL, JWKS, supported algorithms) does not enable impersonation. Private keys are never exposed through these endpoints.

Denial of service

Mitigations:

• T-D1: The Vouch server implements rate limiting and is deployed behind infrastructure-level DDoS protection. Authentication requires a valid FIDO2 assertion, making automated abuse expensive.
• T-D2: Cached credentials remain valid for their remaining lifetime (up to 8 hours for sessions and SSH certificates, 1 hour for AWS STS). Developers can continue working with existing credentials during an outage. → Availability and Failure Modes

Elevation of privilege

Mitigations:

• T-E1: The Unix socket is restricted to the owning user by filesystem permissions. Additionally, the agent verifies peer credentials (SO_PEERCRED / getpeereid) on every connection to its IPC socket, confirming the connecting process has the same UID — rejected connections are audit-logged for forensic visibility. The companion SSH agent socket relies on the same owner-only directory and socket permissions. On startup, the agent validates that its socket directory ($XDG_RUNTIME_DIR/vouch/, or ~/.cache/vouch/ where XDG_RUNTIME_DIR is unset) is not a symlink and is owned by the current user, preventing directory hijacking. DPoP prevents extracted tokens from being used on a different machine. Credential scope is limited to the user’s authorized roles — the attacker cannot escalate beyond what the user could already access. This threat is bounded by session lifetime (8 hours, which also bounds SSH certificates) and AWS credential lifetime (≤1 hour).
• T-E2: IAM roles should follow least-privilege principles. Vouch enables fine-grained role mapping per user via OIDC claims. CloudTrail provides full attribution of which user assumed which role. → Shared responsibility
• T-E3: Signing keys are in AWS KMS (non-extractable). The document encryption private key is KMS-wrapped, with the key policy restricting decryption to NitroTPM-attested instances — an attacker with disk or database access alone cannot decrypt user data. Server infrastructure is hardened with network isolation, encrypted storage, audited access, and minimal attack surface. The server does not store user credentials for external services — it brokers them — so compromise enables credential issuance (while the attacker maintains access) but not extraction of stored user secrets.
• T-E4 (formerly T-S3): SCIM integration enables automated de-provisioning — deactivation revokes active sessions and issued SSH certificates (via the CA revocation list). Sessions can also be revoked server-side. Outstanding AWS credentials (≤1 hour) expire naturally.

Mitigation summary

Out of scope

The following threats are explicitly out of scope for this threat model:

Validation

• Automated scanning – Dependency auditing (cargo deny: advisories, licenses, sources) and a deny-level lint gate (unsafe code and panics denied workspace-wide) run on every commit; dependency review runs on every pull request; container images are vulnerability-scanned on push.
• SLSA provenance – Release binaries include Build Level 3 provenance and SBOM attestations, verifiable against the source repository and the pinned reusable build workflow with gh attestation verify --signer-workflow; releases are independently rebuilt to verify reproducibility.
• Protocol conformance – WebAuthn assertion validation is covered by a spec-referenced test suite (WebAuthn Level 2), OIDC behavior is validated against the OpenID Foundation conformance suite, and HTTP Message Signatures are tested against the official RFC 9421 test vectors.
• Client diagnostics – vouch doctor performs runtime checks (YubiKey and agent health, server connectivity and clock skew, session validity, SSH/EKS/SSM configuration) to validate the local setup.

Review schedule

This threat model is reviewed quarterly and after any change to a trust boundary or credential flow. The revision history below tracks updates.

Revision history