aixisstudio/Snitch

Snitch is a real-time network traffic visualizer. See every connection your computer makes — who it talks to, where they are, and which app is responsible.

The entire interface is available in English and French: use the EN / FR toggle in the top-right toolbar.

• vs Little Snitch / Lulu — those are macOS firewalls that block connections; Snitch visualizes and explains traffic, is cross-platform, free and open-source.
• vs GlassWire — Snitch is free, open-source (AGPL), requires no account and makes zero outbound calls; even geolocation is offline.
• vs Wireshark — Snitch gives a live, high-level overview anyone can read, instead of raw packet dissection.
• vs cloud-based monitors — everything runs on 127.0.0.1 behind a token; your traffic data never leaves the machine.

Or grab the latest release: github.com/aixisstudio/Snitch/releases

macOS first run / Premier lancement macOS — Snitch is ad-hoc signed, not notarized (no paid Apple Developer ID). The brew install --cask above removes the quarantine flag for you. For the manual zip: right-click → Open, or run xattr -dr com.apple.quarantine /Applications/Snitch.app. On first launch Snitch asks for your admin password once — packet capture requires it, same as tcpdump/Wireshark; the UI itself stays unprivileged.

FR — Snitch est signé ad-hoc, pas notarisé (pas de Developer ID payant). Le brew install --cask ci-dessus retire le drapeau de quarantaine pour vous. Pour le zip manuel : clic droit → Ouvrir, ou xattr -dr com.apple.quarantine /Applications/Snitch.app. Au premier lancement, Snitch demande le mot de passe admin une fois — la capture de paquets l'exige, comme tcpdump/Wireshark ; l'UI reste non privilégiée.

• API token — every REST endpoint and the WebSocket require a token. Electron generates it per launch; in Docker/browser it's printed once in the backend logs and stored in data/api_token.txt. Open the UI with http://localhost:8000/?token=<TOKEN> (or enter it when prompted).
• Loopback-only by default — the API binds 127.0.0.1 in every mode. Set SNITCH_BIND=0.0.0.0 only if you explicitly want LAN access (token auth still applies).
• CORS/WebSocket origin allowlist — only localhost:5173, the backend's own origin and Electron file:// pages may connect.
• Geolocation is offline-only — there is no online lookup. DB-IP Lite (CC BY 4.0) ships gzip'd in backend/data/geo/ and is auto-extracted into <data_dir>/geo/ on first launch — geo works out of the box, zero network calls. You may still drop newer GeoLite2-City.mmdb/GeoLite2-ASN.mmdb (MaxMind) into <data_dir>/geo/, or download a fresh DB-IP Lite from the Settings panel (explicit consent, the only possible outbound call).
• All data stays local — snitch.db (24 h sliding window, configurable via retention_hours setting) and data/logs/snitch.log never leave the machine. No telemetry. The only possible outbound call is the opt-in DB-IP Lite download (Settings → "Download DB-IP Lite"), which requires an explicit click.
• Settings persist — port filters, excluded processes, the IP whitelist, language and retention are stored in SQLite and restored on restart.
• Alert suppression — each alert has an "Ignore this type/host" action; suppression rules are persisted (alert_suppressions table), applied before alerts are emitted or logged, and survivable across restarts via POST /alerts/ignore / DELETE /alerts/ignore / GET /alerts/ignore.
• History — per-minute per-host and per-process byte/packet aggregates are kept in SQLite (host_history, process_history) for the retention window, powering the per-application view and GET /history/host/{ip} / GET /history/process/{name}.
• Diagnostics — GET /diagnostics returns a JSON snapshot of the runtime (capture state, geo DB status, interface, versions, paths) with no secrets; the Settings panel can export it or open the log directory (Electron).
• LAN devices are discovered passively from the system ARP table — no active broadcast scanning. Device names are learned from what devices broadcast themselves: mDNS *.local (Apple/Linux), LLMNR & NetBIOS names (Windows), DHCP hostname options, plus the full offline IEEE OUI vendor table, and your gateway is auto-detected as the router.
• See docs/threat-model.md for the full threat model.

The Docker deployment is for Linux users who want to run Snitch without installing anything beyond Docker. Packet capture works via network_mode: host — the container sees real host traffic.

Note: Docker Desktop on Mac/Windows runs inside a VM and cannot capture traffic from the host. Use the Electron app on those platforms.

# Clone and enter the repo / Cloner puis entrer dans le dépôt
git clone <your-repo-url> snitch
cd snitch

