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.

14.4 KB
Raw Blame
"""
Snitch — ctypes binding to libpcap / wpcap.

EN: Minimal, dependency-free binding to the system packet-capture library:
      - Windows : wpcap.dll, shipped by Npcap (user-installed — NOT bundled;
                  the free Npcap license does not allow external redistribution)
      - Linux   : libpcap.so (apt install libpcap0.8)
      - macOS   : libpcap.dylib (ships with the OS)

    ctypes is stdlib, so this adds zero compiled dependencies and zero GPL
    contamination (libpcap/Npcap are BSD-style licensed).

    Capture rights are still required: admin on Windows, root or
    cap_net_raw/cap_net_admin on Linux, /dev/bpf* access on macOS.

FR: Liaison ctypes minimale et sans dépendance vers la bibliothèque système de
    capture :
      - Windows : wpcap.dll, fournie par Npcap (installé par l'utilisateur —
                  PAS embarqué ; la licence gratuite de Npcap interdit la
                  redistribution externe)
      - Linux   : libpcap.so (apt install libpcap0.8)
      - macOS   : libpcap.dylib (livré avec l'OS)

    ctypes fait partie de la bibliothèque standard : zéro dépendance compilée,
    zéro contamination GPL (libpcap/Npcap sont sous licences de type BSD).

    Les droits de capture restent nécessaires : admin sous Windows, root ou
    cap_net_raw/cap_net_admin sous Linux, accès /dev/bpf* sous macOS.
"""

import ctypes
import ctypes.util
import logging
import socket
import sys
from dataclasses import dataclass
from typing import Optional

logger = logging.getLogger("snitch.capture.pcap")


class PcapError(Exception):
    """EN: Raised when libpcap is missing or a call fails.
    FR: Levée quand libpcap est absente ou qu'un appel échoue."""
    pass


# ── Structures / Structures ──────────────────────────────────────────────────

class _TimeVal(ctypes.Structure):
    """EN: struct timeval. / FR: struct timeval."""
    _fields_ = [("tv_sec", ctypes.c_long), ("tv_usec", ctypes.c_long)]


class PcapPkthdr(ctypes.Structure):
    """EN: struct pcap_pkthdr — timestamp + captured/wire lengths.
    FR: struct pcap_pkthdr — timestamp + longueurs capturée/fil."""
    _fields_ = [
        ("ts", _TimeVal),
        ("caplen", ctypes.c_uint32),
        ("len", ctypes.c_uint32),
    ]


class PcapAddr(ctypes.Structure):
    """EN: struct pcap_addr (linked list of interface addresses).
    FR: struct pcap_addr (liste chaînée des adresses d'interface)."""
    pass


PcapAddr._fields_ = [
    ("next", ctypes.POINTER(PcapAddr)),
    ("addr", ctypes.c_void_p),
    ("netmask", ctypes.c_void_p),
    ("broadaddr", ctypes.c_void_p),
    ("dstaddr", ctypes.c_void_p),
]


class PcapIf(ctypes.Structure):
    """EN: struct pcap_if — device list node. / FR: struct pcap_if — nœud de la liste de périphériques."""
    pass


PcapIf._fields_ = [
    ("next", ctypes.POINTER(PcapIf)),
    ("name", ctypes.c_char_p),
    ("description", ctypes.c_char_p),
    ("addresses", ctypes.POINTER(PcapAddr)),
    ("flags", ctypes.c_uint32),
]


class BpfInsn(ctypes.Structure):
    """EN: struct bpf_insn. / FR: struct bpf_insn."""
    _fields_ = [
        ("code", ctypes.c_ushort),
        ("jt", ctypes.c_ubyte),
        ("jf", ctypes.c_ubyte),
        ("k", ctypes.c_uint32),
    ]


class BpfProgram(ctypes.Structure):
    """EN: struct bpf_program. / FR: struct bpf_program."""
    _fields_ = [
        ("bf_len", ctypes.c_uint),
        ("bf_insns", ctypes.POINTER(BpfInsn)),
    ]


