privatae-bastion/docs/security-model.md

# Security model

- **The bastion dials out.** Every lane is a reverse connection from this
  machine to the host. No port is opened on an externally reachable interface;
  the control ports and console bind loopback only, and the optional
  memory-mirror forwarder binds loopback plus the replica container's private
  gateway address, with every accept source-checked.
- **Inside the tunnel, only gated listeners.** The host can connect to up to
  three inference forwards (local ollama, an OpenAI-compatible server, a PII
  sterilizer), each a proxy to a service you run, on loopback by default and
  elsewhere only if you point it there by environment variable; and to one
  port per server in the service slot (18100 to 18199), joined to that
  server's socket; and to one port per coder run (18200 to 18299), joined to
  that run's control socket. Every connection is checked when it is accepted: a forward
  needs the pairing to hold the `inference` capability family, a service
  slot port needs the `services` family and a reach grant for that server
  naming that host, and a coder run port needs the `harness` family, the run
  to be that host's and within its deadline, and the connection to come from
  that host's own tunnel address. Nothing else in the tunnel accepts a connection.
- **A Host on this machine gets the same walls.** Its lanes go over its lane
  socket with mutual TLS against the CA pinned at pairing, the pairing's name
  checked and the bearer on every lane; a pairing with no bearer opens none.
  A coder run it owns is a socket in its own runs directory (0660, group
  `privatae-host`, else root), checked at every accept as a run port is, and
  removed at run-down and at the watchdog's stop. The runs directory must be
  one only root can change (root's, writable by nobody else, under
  directories that are root's and not writable by others unless sticky), or
  no socket is made in it. On an anchored machine its run-up needs the
  standing coder grant like any pairing's.
- **Scoped tunnel.** The WireGuard peer's only allowed address is the paired
  host's single tunnel address, so the tunnel can reach nothing else. A
  pairing that offers anything wider is refused, and a pairing file that
  holds one brings no tunnel up.
- **No MCP endpoint.** Nothing on this machine drives the host.
- **Grants are verified here.** What the host may do arrives signed. The verify
  key is pinned on first use, and a deny always beats an allow.
- **Fixed argv.** Every management op runs a fixed command line. File ops are
  dedicated Go handlers with no shell. Text extraction runs a named local tool
  from a fixed template.
- **Approval on the machine, once enrolled.** With a second factor enrolled
  here, folder grants, move plans, model pulls and root sessions each need a
  code from this machine, bound to that exact request, single use. Without
  one, grants and move plans rest on the signed grant alone, and model pulls
  and root sessions are refused.
- **On an anchored machine, a write needs an approval verified and spent
  here.** It comes from the second factor enrolled here or from your pinned
  approval device, is bound to the op and a digest of its arguments, and is
  used once; with neither enrolled, those writes are refused. The exceptions
  take no fresh approval: standing work under a place you set up at the
  machine (backup fetch and backup push, the host's context store), a backup
  restore request (approved on its own, below), runs under op terms you
  approved earlier, a root command under the grant you gave here with the
  code, the anchor host's signed pairing records, revokes, and a
  self-update to a newer version we signed. Repeated refused writes close a pairing's
  write lanes for a while.
- **Host-written programs run sandboxed first.** An op runs only under signed
  terms you approved, as a dry run in a sandbox with no network, and never
  changes anything outside its declared file effects. A one-time apply lands
  only the change list you saw; a run under a standing grant is held to the
  grant's bounds.
- **A server in the service slot has no network.** The host's tunnel is its
  only way in, and it cannot reach this machine, your network or the
  internet.
- **Egress for someone else reaches the public internet, never this
  machine.** A coder run's proxy, always, and the egress lane on an anchored
  machine refuse loopback, link-local (the cloud metadata address included),
  private, CGNAT and reserved addresses, and any address this machine takes
  as its own: one on its interfaces (a public one included), and on Linux any
  address the kernel's routing table delivers here (a `local`, broadcast,
  anycast or multicast route, such as an AnyIP range on `lo`), asked of the
  kernel per connection. The IPv4 address inside an IPv4-mapped, NAT64 or
  6to4 address is checked too, every address a name resolves to is checked,
  and the address checked is the one dialled. When the machine cannot tell,
  it refuses. A coder run reaches a LAN host only when you named it in
  `coders set --allow-lan`; the anchored egress lane has no such exception.
  The anchored lane's refusal of this machine's own non-private addresses is
  new in 0.50.0; before it, that lane refused only the internal ranges. A
  local (unanchored) machine's egress lane is unchanged and vets no
  destination. The backup lanes (`backup_fetch` and `backup_push`, anchored
  or not) apply the same check of this machine's own addresses, to every
  address the URL's name resolves to, to each redirect a fetch follows and to
  the address dialled; this too is new in 0.50.0, and before it they refused
  only loopback, private, link-local, multicast, unspecified, CGNAT and ULA
  addresses. Also since 0.50.0 they classify an address as a coder run's
  proxy does: the IPv4 address inside a NAT64 `64:ff9b::/96` or 6to4
  address is judged, and IPv4-compatible and IPv4-translated addresses, the
  rest of `64:ff9b::/32`, site-local `fec0::/10`, `0.0.0.0/8`,
  `198.18.0.0/15` and `240.0.0.0/4` are refused. Not covered: a public
  address that reaches this machine only through a 1:1 NAT in front of it,
  which is on no interface and in no local route. The bastion does not learn
  that address.
- **A terminal is checked here and logged.** On a local (unanchored) machine,
  a terminal opens when the host asks, with no approval. No signed grant is
  needed, but one that is sent is verified, and a deny in it refuses. On an
  anchored machine, a host other than the anchor needs the `session` family
  in its pairing grant, and each terminal needs an approval from your pinned
  approval device or the second factor enrolled here, bound to that one
  session and used once. A root terminal, on either kind of machine, needs
  the bastion to run as root, a second factor enrolled here, and a code
  entered on this machine for that session; an approval device cannot approve
  it. Each session, and each refusal of a well-formed request, is written to
  the audit log on this machine when the pairing has a grant store; a
  malformed request is refused with no audit line.
- **Root commands run only under a grant given here with the code.** Only
  the anchor host can hold it. It names this machine, ends when you said, is
  revoked from this console, and needs the bastion to run as root. A revoke
  or an expiry also stops a command already running, within 2 seconds. Every
  command and its output is written to a transcript here and to the audit
  log; refusals, malformed commands and setup failures are audited too.
- **Root only where there is no one else to ask.** Claiming ownership or the
  anchor requires root because those are machine-wide facts.
- **On macOS and Windows, a networked bastion is the system's service.** It
  runs as root under launchd, or as LocalSystem under the Windows service
  manager, starts at boot and is restarted when it stops, so the signed-in
  user cannot stop it. It is registered only from a program that only root or
  an administrator can replace. Beside it, `pair`, `run` and `status` from an
  account that does not administer the machine are refused, so this binary
  will not start a second bastion in that account. An older or modified copy
  is not bound by that refusal; what keeps the service in place is that the
  signed-in user does not administer the machine.
- **Observation changes nothing on the machine.** Observe ops read and report.
  No input injection lives in the bastion. The observe ops that send traffic
  are `observe:net`, an outbound probe to a host you name; `observe:k8s`, a
  read-only query of a cluster API; and the three monitoring ops
  (`observe:alerts`, `observe:metrics`, `observe:logs`), read-only HTTP
  against an Alertmanager/Prometheus/Loki on the box's own network —
  private addresses only, re-checked at the socket so neither a redirect nor
  a DNS answer can walk a query out of that neighbourhood.
- **A backup's key goes to a host only when you approve it here.** A host's
  request to restore files a request and gets nothing until you approve it
  on this machine; the key sealed to the host then opens that one backup and
  no other, and this bastion's key never leaves this machine. Thinning the backup
  folder removes only backup files this bastion recorded fetching, still as
  they arrived, judged by arrival here. A host sends from this machine only
  backup files in its own folder or a folder you shared with it.
- **No delete op on shared stores.** The one write lane is a move plan you
  approved, and it archives rather than deletes.
- **Verified releases.** The self-updater checks the release manifest's
  signature against the release keys compiled into it, then checks the
  binary's SHA-256 against that manifest before anything is swapped. The
  agent download is checked the same way, and an installed agent is never
  replaced with an older one. The release key never reaches the machine that
  builds and publishes: each release waits until the key holder signs it on
  their own computer. The installer checks the SHA-256; see
  [SECURITY.md](../SECURITY.md) for what that does and does not prove.
- **No secrets cached for git.** The credential helper fetches a token from
  the host on every auth and stores nothing itself, and `git-setup` resets
  the forge's helper chain before adding it. With git 2.46 or later, git's
  own store and cache helpers keep nothing, wherever they are configured; a
  helper that records everything it is given still receives the token. A git older than 2.46 gets the username
  and password, and for it only helpers configured before `git-setup`'s
  lines are kept out.

## How each claim is tested

[claims.md](claims.md) names, for each point above, the test that fails if
it stops being true, and says where there is none.

To report a security issue, please do not open a public issue. See
[SECURITY.md](../SECURITY.md).