Threat model

Applies to: ✓ Mode 1 · ✓ Mode 2 · ✓ Mode 3 (the gateway trust boundaries are the same; Mode 3 adds the control plane's own trust — see security.md)

A working security model for a GitHub Actions egress gateway. It names what the system protects, who might attack it, where the trust boundaries are, and what stops each attack today. It is the scoping document for an independent security review, and it is written to be falsifiable: every "mitigated" claim points at code or config a reviewer can check.

First written against the tree at the feat/release-image branch point (20a7941) and kept current since; code references still cite 20a7941 where the mechanism has not changed.

What the system is

One stateless process, skimasque-server, sits at a network egress point. A CI job proves its identity with a GitHub (or GitLab / Buildkite / generic) OIDC token, trades it once for a short-lived credential, and then opens MASQUE tunnels that carry its real traffic. A policy — a set of files the gateway re-reads in place — decides per tunnel whether it opens, to where, and under what rate and volume limits.

                    ┌─────────────────────── gateway host (trusted) ────────────────────────┐
                    │                                                                       │
 CI runner          │   skimasque-server                                                    │
 (semi-trusted)     │   ┌───────────────┐   ┌──────────────────────────────────────────┐    │
   │                │   │ token exchange│   │ data plane (QUIC / HTTP/3)                │    │
   │ OIDC token ────┼──▶│  verify RS256 │   │  IdentityLayer  → verify HS256 credential │    │
   │                │   │  iss/aud/exp  │   │  AuthorizeLayer                           │    │
   │ ◀── credential ┼───│  → HS256 JWT  │   │  PolicyLayer    → evaluate policy set     │    │
   │  (HS256, ~1h)  │   └───────────────┘   │  QuotaLayer     → rate / volume limits    │    │
   │                │                       │  AddressPolicy  → SSRF floor (resolved IP)│    │
   │ tunnels ───────┼──────────────────────▶│  Dispatch       → UdpProxy / TcpProxy     │    │
   │                │                       └───────────────────────┬──────────────────┘    │
   │                │                                               │                       │
   │                │   policy files ─┐   TLS cert/key ─┐           │ egress                │
   │                │   audit log ────┤   (files, hot-reloaded)     │                       │
   │                └─────────────────┼────────────────────────────┼───────────────────────┘
   │                                  │                            │
 OIDC issuer JWKS                operator / CD                private resources
 (external, trusted to           (trusted)                   (db.prod:5432, …)
  sign only its own tokens)

Assets

Actors and trust levels

The central tension: a legitimate CI job is the primary threat agent. The gateway exists precisely because you cannot fully trust the code running in a build. Every boundary below is drawn with "the job is hostile" in mind.

Trust boundaries and the threats at each

B1 — Runner → token-exchange endpoint

A caller presents an OIDC token; the gateway returns a credential.

B2 — Runner → data plane (tunnel open)

Every tunnel carries Proxy-Authorization: Bearer <credential>.

B3 — PolicyLayer → egress (destination authorization)

B4 — Gateway → OIDC issuer (JWKS fetch)

B5 — Network attacker on the runner↔gateway path

B6 — Cross-tenant isolation on one gateway

Multiple repos/workflows share one process.

B7 — Shared platform gateway (--platform)

One process serves many organisations. The tenant is named by the credential (its org_id) or, at exchange, by the audience https://<hostname>/o/<slug>; nothing else selects it, and there is no default tenant.

B8 — Agent session and its sandbox

A coding agent runs with a session credential (see agents.md), issued by the control plane for a signed-in member and enforced by the gateway.

The two authorization escape hatches

Both are named to be greppable, and an audit against 20a7941's successors found neither reachable on an enforced request path by accident.

AuthorizedDestination::trusting

The inner UdpProxy / TcpProxy forwards only to an AuthorizedDestination. trusting is the one constructor that makes one with no policy decision behind it. It is reached in exactly three places:

• No PolicyLayer in the stack (open_tunnel / open_tcp_tunnel fall back to it). This is the deliberate "network floor only" mode for a single-tenant gateway. skimasque-server now warns at startup when an identity source is configured but no policy is — the case where an operator might wrongly believe destinations are constrained.
• Observe mode (--policy-observe), which by definition enforces nothing; it evaluates, logs masque::observe, and forwards. Opt-in, and the audit log is deliberately not written in this mode.
• Tests.

Enforce::call itself is fail-closed: an Allow attaches a real AuthorizedDestination::from_decision, a Deny returns 403, and a request it cannot turn into a policy question (a non-UDP/TCP target) is denied, not passed through. There is no path from Enforce to the inner service that skips authorize.

--insecure

A skimasque-client flag that swaps certificate verification for AcceptAnyCertificate. It is CLI-only (no env var), conflicts_with --ca, prints a warning, and is not exposed by the composite GitHub Action (which only takes an optional --ca). The default client path uses the webpki roots. The library function is pub but named dangerous_client_config_without_verification and documented as dev-only.

A gateway started with --acme serves a publicly-trusted Let's Encrypt certificate for --hostname, so its clients need neither --ca nor --insecure — the default webpki path just works (and skimasque-client --proxy defaults to gateway.skimasque.com). This removes the operational pressure that leads to --insecure (a self-signed gateway whose certificate was not distributed). The ACME account key and issued certificate sit in --acme-cache; they are ordinary key material, protected as assumption 2 requires, and a leaked account key lets an attacker who also controls the domain's DNS or port 443 issue certificates — i.e. it grants nothing they did not already have.

Security assumptions

1. The gateway host and its operator are trusted. Host compromise is out of scope.
2. --credential-secret and the TLS key are stored and distributed by the operator with at least the care of any other production secret.
3. The OIDC issuer signs tokens honestly and manages its keys. It will sign a token for an attacker's own repository — policy, not token validity, is what keeps that attacker out.
4. Policy is treated as code: version-controlled, reviewed, tested with [[tests]], and checked in CI before it reaches --policy-dir.
5. Clients verify the gateway certificate — the default webpki path, which an --acme gateway makes zero-config. --insecure is for local development only.
6. TLS is terminated at the gateway; the egress hop runs on a network the operator already controls with a firewall (skimasque decides who, the firewall decides what is reachable at all).

Non-goals (today)

• Authenticating the application name. Session context, not proof, until Phase 5 (cgroups / eBPF process identity).
• Proof-of-possession credentials. Credentials and OIDC tokens are bearer tokens; a token stolen from a running job grants that job's access for the token's lifetime.
• Protecting against a malicious operator or a compromised host.
• Confidentiality of traffic past the gateway. The proxy exists to make that hop; the private resource sees gateway-sourced plaintext (or its own TLS).
• A hosted multi-org control plane. One gateway, one operator, files on disk.

Known gaps feeding the review

These are the questions the independent review should press on:

1. The per-source rate limiters. The QUIC new-connection path and the token-exchange path both now have per-source-IP token buckets (PerSourceRate / ExchangeRateLimiter in crates/skimasque/src/server.rs), bounded by a MAX_SOURCES LRU map. Is that map the right structure, is keying on an unvalidated QUIC peer address acceptable, and is the residual — a NAT'd fleet sharing one bucket, and no global cap on exchange volume beyond --max-concurrent-requests — the right trade?
2. Per-session resource limits. [limits] are aggregate per policy. Agent sessions now carry a session id (sid), so per-session limits are possible for them; they are not implemented, and CI and developer credentials still have no session id.
3. Bearer-token theft. Is there a practical binding of the credential to the QUIC connection or the runner that would not break mid-session refresh?
4. Policy misconfiguration is the likeliest real-world failure. skimasque policy validate now lints for the broad-[match] cases (match-governs-every-workload, match-lacks-repository, match-lacks-ref), --strict fails CI on them, and the gateway logs them on load (Policy::lints in crates/skimasque-policy/src/lint.rs). Are those three heuristics the right set, is warn-not-fail the right default, and should match-lacks-ref be louder given it is the pull-request-from-a-fork vector?
5. AddressPolicy opt-in granularity. Addressed: --allow-cidr / AddressPolicy::allowed_cidrs is a per-range allow-list that overrides the category floor for exactly the networks listed (allowed_cidrs in crates/skimasque/src/policy.rs). The review should decide whether --allow-private should be deprecated outright, and whether a CIDR that spans a category (e.g. 10.0.0.0/8) deserves a warning.
6. The trusting / --insecure escape hatches. Audited — see The two authorization escape hatches. The internal review should re-confirm the three trusting call sites and that --insecure stays out of the Action, and decide whether the identity-without-policy mode should be a hard error rather than a warning.
7. Fleet secret sharing. The --credential-secret model trades isolation for fleet mobility. SECURITY.md now spells out the blast radius and rotation; the review should still sanity-check the wording. The control plane's D1 scheme narrows this: with --control-plane --oidc, the private signing key stays on the control plane, gateways hold only the org public key and verify credentials against it offline, and issuance goes through POST /v1/gateways/{id}/credentials. A gateway compromise no longer leaks a fleet-wide minting secret. The org key rotates via POST /v1/orgs/{id}/signing-key/rotate — gracefully (previous key kept for the credential TTL) or revoke_previous for an immediate revocation of every outstanding credential. Residual exposure: --credential-secret still signs the 5-minute fallback credentials during a control-plane outage (and --control-plane-no-credential-fallback removes even that); rotation is operator-triggered with no automatic cadence yet, and there is no per-credential revocation. The review should check the outage/fallback window and the still-shared HS256 path.
8. Dependency surface. quinn, h3, rustls, jsonwebtoken. The h3 git pin was reviewed (see the notes in the workspace Cargo.toml): the rev is hyperium/h3 master HEAD, master is developed actively but the h3-v* tags have not moved in over a year, so there is no imminent release to move to; the pin also carries correctness fixes we want. deny.toml restricts git sources to that one URL. Open items for the review: cargo audit does not see the git dependency (an h3 advisory needs a manual watch), and h3-quinn runs from its registry release against patched h3 with no lockstep guarantee. The clean exit is h3 0.0.9, or dropping connect-ip as a goal and reverting to h3 0.0.8.
9. Agent sessions (B8). Open items for the review: (a) revocation propagation is about one round trip by design but has not been measured, and a gateway cut off from the control plane relies on credential expiry (≤ 4 h) for sessions ended meanwhile; (b) [session] max_duration is documented but the gateway does not enforce it, and CI and developer credentials are not cut at expiry (a job longer than the credential lifetime would break), so only agent sessions are cut mid-tunnel; (c) a client with no token falls back to the stored skimasque login session and mints a developer credential, so an agent that can run that client inside its sandbox inherits the owner's login; (d) the expiry deadline is read from the bearer token's exp below an identity layer that has already verified the token, which is sound but is an ordering the stack must preserve; (e) a coding agent's sandbox is not provided, only specified.