# Optional: place your MaxMind GeoLite2-City.mmdb in data/ for offline geolocation
# Optionnel : placez votre GeoLite2-City.mmdb dans data/ pour la géolocalisation hors ligne
mkdir -p data

# Build and run (requires Docker + root/sudo for raw socket capture)
# Construire et lancer (Docker + root/sudo requis pour la capture)
sudo docker compose up --build

Get the API token (printed once at startup, or cat data/api_token.txt), then open http://localhost:8000/?token=TOKEN in your browser.

To run in the background: sudo docker compose up -d --build

Docker limitations:

• Process attribution is limited to container processes (host PIDs are not shared by default)
• LAN scanner may be unavailable on some network configurations

Requirements:

• Python 3.11+
• Node.js 18+
• Npcap installed (Windows only)
• Administrator/root terminal for the backend (raw packet capture)

Demo mode / Mode démo — run the backend with SNITCH_DEMO=1 to feed synthetic traffic through the real pipeline: no root, no libpcap, no real packets touched. Ideal for screenshots, tests and previews. Lancez le backend avec SNITCH_DEMO=1 pour injecter un trafic synthétique dans le pipeline réel — ni root ni libpcap ni paquets réels.

# Backend (admin terminal) — API at http://127.0.0.1:8000
cd backend
pip install -r requirements.txt
python run_backend.py   # prints the API token once

# Frontend (separate terminal) — UI at http://localhost:5173/?token=TOKEN
cd frontend
npm install
npm run dev

# Electron (optional, admin terminal) — token is injected automatically
cd electron
npm install
set VITE_DEV=1   # Windows
# VITE_DEV=1     # macOS/Linux shell
npx electron .

Tests:

cd backend && pip install -r requirements-dev.txt && python -m pytest tests/ -v
cd frontend && npm test

# 1 — Compile backend (PyInstaller)
cd backend
pip install pyinstaller
pyinstaller backend.spec --distpath ../dist/backend

# 2 — Build frontend
cd frontend
npm run build

# 3 — Build Electron installer
cd electron
npm run build:dir

snitch/
├── backend/       Python FastAPI + libpcap capture engine (ctypes, own parser)
├── frontend/      React + D3.js UI (EN/FR)
├── electron/      Electron wrapper (main, splash, preload)
├── data/          Runtime data (SQLite DB, .mmdb geo DBs in geo/)
└── dist/          Compiled output (backend exe, installer)

Snitch est un visualiseur de trafic réseau en temps réel. Voyez chaque connexion que votre ordinateur établit — à qui il parle, où se trouvent les serveurs, et quelle application est responsable.

Toute l'interface est disponible en français et en anglais : utilisez le sélecteur EN / FR dans la barre d'outils en haut à droite.

• vs Little Snitch / Lulu — ce sont des pare-feux macOS qui bloquent les connexions ; Snitch visualise et explique le trafic, est multiplateforme, gratuit et open-source.
• vs GlassWire — Snitch est gratuit, open-source (AGPL), sans compte et n'effectue aucun appel sortant ; même la géolocalisation est hors ligne.
• vs Wireshark — Snitch offre une vue d'ensemble en direct lisible par tous, plutôt qu'une dissection brute de paquets.
• vs les moniteurs cloud — tout tourne sur 127.0.0.1 derrière un jeton ; vos données de trafic ne quittent jamais la machine.

Ou récupérez la dernière release : github.com/aixisstudio/Snitch/releases

