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.

19.1 KB
Raw Blame
"""
EN: Windows Filtering Platform — USER-MODE backend (no driver, no kernel
    callout). Snitch talks to `fwpuclnt.dll` through ctypes and installs
    ordinary WFP *filters* at the ALE_AUTH_CONNECT layers — exactly what
    `netsh advfirewall` does under the hood, but with per-application
    precision (ALE_APP_ID), per-rule GUID keys and atomic deletes.
    A true *callout* (packet inspection inside the kernel) still needs a
    signed driver — that stays a research item; static block filters do not.

    Why this beats `netsh`:
      * `program=` accepts a name OR path here — we resolve names to the
        running exe and WFP matches the real ALE_APP_ID (canonicalized
        device path), not a display string,
      * filters are added/deleted individually by key (domain re-resolution
        becomes a true delta instead of delete+recreate),
      * IPv4 AND IPv6 connect layers are covered — netsh rules created
        through the advfirewall surface only ever saw IPv4 destinations.
    Requires an elevated process (same requirement as `netsh`); failures are
    reported as honest applied=False by the caller.

FR: Windows Filtering Platform — backend USER-MODE (sans driver ni callout
    noyau). Snitch dialogue avec `fwpuclnt.dll` via ctypes et installe des
    filtres WFP ordinaires sur les couches ALE_AUTH_CONNECT — exactement ce
    que fait `netsh advfirewall` en dessous, mais avec une précision par
    application (ALE_APP_ID), des clés GUID par règle et des suppressions
    atomiques. Un vrai *callout* (inspection dans le noyau) exige toujours
    un driver signé — reste en recherche ; les filtres statiques, non.
"""

from __future__ import annotations

import ctypes
import ipaddress
import os
import uuid
from typing import Optional

# ── GUID constants (Windows SDK fwpmk.h — values verified against
#    winsdk-10 + OpenVPN's wfp_block.c) / Constantes GUID ────────────────────
_LAYER_V4 = "c38d57d1-05a7-4c33-904f-7fbceee60e82"   # ALE_AUTH_CONNECT_V4
_LAYER_V6 = "4a72393b-319f-44bc-84c3-ba54dcb3b6b4"   # ALE_AUTH_CONNECT_V6
_COND_REMOTE_IP   = "b235ae9a-1d64-49b8-a44c-5ff3d9095045"
_COND_REMOTE_PORT = "c35a604d-d22b-4e1a-91b4-68f674ee674b"
_COND_ALE_APP_ID  = "d78e1e87-8644-4ea5-9437-d809ecefc971"
_SUBLAYER_UNIVERSAL = "eebecc03-ced4-4380-819a-2734397b2b74"

# ── Scalar constants / Constantes scalaires ──────────────────────────────────
RPC_C_AUTHN_WINNT        = 10
FWPM_SESSION_FLAG_DYNAMIC = 1
FWP_EMPTY                = 0
FWP_UINT8                = 1
FWP_UINT16               = 2
FWP_UINT32               = 3
FWP_UINT64               = 4          # EN: value passed by POINTER / FR: valeur par pointeur
FWP_BYTE_ARRAY16_TYPE    = 11         # EN: FWP_DATA_TYPE — fwpmtypes.h / FR: idem
FWP_BYTE_BLOB_TYPE       = 12
# EN: Compound types start at 0x100 — they are NOT small scalars.
#     (Found by the Windows integration job: 19/20 → FWP_E_INVALID_ENUMERATOR)
# FR: Les types composés commencent à 0x100 — pas de petits scalaires.
FWP_V4_ADDR_MASK         = 256
FWP_V6_ADDR_MASK         = 257
FWP_MATCH_EQUAL          = 0
FWP_ACTION_BLOCK         = 0x00001001  # EN: BLOCK | FLAG_TERMINATING / FR: BLOCK | TERMINATING
FWP_E_FILTER_NOT_FOUND   = 0x80320004
_NAME_PREFIX             = "SnitchRule-"


def _guid(text: str):
    """EN: Parse a {xxxxxxxx-…} GUID into the 16-byte Windows layout
    (first three fields little-endian). / FR: Convertit un GUID texte en
    layout mémoire Windows (trois premiers champs little-endian)."""
    return _GUID.from_buffer_copy(uuid.UUID(text).bytes_le)