# ── Library loading / Chargement de la bibliothèque ─────────────────────────

_lib = None


def _load_lib() -> ctypes.CDLL:
    """
    EN: Locate and load libpcap for the current platform, once. On Windows,
        Npcap installs wpcap.dll under System32\\Npcap — add it to the DLL
        search path explicitly (required since Python 3.8 no longer searches
        PATH for ctypes loads).
    FR: Localiser et charger libpcap pour la plateforme courante, une fois.
        Sous Windows, Npcap installe wpcap.dll dans System32\\Npcap — l'ajouter
        explicitement au chemin de recherche DLL (Python 3.8+ ne consulte plus
        PATH pour les chargements ctypes).
    """
    global _lib
    if _lib is not None:
        return _lib

    candidates: list[str] = []
    if sys.platform == "win32":
        import os
        npcap_dir = os.path.join(os.environ.get("SystemRoot", r"C:\Windows"),
                                 "System32", "Npcap")
        if os.path.isdir(npcap_dir):
            try:
                os.add_dll_directory(npcap_dir)
            except OSError:
                pass
        candidates = ["wpcap.dll"]
    elif sys.platform == "darwin":
        candidates = ["libpcap.dylib", "libpcap.A.dylib"]
    else:
        found = ctypes.util.find_library("pcap")
        candidates = [found] if found else []
        candidates += ["libpcap.so.0.8", "libpcap.so.1", "libpcap.so"]

    last_err: Optional[Exception] = None
    for name in candidates:
        if not name:
            continue
        try:
            _lib = ctypes.CDLL(name)
            _configure(_lib)
            return _lib
        except OSError as exc:
            last_err = exc

    raise PcapError(_missing_msg(last_err))


def _missing_msg(err: Optional[Exception]) -> str:
    """EN: Human-readable install guidance per platform.
    FR: Conseils d'installation lisibles selon la plateforme."""
    if sys.platform == "win32":
        return ("Npcap not found — install it from https://npcap.com "
                "(Npcap n'est pas installé — téléchargez-le sur https://npcap.com)")
    if sys.platform == "darwin":
        return "libpcap not found (unexpected on macOS) / libpcap introuvable"
    return ("libpcap not found — install it (apt install libpcap0.8 / dnf install libpcap) "
            "/ libpcap introuvable — installez-la")


def _configure(lib: ctypes.CDLL) -> None:
    """EN: Declare argtypes/restypes for the functions we bind.
    FR: Déclarer les argtypes/restypes des fonctions liées."""
    lib.pcap_findalldevs.argtypes = [ctypes.POINTER(ctypes.POINTER(PcapIf)), ctypes.c_char_p]
    lib.pcap_findalldevs.restype = ctypes.c_int
    lib.pcap_freealldevs.argtypes = [ctypes.POINTER(PcapIf)]
    lib.pcap_freealldevs.restype = None

    lib.pcap_open_live.argtypes = [ctypes.c_char_p, ctypes.c_int, ctypes.c_int,
                                   ctypes.c_int, ctypes.c_char_p]
    lib.pcap_open_live.restype = ctypes.c_void_p

    lib.pcap_datalink.argtypes = [ctypes.c_void_p]
    lib.pcap_datalink.restype = ctypes.c_int

    lib.pcap_compile.argtypes = [ctypes.c_void_p, ctypes.POINTER(BpfProgram),
                                 ctypes.c_char_p, ctypes.c_int, ctypes.c_uint32]
    lib.pcap_compile.restype = ctypes.c_int

    lib.pcap_setfilter.argtypes = [ctypes.c_void_p, ctypes.POINTER(BpfProgram)]
    lib.pcap_setfilter.restype = ctypes.c_int

    lib.pcap_freecode.argtypes = [ctypes.POINTER(BpfProgram)]
    lib.pcap_freecode.restype = None

    lib.pcap_next_ex.argtypes = [ctypes.c_void_p,
                                 ctypes.POINTER(ctypes.POINTER(PcapPkthdr)),
                                 ctypes.POINTER(ctypes.POINTER(ctypes.c_ubyte))]
    lib.pcap_next_ex.restype = ctypes.c_int

    lib.pcap_geterr.argtypes = [ctypes.c_void_p]
    lib.pcap_geterr.restype = ctypes.c_char_p

    lib.pcap_close.argtypes = [ctypes.c_void_p]
    lib.pcap_close.restype = None

    lib.pcap_lib_version.restype = ctypes.c_char_p


