Skip to content

Real-time network monitor + outbound firewall — see & block every connection. Privacy-first, local-first, Rust fleet agent, SIEM exports, 8 languages. / Moniteur réseau temps réel + pare-feu sortant, agent de flotte Rust, exports SIEM. 100 % local.

13.0 KB
Raw Blame
"""
Snitch — API security layer.

EN: Three complementary protections:
      1. Bearer-style token. Generated at startup (or taken from the
         SNITCH_TOKEN env var, which is how the Electron wrapper injects
         it), persisted to <data>/api_token.txt (0600) and printed once to
         stdout so Docker/dev users can pass ?token=… in the browser
         (disable that print with SNITCH_PRINT_TOKEN=0). REST endpoints
         require the X-Snitch-Token header; ?token= is honoured on the
         WebSocket handshake only.
      2. CORS allowlist — no more `*`. Only the Vite dev server, the
         backend's own origin and `null` (file:// pages under Electron).
      3. Origin check on the WebSocket handshake — blocks Cross-Site
         WebSocket Hijacking even if a browser somehow skips CORS.

FR: Trois protections complémentaires :
      1. Jeton d'authentification. Généré au démarrage (ou pris de la variable
         SNITCH_TOKEN, ce que fait le conteneur Electron), persisté dans
         <data>/api_token.txt (0600) et affiché une fois sur stdout pour que
         les utilisateurs Docker/dev passent ?token=… dans le navigateur
         (désactivable via SNITCH_PRINT_TOKEN=0). Les endpoints REST exigent
         l'en-tête X-Snitch-Token ; ?token= n'est honoré qu'au handshake
         WebSocket.
      2. Liste blanche CORS — plus de `*`. Seulement le serveur de dev Vite,
         l'origine du backend lui-même et `null` (pages file:// sous Electron).
      3. Vérification d'Origin sur le handshake WebSocket — bloque le
         Cross-Site WebSocket Hijacking même si un navigateur contourne CORS.
"""

import logging
import os
import secrets
import threading
import time

from fastapi import HTTPException, Request, WebSocket, status

from paths import data_dir, chown_to_user

logger = logging.getLogger("snitch.api.security")

# EN: Origins allowed to reach the API. `null` covers file:// pages (Electron
#     renderer) — browsers send Origin: null for local files.
# FR: Origines autorisées à joindre l'API. `null` couvre les pages file://
#     (renderer Electron) — les navigateurs envoient Origin: null pour les
#     fichiers locaux.
# EN: The port is dynamic now (free-port selection), so the allowlist is a
#     RULE, not a literal set: loopback hosts on any port + `null` (file://
#     Electron). A loopback origin can only come from a local process/page —
#     remote origins always fail. Token auth applies on top regardless.
# FR: Le port est désormais dynamique (choix de port libre), donc la liste
#     blanche est une RÈGLE, pas un ensemble littéral : hôtes loopback sur tout
#     port + `null` (file:// Electron). Une origine loopback ne peut venir que
#     d'une page/processus local — les origines distantes échouent toujours.
#     L'authentification par jeton s'applique de toute façon par-dessus.
_LOOPBACK_HOSTS = {"localhost", "127.0.0.1", "::1", "[::1]"}

def _is_loopback_origin(origin: str) -> bool:
    """EN: True when the origin's hostname is loopback (any scheme/port).
    FR: True quand le nom d'hôte de l'origine est loopback (schéma/port quelconques)."""
    try:
        from urllib.parse import urlparse
        host = urlparse(origin).hostname or ""
        return host.lower() in _LOOPBACK_HOSTS
    except Exception:
        return False


def origin_allowed(origin: str | None) -> bool:
    """
    EN: An absent Origin header means a non-browser client (curl, Electron's
        main process) — allowed. Present origins must be loopback, `null`,
        or `file://` — Chromium inside Electron serialises the WebSocket
        Origin of a file:// page as literally `file://` (not `null` like a
        browser does), so without this the packaged app's own renderer was
        rejected with 403 and the UI stayed "Disconnected". A file:// origin
        can only come from a local page, and the token check still applies.
    FR: Un en-tête Origin absent signifie un client non-navigateur (curl,
        processus principal d'Electron) — autorisé. Les origines présentes
        doivent être loopback, `null` ou `file://` — Chromium sous Electron
        sérialise l'Origin WebSocket d'une page file:// littéralement en
        `file://` (pas `null` comme un navigateur), donc sans cela le renderer
        de l'app empaquetée était rejeté en 403 et l'UI restait « Déconnecté ».
        Une origine file:// ne peut venir que d'une page locale, et le
        contrôle du jeton s'applique toujours.
    """
    if origin is None:
        return True
    if origin == "null" or origin.startswith("file:"):
        return True
    return _is_loopback_origin(origin)