def _rule_key(rid: str, tag: str = ""):
    """EN: Deterministic filter GUID per (rule, target) — delete-by-key then
    needs no stored handle and survives restarts.
    FR: GUID de filtre déterministe par (règle, cible) — la suppression par
    clé n'exige pas de handle stocké et survit aux redémarrages."""
    return _GUID.from_buffer_copy(
        uuid.uuid5(uuid.NAMESPACE_URL, f"snitch-wfp:{rid}:{tag}").bytes_le)


# ── ctypes structures — layouts match the SDK on Win64 exactly ──────────────
# EN: ctypes unions/structures replicate fwpmtypes.h; alignment is natural.
# FR: les unions/structures ctypes répliquent fwpmtypes.h ; alignement naturel.

class _GUID(ctypes.Structure):
    _fields_ = [("Data1", ctypes.c_uint32), ("Data2", ctypes.c_uint16),
                ("Data3", ctypes.c_uint16), ("Data4", ctypes.c_uint8 * 8)]


class _BYTE_BLOB(ctypes.Structure):
    _fields_ = [("size", ctypes.c_uint32), ("data", ctypes.c_void_p)]


class _DISPLAY_DATA(ctypes.Structure):
    _fields_ = [("name", ctypes.c_wchar_p), ("description", ctypes.c_wchar_p)]


class _VALUE_UNION(ctypes.Union):
    _fields_ = [("uint8", ctypes.c_uint8), ("uint16", ctypes.c_uint16),
                ("uint32", ctypes.c_uint32), ("uint64p", ctypes.c_void_p),
                ("blobp", ctypes.c_void_p), ("ba16p", ctypes.c_void_p),
                ("v4amp", ctypes.c_void_p), ("v6amp", ctypes.c_void_p),
                ("rangep", ctypes.c_void_p)]


class _VALUE(ctypes.Structure):
    _fields_ = [("type", ctypes.c_uint32), ("v", _VALUE_UNION)]


class _CONDITION(ctypes.Structure):
    _fields_ = [("fieldKey", _GUID), ("matchType", ctypes.c_uint32),
                ("conditionValue", _VALUE)]


class _ACTION_UNION(ctypes.Union):
    _fields_ = [("filterType", _GUID), ("calloutType", _GUID)]


class _ACTION(ctypes.Structure):
    _fields_ = [("type", ctypes.c_uint32), ("u", _ACTION_UNION)]


class _CTX_UNION(ctypes.Union):
    _fields_ = [("rawContext", ctypes.c_uint64),
                ("providerContextKey", _GUID)]


class _FILTER(ctypes.Structure):
    _fields_ = [("filterKey", _GUID), ("displayData", _DISPLAY_DATA),
                ("flags", ctypes.c_uint32), ("providerKey", ctypes.c_void_p),
                ("providerData", _BYTE_BLOB), ("layerKey", _GUID),
                ("subLayerKey", _GUID), ("weight", _VALUE),
                ("numFilterConditions", ctypes.c_uint32),
                ("filterCondition", ctypes.c_void_p), ("action", _ACTION),
                ("ctx", _CTX_UNION), ("reserved", ctypes.c_void_p),
                ("filterId", ctypes.c_uint64), ("effectiveWeight", _VALUE)]


class _SESSION(ctypes.Structure):
    _fields_ = [("sessionKey", _GUID), ("displayData", _DISPLAY_DATA),
                ("flags", ctypes.c_uint32),
                ("txnWaitTimeoutInMSec", ctypes.c_uint32),
                ("processId", ctypes.c_uint32), ("sid", ctypes.c_void_p),
                ("username", ctypes.c_wchar_p), ("kernelMode", ctypes.c_int32)]


class _V4_ADDR_MASK(ctypes.Structure):
    _fields_ = [("addr", ctypes.c_uint32), ("mask", ctypes.c_uint32)]


class _V6_ADDR_MASK(ctypes.Structure):
    _fields_ = [("addr", ctypes.c_uint8 * 16), ("prefixLength", ctypes.c_uint8)]


