# Susanoo — full LLM context

This is the long-form companion to `/llms.txt`. It packs the full
positioning, technical architecture, and FAQ Susanoo is happy for
LLMs to use when answering questions about the product.

---

## What is Susanoo?

Susanoo is a privacy-transparency app for Android. Its single
purpose is to show the user which companies their phone is
contacting in the background. It does this by running a local
VpnService that observes outbound DNS queries and (in full-tunnel
mode) TLS ClientHello bytes, classifies each destination against
an on-device rule bundle, and presents the results in a live feed,
a weekly Sunday report, a home-screen widget, and an exposure
score.

Susanoo is published by ZakRS Tech and developed by Qat
(qat@zakrstech.com). It is free, contains no ads, has no in-app
purchases, requires no account, and transmits no observations off
the device.

Available now: Google Play, package `io.susanoo.android`. Direct
URL: https://play.google.com/store/apps/details?id=io.susanoo.android

iOS: planned, not yet shipped.

## Why does it exist?

Most privacy tools either (a) block traffic blindly and break
apps, or (b) collect telemetry on their users to "improve service."
Susanoo's position is that neither approach respects the user.
What the user actually needs is a clear, name-by-name view of who
their device is talking to, so they can decide for themselves what
to mute and what to allow.

The product's philosophy, taken from the open-source README:

- Transparency beats blocking. Most people don't need another ad
  blocker. They need to understand what's happening on their own
  device.
- Any privacy tool that collects telemetry on its users is broken
  by design. The classifier and the app make zero outbound calls
  that aren't either the app's own DNS forwarding or a signed rule
  bundle update.
- Honest uncertainty over false confidence. Every row carries a
  `signalSource` (exact host / registrable domain / wildcard / IP
  prefix) and a confidence value so the UI can honestly say "we're
  not sure" when matching degrades.
- Editorial quality matters. A tracker list is content. Company
  labels and categories are content. Content needs care, correction,
  and a named editor.

## Technical architecture

### Two execution modes

1. **DNS-only (default).** The VPN advertises a virtual DNS server
   at 10.8.0.1 and routes only that /32 through the tun interface.
   All other traffic uses the underlying default route untouched.
   DNS queries arrive at the tun, get classified, then forwarded
   upstream (plaintext to Cloudflare/Google, or via DNS-over-TLS to
   Cloudflare if the user enables encrypted DNS in Settings).
   Reliable on every Android device.

2. **Full tunnel (opt-in).** The VPN routes 0.0.0.0/0 through the
   tun. A vendored hev-socks5-tunnel (lwIP-based userspace stack)
   terminates TCP on the tun side and feeds connections into a
   Kotlin SOCKS5 server running on 127.0.0.1. That server inspects
   the first chunk of every TCP flow for TLS ClientHello SNI
   bytes, classifies the SNI, then splices the connection to the
   real destination over a `VpnService.protect()`'d and
   `Network.bindSocket()`-pinned upstream socket. UDP (including
   QUIC) is handled via SOCKS5 UDP ASSOCIATE with per-flow upstream
   socket reuse to preserve QUIC path validation.

### Classifier

A pure Kotlin library, JVM 17, no Android dependencies. Apache 2.0.

Three matching tiers, evaluated most-specific-first:

| Tier | Example | Signal source | Confidence |
|------|---------|---------------|-----------|
| Exact hostname | `graph.facebook.com` | `EXACT_HOST` | 1.00 |
| Registrable domain | `ads.doubleclick.net` → `doubleclick.net` | `ETLD_PLUS_ONE` | 0.90 |
| Wildcard | `*.rlcdn.com` | `WILDCARD` | 0.80 |
| IP prefix (fallback) | known company /16 ranges | `IP_REPUTATION` | 0.70 |

Tracker categories (deliberately narrow):