def is_available() -> bool:
    """EN: True when libpcap/wpcap loads. / FR: True si libpcap/wpcap se charge."""
    try:
        _load_lib()
        return True
    except PcapError:
        return False


@dataclass
class PcapDevice:
    """EN: One capture-capable interface. / FR: Une interface capturable."""
    name: str
    description: str
    loopback: bool = False
    # EN: IPv4/IPv6 addresses owned by the device, as reported by libpcap.
    #     Needed on Windows, where Npcap names (\Device\NPF_{GUID}) never
    #     match psutil's friendly names ("Ethernet 2").
    # FR: Adresses IPv4/IPv6 du périphérique, telles que rapportées par
    #     libpcap. Indispensable sous Windows, où les noms Npcap
    #     (\Device\NPF_{GUID}) ne correspondent jamais aux noms
    #     conviviaux de psutil (« Ethernet 2 »).
    addresses: tuple[str, ...] = ()


def _sockaddr_ip(ptr: Optional[int]) -> Optional[str]:
    """
    EN: Decode a `struct sockaddr *` into an IP string (IPv4/IPv6 only).
        BSD/macOS start with a 1-byte sa_len then a 1-byte family; Windows
        and Linux use a 2-byte little-endian family.
    FR: Décoder un `struct sockaddr *` en chaîne IP (IPv4/IPv6 seulement).
        BSD/macOS commencent par sa_len sur 1 octet puis la famille sur 1
        octet ; Windows et Linux utilisent une famille sur 2 octets LE.
    """
    if not ptr:
        return None
    # EN: Read the 2-byte family FIRST — a short sockaddr (sa_len/
    #     sa_family only, e.g. AF_UNIX) must not be over-read for 24 bytes.
    # FR: Lire la famille sur 2 octets D'ABORD — un sockaddr court
    #     (sa_len/sa_family seuls, ex. AF_UNIX) ne doit pas être relu
    #     sur 24 octets.
    head = ctypes.string_at(ptr, 2)
    family = head[1] if sys.platform == "darwin" else int.from_bytes(head, "little")
    if family == socket.AF_INET:
        return socket.inet_ntop(socket.AF_INET, ctypes.string_at(ptr + 4, 4))
    if family == socket.AF_INET6:
        return socket.inet_ntop(socket.AF_INET6, ctypes.string_at(ptr + 8, 16))
    return None


def list_devices() -> list[PcapDevice]:
    """
    EN: Enumerate capture interfaces via pcap_findalldevs.
    FR: Énumérer les interfaces de capture via pcap_findalldevs.
    """
    lib = _load_lib()
    devs = ctypes.POINTER(PcapIf)()
    errbuf = ctypes.create_string_buffer(256)
    try:
        if lib.pcap_findalldevs(ctypes.byref(devs), errbuf) != 0:
            raise PcapError(f"pcap_findalldevs: {errbuf.value.decode(errors='replace')}")
        out = []
        cur = devs
        while cur:
            d = cur.contents
            name = d.name.decode(errors="replace") if d.name else ""
            desc = d.description.decode(errors="replace") if d.description else ""
            addrs = []
            a = d.addresses
            while a:
                ip = _sockaddr_ip(a.contents.addr)
                if ip:
                    addrs.append(ip)
                a = a.contents.next
            out.append(PcapDevice(name=name, description=desc,
                                  loopback=bool(d.flags & 0x1),
                                  addresses=tuple(addrs)))
            cur = d.next
        return out
    finally:
        lib.pcap_freealldevs(devs)