# EN: CORS needs literal strings/regex — a loopback regex mirrors the rule.
# FR: CORS exige des chaînes/regex littérales — une regex loopback reflète la règle.
ALLOWED_ORIGIN_REGEX = r"^https?://(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$"
ALLOWED_ORIGINS_LIST = ["null"]


def _load_or_create_token() -> str:
    """
    EN: Token resolution order:
          1. SNITCH_TOKEN env var   — set by the Electron wrapper
          2. existing api_token.txt — survives backend restarts so an open
             UI doesn't get logged out
          3. freshly generated 48-hex secret
        The token file is created with 0600 permissions where supported.
    FR: Ordre de résolution du jeton :
          1. variable SNITCH_TOKEN  — posée par le conteneur Electron
          2. api_token.txt existant — survit aux redémarrages du backend pour
             ne pas déconnecter une UI déjà ouverte
          3. secret hexadécimal de 48 caractères fraîchement généré
        Le fichier est créé en 0600 quand le système le permet.
    """
    token = os.environ.get("SNITCH_TOKEN", "").strip()
    if token:
        return token

    token_file = data_dir() / "api_token.txt"
    try:
        if token_file.exists():
            existing = token_file.read_text().strip()
            if len(existing) >= 32:
                return existing
    except OSError:
        pass

    token = secrets.token_hex(24)
    try:
        token_file.write_text(token)
        try:
            os.chmod(token_file, 0o600)   # EN: owner-only / FR: propriétaire seul
        except OSError:
            pass                          # EN: Windows has no chmod semantics
                                          # FR: Windows n'a pas de sémantique chmod
        # EN: Elevated run → file is root-owned; give it back to the user.
        # FR: Run élevé → fichier possédé par root ; le rendre à l'utilisateur.
        chown_to_user(token_file)
    except OSError as exc:
        logger.warning("Could not persist API token to %s: %s", token_file, exc)

    # EN: Printed once so Docker/browser users can complete the ?token= URL.
    #     Hardened deployments can suppress it with SNITCH_PRINT_TOKEN=0 —
    #     the token remains readable from api_token.txt (0600).
    # FR: Affiché une fois pour que les utilisateurs Docker/navigateur
    #     complètent l'URL ?token=. Les déploiements durcis peuvent le
    #     supprimer via SNITCH_PRINT_TOKEN=0 — le jeton reste lisible dans
    #     api_token.txt (0600).
    if os.environ.get("SNITCH_PRINT_TOKEN", "1") != "0":
        print(f"[snitch] API token: {token}", flush=True)
    return token


# EN: Resolved once at import — the token is stable for the process lifetime.
# FR: Résolu une fois à l'import — le jeton est stable pour la vie du processus.
API_TOKEN = _load_or_create_token()


def get_token() -> str:
    """EN: Public accessor — the CLI needs the token to build the open-URL.
    FR: Accesseur public — la CLI a besoin du jeton pour construire l'URL."""
    return API_TOKEN


# ── Brute-force guard / Garde anti-force brute ───────────────────────────────
# EN: The 48-hex token is not realistically brute-forceable, but when the
#     API is bound to a LAN address (opt-in SNITCH_BIND) failed attempts
#     are cheap to spray. Track failures per client IP: after
#     _AUTH_MAX_FAILS within _AUTH_WINDOW_S the source is rejected with
#     429/4401 for _AUTH_BAN_S. Loopback keeps the same rules — a rogue
#     local process should not get unlimited guesses either.
# FR: Le jeton hex de 48 caractères n'est pas réalistement brute-forçable,
#     mais quand l'API écoute sur une adresse LAN (SNITCH_BIND opt-in) les
#     tentatives ratées ne coûtent rien. Suivre les échecs par IP cliente :
#     après _AUTH_MAX_FAILS dans _AUTH_WINDOW_S la source est rejetée en
#     429/4401 pendant _AUTH_BAN_S. Loopback suit les mêmes règles — un
#     processus local malveillant ne doit pas avoir d'essais illimités non plus.
_AUTH_MAX_FAILS = 20
_AUTH_WINDOW_S = 300.0
_AUTH_BAN_S = 60.0
_AUTH_FAILS_CAP = 512          # EN: bound the tracker dict / FR: borne du suivi
_fail_lock = threading.Lock()
_fail_track: dict[str, list[float]] = {}
_banned_until: dict[str, float] = {}