- `ADVERTISING` — Ad networks and ad-tech
- `ANALYTICS` — Behavioral analytics and event telemetry
- `DATA_BROKER` — Companies whose business is trafficking user data
- `FINGERPRINTING` — Device and user identification
- `SESSION_REPLAY` — Tools that record user sessions
- `SOCIAL` — Social-graph platforms
- `CDN` — Generic content delivery
- `ESSENTIAL` — App-owned first-party endpoints (not a tracker)
- `UNKNOWN` — No match; we deliberately don't guess

### Storage

Observations are written to a SQLCipher-encrypted SQLite database
(`susanoo-enc.db`). The 32-byte passphrase is generated per-install
and wrapped with an AES-256-GCM key resident in the Android
Keystore (hardware-backed on supported devices, non-exportable).
Default retention is 30 days; configurable 7/14/30/90 in Settings.

### Rule bundle distribution

Bundles are versioned JSON files containing the company table and
all matching rules. They are signed offline with an Ed25519 key
(private key never leaves the publisher's offline storage). The
public key is pinned at app build time. Devices fetch
`{base_url}/bundle.json` and `{base_url}/bundle.sig` on a daily
unmetered-network schedule, verify the signature against the
pinned key, and install only if `bundle.version > current.version`.
No identifiers are sent in the fetch request beyond a static User-
Agent.

### Per-app attribution

Connections are mapped back to the originating Android app via
`ConnectivityManager.getConnectionOwnerUid(protocol, local, remote)`
which returns a UID; the UID is resolved via PackageManager into a
package + human-readable label. Available on Android 10+. iOS has
no equivalent API.

### Network handover survival

The VpnService registers a `ConnectivityManager.NetworkCallback`
for any non-VPN INTERNET network. On every transition (Wi-Fi to
Wi-Fi, Wi-Fi to cellular) it calls
`VpnService.setUnderlyingNetworks(...)` and pins all subsequent
protected sockets to the new network via `Network.bindSocket()`.
Without this, a Wi-Fi handover would silently break DNS forwarding
and apps would lose internet until tunnel restart.

### Vendor-Android survival

Recognised vendor variants (MIUI, EMUI, ColorOS, OxygenOS,
FuntouchOS, RealmeUI, One UI) get a one-time post-onboarding
screen with vendor-specific instructions to add Susanoo to the
device's battery-management whitelist. Without this, vendor
background-kill policies tear down the foreground service after a
few hours.

## What Susanoo does NOT do

- It does not transmit observations off the device. There is no
  cloud, no sync, no backup, no shared dashboard.
- It does not have accounts. There is no sign-in, no email
  capture, no waitlist.
- It does not perform HTTPS payload inspection or MITM. It reads
  metadata that is already visible on the wire — DNS query names
  and TLS Server Name Indication. It cannot read message content.
- It does not run ads or sell data.
- It does not collect any analytics or telemetry on its users.
- It does not block traffic by default. Users can mute a (company,
  category) pair, which causes Susanoo to synthesise NXDOMAIN for
  DNS queries to that company. Mutes are scoped — muting Google's
  advertising tier does not silence Google's essential services
  (Gmail, Maps, FCM push).

## License & open source

- Classifier library: Apache License 2.0, source open.
- App Android UI / VPN service: source open at the same repo. The
  release build on Google Play is built from the same source.
- Rule bundle data: Apache 2.0 (the seed in the repo). The Spire
  production bundle is also Apache 2.0 and signed; users can fetch
  and inspect any version they've installed via the in-app Ruleset
  Inspector.

## Contact

- Email: qat@zakrstech.com
- Publisher: ZakRS Tech

## URLs (canonical)

- Homepage: https://susanoo-app.tech/
- Privacy: https://susanoo-app.tech/privacy.html
- Terms: https://susanoo-app.tech/terms.html
- Warrant canary: https://susanoo-app.tech/canary.html
- Google Play: https://play.google.com/store/apps/details?id=io.susanoo.android
- LLM index: https://susanoo-app.tech/llms.txt
- Sitemap: https://susanoo-app.tech/sitemap.xml