class PcapSession:
    """
    EN: One live capture session on a device. `next_packet()` blocks up to
        `timeout_ms` (set at open) and returns (bytes, wire_len) or None on
        timeout — the caller loop polls and stays interruptible.
    FR: Une session de capture live sur un périphérique. `next_packet()`
        bloque jusqu'à `timeout_ms` (fixé à l'ouverture) et renvoie
        (octets, longueur_fil) ou None en cas de timeout — la boucle appelante
        sonde et reste interruptible.
    """

    def __init__(self, device: str, snaplen: int = 65535, promisc: bool = True,
                 timeout_ms: int = 100, bpf_filter: Optional[str] = None):
        self._lib = _load_lib()
        errbuf = ctypes.create_string_buffer(256)
        self._handle = self._lib.pcap_open_live(
            device.encode(), snaplen, 1 if promisc else 0, timeout_ms, errbuf)
        if not self._handle:
            raise PcapError(
                f"pcap_open_live({device}): {errbuf.value.decode(errors='replace')}")
        self.device = device
        self.linktype = self._lib.pcap_datalink(self._handle)
        self._closed = False

        if bpf_filter:
            prog = BpfProgram()
            try:
                if self._lib.pcap_compile(self._handle, ctypes.byref(prog),
                                          bpf_filter.encode(), 1, 0) != 0:
                    raise PcapError(f"pcap_compile({bpf_filter!r}): {self._err()}")
                if self._lib.pcap_setfilter(self._handle, ctypes.byref(prog)) != 0:
                    raise PcapError(f"pcap_setfilter: {self._err()}")
            except Exception:
                # EN: A filter failure must not strand the live handle —
                #     nothing else will ever close it after __init__ raises.
                # FR: Un échec de filtre ne doit pas orpheliner le handle
                #     live — plus rien ne le fermera si __init__ lève.
                self._lib.pcap_close(self._handle)
                self._closed = True
                raise
            finally:
                self._lib.pcap_freecode(ctypes.byref(prog))

    def _err(self) -> str:
        """EN: Last libpcap error string. / FR: Dernière erreur libpcap."""
        raw = self._lib.pcap_geterr(self._handle)
        return raw.decode(errors="replace") if raw else "unknown error"

    def next_packet(self) -> Optional[tuple[bytes, int, float]]:
        """
        EN: Next packet — (payload, wire_length, wire_ts) or None on
            timeout. `wire_ts` is libpcap's own timestamp (seconds, float)
            — more accurate than time.time() for forensic exports. Raises
            PcapError on capture failure or EOF.
        FR: Paquet suivant — (charge utile, longueur fil, ts fil) ou None
            au timeout. `wire_ts` est le timestamp propre de libpcap —
            plus précis que time.time() pour les exports forensiques.
            Lève PcapError en cas d'échec ou de fin de fichier.
        """
        hdr = ctypes.POINTER(PcapPkthdr)()
        data = ctypes.POINTER(ctypes.c_ubyte)()
        rc = self._lib.pcap_next_ex(self._handle, ctypes.byref(hdr), ctypes.byref(data))
        if rc == 1:
            h = hdr.contents
            ts = h.ts.tv_sec + h.ts.tv_usec / 1_000_000.0
            return (ctypes.string_at(data, h.caplen), h.len, ts)
        if rc == 0:
            return None                    # EN: timeout / FR: timeout
        if rc == -2:
            return None                    # EN: EOF (offline dumps) / FR: fin de fichier (dumps hors ligne)
        raise PcapError(f"pcap_next_ex: {self._err()}")

    def close(self) -> None:
        """EN: Release the capture handle. / FR: Libérer le handle de capture."""
        if not self._closed and self._handle:
            self._lib.pcap_close(self._handle)
            self._closed = True