class _BYTE_ARRAY16(ctypes.Structure):
    _fields_ = [("byteArray16", ctypes.c_uint8 * 16)]


class WfpBackend:
    """EN: Minimal WFP user-mode client — open engine, add block filters with
    deterministic GUID keys, delete by key, purge stale Snitch filters by
    enumerating names. Everything is best-effort and never raises.
    FR: Client WFP user-mode minimal — ouvre le moteur, ajoute des filtres
    de blocage à clés GUID déterministes, supprime par clé, purge les
    filtres Snitch périmés en énumérant les noms. Au mieux, ne lève jamais."""

    def __init__(self):
        self._dll = None
        self._engine = ctypes.c_void_p()
        # EN: pinned ctypes objects — bounded: app blobs accumulate per
        #     add_block, so cap the list (dropping a pin only risks GC of
        #     blobs WFP already copied during FwpmFilterAdd0).
        # FR: objets ctypes épinglés — bornés : les blobs s'accumulent à
        #     chaque add_block, donc caper la liste (retirer un pin ne
        #     risque que le GC de blobs que WFP a déjà copiés).
        self._keepalive: list = []
        self._keepalive_max = 2048

    # ── lifecycle / cycle de vie ─────────────────────────────────────────────

    @staticmethod
    def available() -> bool:
        return os.name == "nt"

    def open(self) -> tuple[bool, str]:
        """EN: Load fwpuclnt + open a non-dynamic session (filters persist —
        Snitch deletes them explicitly by key). Returns (ok, error).
        FR: Charge fwpuclnt + ouvre une session non dynamique (les filtres
        persistent — Snitch les supprime explicitement par clé)."""
        if self._engine.value:
            return True, ""
        if not self.available():
            return False, "windows only"
        try:
            self._dll = ctypes.WinDLL("fwpuclnt")
        except OSError as e:
            return False, f"fwpuclnt unavailable: {e}"
        sess = _SESSION()
        sess.displayData.name = "Snitch"
        sess.displayData.description = "Snitch outbound filters"
        sess.flags = 0                 # EN: persistent / FR: persistante
        sess.processId = os.getpid()
        engine = ctypes.c_void_p()
        rc = self._dll.FwpmEngineOpen0(None, RPC_C_AUTHN_WINNT, None,
                                       ctypes.byref(sess), ctypes.byref(engine))
        if rc != 0:
            return False, f"FwpmEngineOpen0=0x{rc:08x} (admin required)"
        self._engine = engine
        self._purge_stale()
        return True, ""

    def close(self) -> None:
        if self._dll and self._engine.value:
            self._dll.FwpmEngineClose0(self._engine)
        self._engine = ctypes.c_void_p()

    # ── filters / filtres ────────────────────────────────────────────────────

    def add_block(self, rid: str, conds: list[dict]) -> tuple[bool, str]:
        """EN: Add one BLOCK filter per (layer, address) combination implied
        by `conds` — a condition dict list like:
            {"app": path}      → ALE_APP_ID on BOTH v4+v6 layers
            {"remote": cidr}   → remote addr (+mask) on the matching layer
            {"port": 443}      → remote port on BOTH layers
        Returns (ok, error). Filter keys are uuid5(rid, serialized conds).
        FR: Ajoute un filtre BLOCK par combinaison (couche, adresse) —
        voir le format ci-dessus. Clés uuid5(rid, conditions sérialisées)."""
        if not self._engine.value:
            return False, "engine not open"
        try:
            plan = self._plan(conds)
        except ValueError as e:
            return False, str(e)
        keep: list = []
        try:
            for layer_s, cfields, tag in plan:
                f = _FILTER()
                f.filterKey = _rule_key(rid, tag)
                f.displayData.name = _NAME_PREFIX + rid
                f.displayData.description = "Snitch outbound block"
                f.layerKey = _guid(layer_s)
                f.subLayerKey = _guid(_SUBLAYER_UNIVERSAL)
                weight = ctypes.c_uint64(0xFFFFFFFFFFFFFFFF)
                f.weight.type = FWP_UINT64
                f.weight.v.uint64p = ctypes.cast(
                    ctypes.pointer(weight), ctypes.c_void_p)
                keep.append(weight)
                arr = (_CONDITION * len(cfields))()
                for i, (key_s, vtype, ptr_or_val, pin) in enumerate(cfields):
                    arr[i].fieldKey = _guid(key_s)
                    arr[i].matchType = FWP_MATCH_EQUAL
                    arr[i].conditionValue.type = vtype
                    self._set_value(arr[i].conditionValue.v, vtype, ptr_or_val)
                    keep.append(pin)
                f.numFilterConditions = len(cfields)
                f.filterCondition = ctypes.cast(arr, ctypes.c_void_p)
                keep.append(arr)
                f.action.type = FWP_ACTION_BLOCK
                rc = self._dll.FwpmFilterAdd0(self._engine, ctypes.byref(f),
                                              None, None)
                if rc != 0:
                    return False, f"FwpmFilterAdd0=0x{rc:08x}"
            return True, ""
        except OSError as e:
            return False, str(e)[:200]

    @staticmethod
    def _set_value(union: _VALUE_UNION, vtype: int, val) -> None:
        """EN: Fill the value union — scalar types inline, compound by pointer.
        FR: Remplit l'union — scalaires inline, composés par pointeur."""
        if vtype == FWP_UINT8:
            union.uint8 = val
        elif vtype == FWP_UINT16:
            union.uint16 = val
        elif vtype == FWP_UINT32:
            union.uint32 = val
        elif vtype == FWP_BYTE_BLOB_TYPE:
            union.blobp = val
        elif vtype == FWP_BYTE_ARRAY16_TYPE:
            union.ba16p = val
        elif vtype == FWP_V4_ADDR_MASK:
            union.v4amp = val
        elif vtype == FWP_V6_ADDR_MASK:
            union.v6amp = val

    def _plan(self, conds: list[dict]) -> list:
        """EN: Translate abstract conds → [(layer_guid, [(key,type,val,pin)],
        tag)] — one filter per address so each key stays unique+deletable.
        FR: Traduit les conditions → [(couche, [(clé,type,valeur,pin)],
        tag)] — un filtre par adresse pour des clés uniques/supprimables."""
        app = next((c["app"] for c in conds if "app" in c), None)
        remotes = [c["remote"] for c in conds if "remote" in c]
        port = next((c["port"] for c in conds if "port" in c), None)
        proto = next((c["proto"] for c in conds if "proto" in c), None)
        plan = []
        if app is not None:
            blob = self._app_blob(app)
            if blob is None:
                raise ValueError(f"FwpmGetAppIdFromFileName failed for {app}")
            fields = [(_COND_ALE_APP_ID, FWP_BYTE_BLOB_TYPE,
                       ctypes.cast(ctypes.byref(blob.contents), ctypes.c_void_p),
                       blob)]
            plan += [(_LAYER_V4, fields, "app4"), (_LAYER_V6, fields, "app6")]
            # EN: app blob freed by caller-side pin until add returns — WFP
            #     copies the blob during FwpmFilterAdd0.
            # FR: blob libéré via le pin côté appelant — WFP le copie
            #     pendant FwpmFilterAdd0.
        for net_s in remotes:
            net = ipaddress.ip_network(net_s, strict=False)
            if net.version == 4:
                # EN: FWP_V4_ADDR_AND_MASK stores both fields in NETWORK
                #     byte order (samples fill .addr via InetPton into an
                #     in_addr). int(ip) is host order → swap.
                # FR: FWP_V4_ADDR_AND_MASK stocke les deux champs en ordre
                #     réseau (les samples remplissent .addr via InetPton
                #     dans un in_addr). int(ip) est host order → swap.
                am = _V4_ADDR_MASK(
                    int.from_bytes(net.network_address.packed, "little"),
                    int.from_bytes(net.netmask.packed, "little"))
                cf = (_COND_REMOTE_IP, FWP_V4_ADDR_MASK,
                      ctypes.cast(ctypes.byref(am), ctypes.c_void_p), am)
                plan.append((_LAYER_V4, [cf], f"ip-{net}"))
            else:
                am = _V6_ADDR_MASK(
                    (ctypes.c_uint8 * 16)(*net.network_address.packed),
                    net.prefixlen)
                cf = (_COND_REMOTE_IP, FWP_V6_ADDR_MASK,
                      ctypes.cast(ctypes.byref(am), ctypes.c_void_p), am)
                plan.append((_LAYER_V6, [cf], f"ip-{net}"))
        if port is not None:
            for layer, tag in ((_LAYER_V4, "port4"), (_LAYER_V6, "port6")):
                fields = [(_COND_REMOTE_PORT, FWP_UINT16, int(port), None)]
                if proto:
                    fields.append(("3971ef2b-623e-4f9a-8cb1-6e79b806b9a7",
                                   FWP_UINT8, int(proto), None))
                plan.append((layer, fields, tag))
        return plan

    def delete(self, rid: str, tags: list[str]) -> None:
        """EN: Delete this rule's filters by their deterministic keys —
        missing keys are fine. / FR: Supprime les filtres par leurs clés
        déterministes — les absents sont ignorés."""
        if not self._engine.value:
            return
        for tag in tags:
            key = _rule_key(rid, tag)
            rc = self._dll.FwpmFilterDeleteByKey0(self._engine,
                                                  ctypes.byref(key))
            # EN: FWP_E_FILTER_NOT_FOUND is expected — ignore it.
            # FR: FWP_E_FILTER_NOT_FOUND est attendu — on l'ignore.
            _ = rc

    @staticmethod
    def tags_for(kind: str, value: str,
                 resolved: Optional[list[str]] = None) -> list[str]:
        """EN: Inverse of _plan's tag generation — which keys might exist
        for a rule (used for deletes + domain refresh deltas).
        FR: Inverse de la génération de tags — quelles clés peuvent exister
        pour une règle (suppressions + deltas de re-résolution)."""
        if kind == "process":
            return ["app4", "app6"]
        if kind == "port":
            return ["port4", "port6"]
        nets = resolved if kind == "domain" else [value]
        return [f"ip-{ipaddress.ip_network(n, strict=False)}" for n in nets]

    def _app_blob(self, path: str):
        """EN: FwpmGetAppIdFromFileName0 → FWP_BYTE_BLOB* (canonicalized
        device path the ALE layer matches). None on failure.
        FR: FwpmGetAppIdFromFileName0 → FWP_BYTE_BLOB* (chemin canonique
        que la couche ALE matche). None en cas d'échec."""
        blob = ctypes.POINTER(_BYTE_BLOB)()
        rc = self._dll.FwpmGetAppIdFromFileName0(path, ctypes.byref(blob))
        if rc != 0 or not blob:
            return None
        if len(self._keepalive) >= self._keepalive_max:
            del self._keepalive[:self._keepalive_max // 4]
        self._keepalive.append(blob)   # EN: keep alive; freed w/ engine / FR: gardé vivant
        return blob

    def _purge_stale(self) -> None:
        """EN: Remove leftover SnitchRule-* filters from previous runs —
        enumerates the engine and deletes by key on name-prefix match.
        FR: Retire les filtres SnitchRule-* restés d'exécutions passées —
        énumère le moteur et supprime par clé sur préfixe de nom."""
        enum_h = ctypes.c_void_p()
        rc = self._dll.FwpmFilterCreateEnumHandle0(
            self._engine, None, ctypes.byref(enum_h))
        if rc != 0:
            return
        try:
            while True:
                arr_p = ctypes.POINTER(ctypes.POINTER(_FILTER))()
                n = ctypes.c_uint32(0)
                rc = self._dll.FwpmFilterEnum0(
                    self._engine, enum_h, 64, ctypes.byref(arr_p),
                    ctypes.byref(n))
                if rc != 0 or n.value == 0:
                    break
                for i in range(n.value):
                    name = arr_p[i].contents.displayData.name or ""
                    if name.startswith(_NAME_PREFIX):
                        key = arr_p[i].contents.filterKey
                        self._dll.FwpmFilterDeleteByKey0(
                            self._engine, ctypes.byref(key))
                self._dll.FwpmFreeMemory0(ctypes.byref(arr_p))
        finally:
            self._dll.FwpmFilterDestroyEnumHandle0(self._engine, enum_h)