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

4.9 KiB

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.