strawberry/docs/tracker-attribution.md
trvon c77bc79dc7
Some checks failed
Build and Test / build (debug, clang) (push) Has been cancelled
Build and Test / build (debug, gcc) (push) Has been cancelled
Build and Test / build (release, clang) (push) Has been cancelled
Build and Test / build (release, gcc) (push) Has been cancelled
Build and Test / macos (push) Has been cancelled
Build and Test / docker (push) Has been cancelled
Privacy: macOS tracker source via Little Snitch log-traffic (WS2 macOS)
Completes the tracker-attribution transport on macOS. There is no network
sandbox to work around there, so the daemon (root) reads Little Snitch's traffic
stream directly and feeds the same on_opensnitch_connection consumer — no relay
or ingest socket (those are the Linux sandbox answer).

- LittleSnitchParser (cross-platform, unit-tested): parses `littlesnitch
  log-traffic` CSV via a header-name->index map (tolerates column reordering),
  yielding the shared redacted OpenSnitchConnection for outbound rows only
  (program, uid, host/ip/port, protocol 6->tcp/17->udp). Little Snitch's CSV has
  no argv/env, so redaction is structural. split_csv_line handles quoted fields.
- LittleSnitchSource (macOS only): posix_spawns `littlesnitch log-traffic
  --stream`, reads the pipe on a guarded thread, parses and calls back; stop()
  SIGTERMs the CLI (EOF -> loop ends) then reaps it.
- Daemon: start_tracker_attribution gains an __APPLE__ branch that starts the
  source; shutdown/status handle it. New config littlesnitch_cli (default CLI
  path). status privacy.listener source "little-snitch".
- docs: macOS section rewritten (needs Little Snitch "Allow access via Terminal").

Test E10 covers the parser (header, outbound/inbound, deny, quoted exe, no-dest).
Linux suite 51/51; analyzer + clang-tidy clean (Linux view). The __APPLE__ code
compiles/validates on the Mac next (ssh); live spawn needs root + LS Terminal access.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-10-28 18:54:27 -06:00

80 lines
4.9 KiB
Markdown

# Tracker attribution (privacy, advisory only)
Which programs on this machine talk to advertising and tracking networks,
not only the browser. Built with the measurement rules of the CarolinaCon
2026 talk "How Ad Networks Map You" (`~/Documents/work/conference`,
bridgescope): a contacted domain on a list is a *candidate*, not proof of
tracking, and every observation is labelled with how strong it is.
## Rules
- **Never blocks, never a finding.** Tracker contacts are not threats. They
are never written to OpenSnitch or Little Snitch rules, never trigger
containment, never raise a finding or an exec-guard decision. A source
invariant (R11) keeps tracker code out of the response paths.
- **Lists are labels, not ground truth.** Strength is `circumstantial`: a
program reached a domain that a public list files under advertising or
tracking.
- **Redaction by construction.** OpenSnitch's event stream carries command
lines and process environments (which can hold secrets). Strawberry reads
the program path, pid and destination host in memory and keeps only the
program, the matched list domain, the list, the port and the time.
Arguments and environment are never stored or logged.
- **On when OpenSnitch is there, easy to turn off.** The installer adds
OpenSnitch's event logger when OpenSnitch is installed (maintainer decision,
2026-10-28), and EasyPrivacy is a default feed. `privacy_trackers=false`
in strawberry.conf turns it off (the installer then leaves OpenSnitch
alone). Contacts are visible to members of the `strawberry` group, like
findings; the telemetry records are root-only.
## Pieces
1. **Feed kind `trackers`.** Hosts files, plain domain lists, and adblock
whole-domain rules (`||host^`, optionally `$third-party`); rules with
other options, paths or exceptions are skipped. Matching is by domain
suffix (`a.b.tracker.example` matches `tracker.example`).
Default list: EasyPrivacy by the EasyList authors (GPL-3.0+ or
CC-BY-SA-3.0; downloaded at run time, attribution kept). Not a default:
Disconnect's lists (CC-BY-NC-SA, non-commercial).
2. **OpenSnitch events via a host-namespace relay.** OpenSnitch (>= 1.6)
streams connection events as JSON over TCP to a configured `remote` logger;
it cannot send to a Unix socket or leave fields out, and each event carries
the process's argv and environment. The daemon runs sandboxed
(`PrivateNetwork=true` + `RestrictAddressFamilies=AF_UNIX`), so it can neither
bind a loopback TCP port nor reach OpenSnitch's namespace. A small relay
bridges the two without weakening the daemon:
- **`strawberry opensnitch relay`** (unit `strawberry-trackerd.service`) runs
in the host network namespace with only `CAP_NET_BIND_SERVICE`. It binds
the loopback port below 1024 (so no other user can take the stream and its
environments), accepts a connection only from a root-owned socket (peer
looked up in `/proc/net/tcp`), parses the event keeping only program, uid,
destination host/ip/port, protocol and action, and **drops argv and
environment before anything leaves the relay**. It bounds clients (4),
object size (256 KiB) and buffered bytes (1 MiB).
- It forwards each redacted tuple to the **daemon's AF_UNIX ingest socket**
(`opensnitch_ingest_socket`, default `/run/strawberry/trackers.sock`), which
the daemon *can* open under its sandbox. The daemon accepts only a root peer
(`SO_PEERCRED`) and matches the host against the tracker lists it holds.
Contacts are bounded at 20000 program x domain keys.
So secrets never reach the daemon (redaction happens in the relay, before the
boundary), and the daemon keeps its full network sandbox. `strawberry
opensnitch enable-events` points OpenSnitch's logger at the relay
(`opensnitch_events`, default `127.0.0.1:979`); the installer runs it and
starts `strawberry-trackerd`. `privacy_trackers=false` disables both ends.
Relaxing the daemon sandbox or systemd socket activation were considered and
rejected (they lose the network isolation or the root-peer check).
3. **Output.** A root-only `tracker_contact` telemetry record per program and
domain (rate-limited: first contact, then counts per hour), a `privacy`
block in status, and `strawberry privacy trackers` (per program: list
domains contacted, counts, first and last seen).
macOS: the same feeds, contacts and output. There is no network sandbox to work
around, so the daemon (root) reads Little Snitch's `log-traffic --stream`
directly — no relay or ingest socket. `littlesnitch_cli` sets the CLI path
(default `/Applications/Little Snitch.app/Contents/Components/littlesnitch`); it
needs Little Snitch's "Allow access via Terminal" (`allowCommandLineAccess`)
turned on. Little Snitch's CSV has no argv/environment, so the redaction
guarantee holds structurally there too; the parser keeps only program, uid,
destination host/ip/port and protocol for outbound rows.