burrow/docs/TOR.md

Tor Transport

Burrow now has a Tor network type that boots an in-process Arti client and exposes a transparent TCP listener for outbound stream forwarding.

The first implementation is intentionally narrow:

• tcp_stack.kind = "system" is the only supported TCP stack backend.
• transparent destination recovery uses Linux SO_ORIGINAL_DST and macOS PF lookups.
• on macOS, Burrow first tries PF DIOCNATLOOK, then falls back to a pflog0 observer backed by an in-memory flow cache keyed by the redirected socket tuple.
• Burrow does not yet install firewall redirect rules for you.
• traffic reaches Arti only if the host already redirects outbound TCP flows to Burrow's local listener.
• the macOS observer fallback only works when the redirect rule is logged to pflog0 and Burrow listens on an explicit local address such as 127.0.0.1:9040.
• destination handling is IP-and-port based, so this does not yet capture DNS or .onion names before local resolution.
• Burrow still does not install loop-avoidance rules for Arti's own relay connections, so redirect rules must exempt those flows externally for now.

Payload format

Network.payload can be JSON or TOML.

{
  "address": ["100.64.0.2/32"],
  "tun_name": "burrow-tor",
  "mtu": 1400,
  "arti": {
    "state_dir": "/var/lib/burrow/arti/state",
    "cache_dir": "/var/cache/burrow/arti"
  },
  "tcp_stack": {
    "kind": "system",
    "listen": "127.0.0.1:9040"
  }
}

Next steps

• teach Burrow to program and tear down redirect rules safely.
• add loop-avoidance for Arti's own relay connections before enabling automatic redirect.
• add DNS capture or hostname-aware forwarding for .onion and other unresolved destinations.
• add alternate pure-Rust TCP stack backends behind the same tcp_stack enum.