Premier lancement macOS — Snitch est signé ad-hoc, pas notarisé. Le brew install --cask retire la quarantaine pour vous. Pour le zip manuel : clic droit → Ouvrir, ou xattr -dr com.apple.quarantine /Applications/Snitch.app. Premier lancement : mot de passe admin demandé une fois (la capture de paquets l'exige, comme tcpdump/Wireshark).

• Jeton API — chaque endpoint REST et le WebSocket exigent un jeton. Electron le génère à chaque lancement ; sous Docker/navigateur il est affiché une fois dans les logs du backend et stocké dans data/api_token.txt. Ouvrez l'UI via http://localhost:8000/?token=<JETON> (ou saisissez-le à l'invite).
• Loopback uniquement par défaut — l'API écoute sur 127.0.0.1 dans tous les modes. Ne mettez SNITCH_BIND=0.0.0.0 que pour un accès LAN explicite (le jeton reste exigé).
• Liste blanche CORS/Origin WebSocket — seuls localhost:5173, l'origine propre du backend et les pages file:// d'Electron peuvent se connecter.
• Géolocalisation 100 % hors ligne — aucune recherche en ligne. DB-IP Lite (CC BY 4.0) est embarquée gzipée dans backend/data/geo/ et auto-extraite vers <data_dir>/geo/ au premier lancement — la géo fonctionne d'emblée, zéro appel réseau. Vous pouvez toujours déposer des GeoLite2-City.mmdb/GeoLite2-ASN.mmdb (MaxMind) plus récents dans <data_dir>/geo/, ou télécharger une DB-IP Lite fraîche depuis Réglages (consentement explicite, seul appel sortant possible).
• Toutes les données restent locales — snitch.db (fenêtre glissante de 24 h, configurable via le réglage retention_hours) et data/logs/snitch.log ne quittent jamais la machine. Pas de télémétrie. Le seul appel sortant possible est le téléchargement opt-in de DB-IP Lite (Réglages → « Télécharger DB-IP Lite »), qui exige un clic explicite.
• Réglages persistés — filtres de ports, processus exclus, whitelist IP, langue et rétention sont stockés dans SQLite et restaurés au redémarrage.
• Suppression d'alertes — chaque alerte offre « Ignorer ce type/cet hôte » ; les règles sont persistées (alert_suppressions), appliquées avant émission, et gérables via POST /alerts/ignore, DELETE /alerts/ignore, GET /alerts/ignore.
• Historique — les agrégats octets/paquets par minute, par hôte et par processus sont conservés dans SQLite (host_history, process_history) sur la fenêtre de rétention, et alimentent la vue par application ainsi que GET /history/host/{ip} et GET /history/process/{nom}.
• Diagnostic — GET /diagnostics renvoie un instantané JSON du runtime (état de capture, géo, interface, versions, chemins) sans secrets ; le panneau Réglages peut l'exporter ou ouvrir le dossier des logs (Electron).
• Appareils LAN découverts passivement via la table ARP système — aucun scan broadcast actif. Les noms sont appris de ce que les appareils diffusent eux-mêmes : mDNS *.local (Apple/Linux), LLMNR et noms NetBIOS (Windows), option hostname DHCP, plus la table de fabricants IEEE OUI complète hors ligne ; votre passerelle est détectée automatiquement comme routeur.
• Voir docs/threat-model.md pour le modèle de menace complet.

Le déploiement Docker est destiné aux utilisateurs Linux qui veulent lancer Snitch sans rien installer d'autre que Docker. La capture fonctionne via network_mode: host — le conteneur voit le vrai trafic de l'hôte.

Remarque : Docker Desktop sur Mac/Windows tourne dans une VM et ne peut pas capturer le trafic de l'hôte. Utilisez l'application Electron sur ces plateformes.

git clone <url-de-votre-depot> snitch
cd snitch
mkdir -p data
sudo docker compose up --build

Récupérez le jeton API (affiché une fois au démarrage, ou cat data/api_token.txt), puis ouvrez http://localhost:8000/?token=JETON dans votre navigateur. En arrière-plan : sudo docker compose up -d --build

Limites Docker :

• L'attribution de processus est limitée aux processus du conteneur
• Le scanner LAN peut être indisponible selon la configuration réseau

Prérequis : Python 3.11+, Node.js 18+, Npcap (Windows), terminal administrateur pour le backend.

# Backend (terminal admin)
cd backend
pip install -r requirements.txt
python run_backend.py

# Frontend (autre terminal)
cd frontend
npm install
npm run dev

# Electron (optionnel) — le jeton est injecté automatiquement
cd electron
npm install
VITE_DEV=1 npx electron .

Tests :

cd backend && pip install -r requirements-dev.txt && python -m pytest tests/ -v
cd frontend && npm test

snitch/
├── backend/       Moteur de capture Python FastAPI + libpcap (ctypes, parseur maison)
├── frontend/      Interface React + D3.js (FR/EN)
├── electron/      Conteneur Electron (main, splash, preload)
├── data/          Données d'exécution (SQLite, bases .mmdb dans geo/)
└── dist/          Sortie compilée (exe backend, installateur)

AGPL v3 — see / voir LICENSE.

EN: Free to use, study, and modify. Derivative works must remain open source under AGPL v3. FR: Libre d'utilisation, d'étude et de modification. Les œuvres dérivées doivent rester open source sous AGPL v3.