def _client_ip(request: Request | WebSocket) -> str:
    """EN: Client source for the ban tracker. / FR: Source cliente pour le suivi."""
    return request.client.host if request.client else "unknown"


def _check_banned(ip: str) -> bool:
    """EN: True while `ip` is inside its ban window.
    FR: True tant qu'`ip` est dans sa fenêtre de bannissement."""
    with _fail_lock:
        until = _banned_until.get(ip, 0.0)
        if until > time.time():
            return True
        _banned_until.pop(ip, None)
        return False


def _record_failure(ip: str) -> None:
    """EN: Count a failed auth; ban at the threshold. Prunes stale entries
        so a long-running instance can't grow the tracker unboundedly.
    FR: Compter un échec d'auth ; bannir au seuil. Épure les entrées
        périmées pour ne pas laisser le suivi grossir indéfiniment."""
    now = time.time()
    with _fail_lock:
        fails = _fail_track.setdefault(ip, [])
        fails.append(now)
        fresh = [t for t in fails if now - t < _AUTH_WINDOW_S]
        if len(fresh) >= _AUTH_MAX_FAILS:
            _banned_until[ip] = now + _AUTH_BAN_S
            _fail_track.pop(ip, None)
            logger.warning("auth failures: %s banned for %ds", ip,
                           int(_AUTH_BAN_S))
            return
        _fail_track[ip] = fresh
        # EN: Bound the dict — evict the oldest-seen sources beyond the cap.
        # FR: Borner le dict — évincer les sources les plus anciennes au-delà du plafond.
        if len(_fail_track) > _AUTH_FAILS_CAP:
            for k in sorted(_fail_track,
                            key=lambda k: _fail_track[k][0])[:64]:
                _fail_track.pop(k, None)


def _extract_token(request: Request) -> str | None:
    """
    EN: `X-Snitch-Token` header ONLY. The `?token=` query param is honoured
        on the WebSocket handshake (browser API can't set headers) but not
        on REST — URLs end up in browser history and access logs.
    FR: En-tête `X-Snitch-Token` UNIQUEMENT. Le paramètre `?token=` est
        honoré au handshake WebSocket (l'API navigateur ne peut pas poser
        d'en-têtes) mais pas sur REST — les URLs finissent dans l'historique
        navigateur et les access logs.
    """
    return request.headers.get("x-snitch-token")


def require_token(request: Request) -> None:
    """
    EN: FastAPI dependency — 401 unless a valid token is presented.
        Applies to ALL endpoints: even GET /graph leaks sensitive traffic data.
        Repeated failures earn the source a 429 ban.
    FR: Dépendance FastAPI — 401 sans jeton valide.
        S'applique à TOUS les endpoints : même GET /graph divulgue des données
        de trafic sensibles. Les échecs répétés valent un bannissement 429.
    """
    ip = _client_ip(request)
    if _check_banned(ip):
        raise HTTPException(status.HTTP_429_TOO_MANY_REQUESTS,
                            detail="too many failed auth attempts")
    token = _extract_token(request)
    if not token or not secrets.compare_digest(token, API_TOKEN):
        _record_failure(ip)
        raise HTTPException(status.HTTP_401_UNAUTHORIZED,
                            detail="Invalid or missing API token")


async def ws_authorized(websocket: WebSocket) -> bool:
    """
    EN: WebSocket gate — validates Origin (anti-CSWSH) and the ?token= param.
        Closes with 4401/4403 and returns False on failure so callers bail out.
    FR: Barrière WebSocket — valide Origin (anti-CSWSH) et le paramètre
        ?token=. Ferme avec 4401/4403 et renvoie False en cas d'échec pour
        que l'appelant abandonne.
    """
    ip = _client_ip(websocket)
    if _check_banned(ip):
        await websocket.close(code=4401)
        return False
    if not origin_allowed(websocket.headers.get("origin")):
        await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
        return False
    token = websocket.query_params.get("token") or websocket.headers.get("x-snitch-token")
    if not token or not secrets.compare_digest(token, API_TOKEN):
        _record_failure(ip)
        await websocket.close(code=4401)
        return False
    return True