Usage Guide

Usage Guide

🇫🇷 Version française : Guide d'utilisation

First launch

1. Start Snitch (see Installation).
2. The backend generates a per-launch API token — in the Electron app it is injected automatically; in Docker/browser it is printed once in the backend logs (and stored in data/api_token.txt).
3. The UI opens on http://127.0.0.1:8000/?token=<TOKEN> — if prompted, paste the token.
4. Grant elevated privileges when asked → live capture starts within seconds.

Demo mode — try without root

cd backend
SNITCH_DEMO=1 python run_backend.py

Demo mode feeds synthetic traffic through the real pipeline — same UI, same alerts, zero packets touched. Ideal for evaluating the interface, taking screenshots, or running on a machine where you can't get root.

Interface tour

Area	What it shows
Force graph	Your machine at the center; every remote host as a node; edges are live connections. Node size follows traffic volume.
World map	Geolocated IPs as arcs on an interactive globe (D3 + TopoJSON). Geolocation is 100 % offline — bundled DB-IP Lite.
Timeline	Sliding 15/30/60-minute history, stored in local SQLite (default 24 h retention, configurable).
Per-app view	Per-process destinations, volumes and 60-min history — which app talks to whom.
Bandwidth	Live MB/s sparkline.
LAN perimeter	Devices discovered passively from the system ARP table — no broadcast scans. Names learned from mDNS/LLMNR/NetBIOS/DHCP + offline IEEE OUI vendor table.
Alerts	Anomaly detection: port scans, beaconing, volume spikes, potential exfiltration. Each alert offers Ignore this type/host — suppression rules persist.
Privacy score	Real-time score of your outgoing exposure, based on tracker matches and traffic patterns.
Settings	Language (EN/FR), retention, port/process filters, IP whitelist, consent-gated DB-IP Lite download, diagnostics export.

The EN / FR toggle

Top-right toolbar: EN / FR — the entire interface, alerts and settings switch language in one click. The choice persists across restarts.

Tracker detection

Snitch flags connections to known trackers/CDNs using suffix-matched domain lists shipped as editable text files in backend/classifier/lists/ — add your own domains, restart, done.

API access

Everything the UI does is available via the API — same token (X-Snitch-Token header or ?token=). See API Reference.

curl -H "X-Snitch-Token: $TOKEN" http://127.0.0.1:8000/flows?limit=20

Keyboard & UI tips

• Click a graph node → host details + history.
• Click an alert → jump to the offending host/process.
• The whitelist in Settings excludes IPs from alerting (e.g., your NAS, printers).
• GET /diagnostics gives a no-secrets runtime snapshot — attach it when reporting a bug.