Sign up
View stargazersSign up

docs(egress): describe the Egress setting in the security policy, features and threat model#1898

opened11d agobyMMatt Donovan

Note

Written by claude-opus-5-5 via Claude Code on behalf of Matt.

Part of the capture engine programme (brief CE-D1). Follows the Egress setting (#1695, PR #1896).

The Egress setting lets an Operator send everything Birdbrain transmits through a proxy or their own Tor instead of their own connection. The documentation still tells Operators to route the whole machine through a VPN or Tor, and lists outbound connections as if they all leave directly. This issue brings the security policy, the features page and the threat model in line with what the setting does and does not hide.

Agent brief: rulings, scope, acceptance criteria, verification and starting files

Rulings this builds on

  • ADR-0032 (docs/adr/0032-route-app-egress-but-do-not-disguise-the-browser.md), Decision rules 1 to 7: while the Egress is not Direct nothing Birdbrain sends leaves directly; SOCKS5 or HTTP proxies that need no login, never SOCKS4, no direct fallback; the TLS Cert Chain re-fetch is skipped, not routed, and the entry says so; the signed capture entry records the kind, the Operator's label and the user agent, never the proxy's host or port; Tor is the Operator's own; a challenge page is a faithful capture.
  • ADR-0032, "The user agent stays as Electron builds it": the docs say that a background Recapture names Birdbrain and its version to the site, and that the Chrome extension in the Operator's own browser is the path for a target that must not see it.
  • ADR-0032, "Fingerprint impersonation stays excluded": the docs say that the time zone and language still reveal the Operator's region through a proxy.
  • Ruling 20 of 2026-10-10: update checks and downloads follow the Egress and fail closed.
  • ADR-0032 rule 1: Shared Case sync is the exception; teammates and the relay see the Operator's IP while the Egress is not Direct.

Scope

  • SECURITY.md, "Network egress": state for each listed connection whether it follows the Egress (all do but Shared Case sync), that with the proxy down each fails rather than leaving directly, and that the TLS re-fetch (item 2) does not run while the Egress is not Direct. Replace the closing advice to route the whole machine with the Egress setting and its limits. Add Shared Case sync to the list if it is missing.
  • website/content/docs/features.mdx, "Network use": the same facts in the page's voice, plus the two ADR-0032 statements above. "Capture": a capture Birdbrain renders through a non-Direct Egress records the kind, the Operator's label and the user agent in its signed record, never the proxy's address.
  • website/content/docs/threat-model.mdx: a "Network attribution" section stating what the Egress hides (the Operator's address from target sites, the timestamp authority, the Internet Archive, the filter-list hosts and GitHub) and its limits (Shared Case sync; an extension capture's page loads in the Operator's own browser; the user agent names Birdbrain; time zone and language; a capture records what Birdbrain asked the browser to do, not which address the site saw). If the section belongs in the persona threat-model delta instead, leave a comment on #546 saying where it went.
  • Describe only what the merged code does. Read it from main once #1695 has merged: src/main/services/egress.ts, backgroundRenderer.ts, updater.ts, captureLifecycle.ts (the re-fetch skip) and OperatorConfig.tsx (the setting's wording).

Acceptance criteria

  • No sentence in the three files tells the Operator to route the whole machine as the only way to hide their address.
  • SECURITY.md and features.mdx say which connections follow the Egress, that they fail closed, that the TLS re-fetch is skipped, and that Shared Case sync does not follow it.
  • features.mdx carries both ADR-0032 statements: a background Recapture names Birdbrain and its version to the site, with the extension as the path for a target that must not see it; and the time zone and language still reveal the region through a proxy.
  • features.mdx states what a capture's signed record says about the Egress, and that it never holds the proxy's address.
  • threat-model.mdx has the network-attribution section with its limits, or #546 has a comment naming where it went.
  • Every claim matches main after #1695; none describes the VPN warning (#1696) as shipped.

Verification

  • .claude/hooks/vale-prose.sh --base origin/main reports no errors.
  • From website/content/: pnpm dlx mint broken-links passes.

Starting files

SECURITY.md, website/content/docs/features.mdx, website/content/docs/threat-model.mdx, docs/adr/0032-route-app-egress-but-do-not-disguise-the-browser.md, and the source files named in Scope.

Evidence-affecting: no. Documentation only.

Order: opens after #1695 merges, or as a docs pull request stacked on PR #1896.