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.
Python cybersecurityd3jsebpfedrelectronfastapifirewallfleet-managementlinuxlittle-snitch-alternativemacosnetwork-monitornetwork-securitypacket-captureprivacyreactrustself-hostedsiemwindows
Add real-OS integration job: unshare/iptables/tc/WFP/sandbox-exec
MoneyLisa1d1b28bf71b9
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 08e8fed..492d1bd 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -57,6 +57,39 @@ jobs:npm testnpm run build+ # EN: Real-OS integration — exercises the actual platform primitives the+ # unit suite only mocks, gated on SNITCH_OS_INTEGRATION=1:+ # Linux unshare netns egress denial, real iptables DROP + live+ # connect check, tc clsact/flower, perf_event_open+ # Windows fwpuclnt engine open + ALE BLOCK filter proven by a TCP+ # connect that fails while installed and recovers on delete+ # macOS sandbox-exec deny-network end-to-end, hosts-file sinkhole+ # Everything cleans up in `finally` and skips honestly when the+ # runner cannot provide the primitive (no egress, userns off, etc.).+ # FR: Intégration OS réel — exerce les vraies primitives que les tests+ # unitaires ne font que mocker (SNITCH_OS_INTEGRATION=1) :+ # unshare/iptables/tc/perf sous Linux, filtres WFP prouvés par une+ # vraie connexion sous Windows, sandbox-exec + hosts sous macOS.+ # Nettoyage en `finally`, skip honnête si le runner ne peut pas.+ integration:+ strategy:+ fail-fast: false+ matrix:+ os: [ubuntu-latest, windows-latest, macos-latest]+ runs-on: ${{ matrix.os }}+ steps:+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7+ - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7+ with:+ python-version: '3.11'+ - name: Install dependencies+ run: pip install -r backend/requirements.txt -r backend/requirements-dev.txt+ - name: Integration tests — real OS primitives (${{ matrix.os }})+ shell: bash+ env:+ SNITCH_OS_INTEGRATION: '1'+ run: cd backend && python -m pytest tests/test_integration_os.py -v+# EN: Per-OS PyInstaller build — runs on tags; verifies the spec compiles# everywhere and produces checksums for the release.# FR: Build PyInstaller par OS — sur tags ; vérifie que le spec compilediff --git a/CHANGELOG.md b/CHANGELOG.mdindex 395bd03..7c7a08a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,10 @@ The format follows [Keep a Changelog](https://keepachangelog.com/) — EN/FR.## [Unreleased]+### Added / Ajouté++- **Real-OS integration tests / Tests d'intégration OS réels** — new `integration` CI job (per-OS) running `tests/test_integration_os.py` with `SNITCH_OS_INTEGRATION=1`: Linux proves `unshare -n` egress denial, real `iptables` DROP + live connect failure, `tc` clsact/flower, `perf_event_open`; Windows opens the real `fwpuclnt` engine and proves a WFP BLOCK filter with a TCP connect that fails then recovers after key-delete; macOS proves `sandbox-exec` deny-network end-to-end and hosts-file sinkhole apply/remove. Every test cleans up in `finally` and skips honestly when the primitive is unavailable. / Nouveau job CI `integration` par OS exécutant `tests/test_integration_os.py` : `unshare`, `iptables` réels + connexion probée, `tc`, `perf` sous Linux ; moteur WFP + blocage prouvé par connexion TCP sous Windows ; `sandbox-exec` + hosts sous macOS. Nettoyage en `finally`, skip honnête si la primitive manque.+## [1.4.0] — 2026-10-23### Added / Ajoutédiff --git a/backend/tests/test_integration_os.py b/backend/tests/test_integration_os.pynew file mode 100644index 0000000..72593ee--- /dev/null+++ b/backend/tests/test_integration_os.py@@ -0,0 +1,329 @@+"""+Snitch — real-OS integration tests / tests d'intégration OS réels.++EN: These tests exercise the ACTUAL OS primitives the production code+ drives — no mocks for the platform layer:+ * Linux : `unshare` net-namespace sandbox, `iptables` OUTPUT DROP+ rules (through FirewallManager itself), `tc` clsact/flower+ throttling, perf_event_open.+ * Windows : `fwpuclnt.dll` WFP engine open, real BLOCK filter at the+ ALE connect layer verified with a live TCP connect.+ * macOS : `sandbox-exec` seatbelt egress denial end-to-end.+ They run only when SNITCH_OS_INTEGRATION=1 (the CI `integration` job)+ because they mutate host firewall state / spawn namespaces. Every test+ cleans up in `finally` and skips honestly when the environment can't+ provide the primitive (no egress, userns disabled, no admin).++FR: Ces tests exercent les VRAIES primitives OS que le code de production+ pilote — aucun mock sur la couche plateforme. Ils ne tournent que si+ SNITCH_OS_INTEGRATION=1 (job CI `integration`) car ils modifient l'état+ du pare-feu hôte. Chaque test nettoie dans `finally` et skip honnêtement+ quand l'environnement ne fournit pas la primitive.+"""++from __future__ import annotations++import os+import platform+import shutil+import socket+import subprocess+import sys+import tempfile+import textwrap++import pytest++SYSTEM = platform.system().lower()+ENABLED = os.environ.get("SNITCH_OS_INTEGRATION") == "1"++pytestmark = [+ pytest.mark.skipif(not ENABLED,+ reason="needs SNITCH_OS_INTEGRATION=1 (CI job)"),+]++# EN: Public reachability probe target for end-to-end block checks.+# 1.1.1.1:443 is a stable anycast TCP endpoint; if the runner has no+# direct egress the tests skip instead of failing.+# FR: Cible de joignabilité publique pour les tests de blocage réels —+# skip honnête si le runner n'a pas d'égress direct.+_PROBE_IP, _PROBE_PORT = "1.1.1.1", 443+++def _probe_source() -> str:+ """EN: Small script printed inside sandboxes — reports whether a TCP+ connect to a public address succeeded (NET_OK) or was refused by the+ environment (NET_DENIED). / FR: Script exécuté dans les sandbox —+ rapporte si une connexion TCP publique a réussi ou été refusée."""+ return textwrap.dedent(+ "import socket\n"+ "try:\n"+ f" socket.create_connection(('{_PROBE_IP}', {_PROBE_PORT}), "+ "timeout=3)\n"+ " print('NET_OK')\n"+ "except Exception as e:\n"+ " print('NET_DENIED', type(e).__name__)\n")+++def _tcp_reachable(ip: str, port: int, timeout: float = 3.0) -> bool:+ """EN: True when a TCP connect to ip:port succeeds.+ FR: Vrai si la connexion TCP vers ip:port aboutit."""+ try:+ socket.create_connection((ip, port), timeout=timeout).close()+ return True+ except OSError:+ return False+++def _run(cmd: list[str], timeout: int = 15) -> subprocess.CompletedProcess:+ return subprocess.run(cmd, capture_output=True, text=True,+ timeout=timeout, check=False)+++def _sudo(cmd: list[str]) -> list[str]:+ """EN: Prefix with non-interactive sudo — CI runners have passwordless+ sudo; production normally runs Snitch with capture privileges anyway.+ FR: Préfixe sudo non interactif — sudo sans mot de passe en CI."""+ return ["sudo", "-n", *cmd]+++# ══════════════════════════ Linux / Linux ══════════════════════════++[email protected](SYSTEM != "linux", reason="linux only")+class TestLinuxReal:+ """EN: Real Linux primitives — namespaces, iptables, tc, perf.+ FR: Primitives Linux réelles — namespaces, iptables, tc, perf."""++ def test_unshare_netns_denies_egress(self, tmp_path):+ """EN: A child inside `unshare -U -n` (the exact wrapper production+ builds via contain.sandbox_command) cannot open a TCP connection —+ first through the unprivileged userns path, then under sudo -n as+ a fallback check of the namespace primitive itself.+ FR: Un enfant dans `unshare -U -n` (wrapper exact de production)+ ne peut pas ouvrir de connexion TCP — chemin userns non privilégié+ d'abord, puis repli sudo pour valider la primitive."""+ from detection import contain++ if not shutil.which("unshare"):+ pytest.skip("unshare missing")+ probe = tmp_path / "probe.py"+ probe.write_text(_probe_source())++ cmd = contain.sandbox_command(sys.executable, [str(probe)])+ res = _run(cmd, timeout=20)+ if res.returncode != 0:+ # EN: Unprivileged userns may be disabled — fall back to root+ # namespace creation (sudo exists on the runner) and still+ # verify real egress denial.+ # FR: Les userns non privilégiés peuvent être désactivés —+ # repli root (sudo) pour valider quand même le déni réel.+ res = _run(_sudo(["unshare", "--net", "--fork",+ sys.executable, str(probe)]), timeout=20)+ assert res.returncode == 0, res.stderr[:400]+ assert "NET_DENIED" in res.stdout++ def test_iptables_rule_through_manager(self):+ """EN: Apply a real rule through FirewallManager (production code+ path, sudo-wrapped _run): the iptables -C check must confirm the+ DROP rule exists, then removal must take it away.+ FR: Appliquer une vraie règle via FirewallManager (chemin+ production, _run enrobé de sudo) : `iptables -C` confirme le DROP,+ puis le retrait l'enlève."""+ from detection.firewall import FirewallManager++ if not shutil.which("iptables"):+ pytest.skip("iptables missing")+ fm = FirewallManager(tempfile.mkdtemp())+ real_run = fm._run+ fm._run = lambda args: real_run(_sudo(args)) # noqa: SLF001+ rule = fm.add_rule("ip", "203.0.113.9", action="block")+ try:+ assert rule["applied"], f"apply failed: {rule['error']}"+ check = _run(_sudo([+ "iptables", "-w", "-C", "OUTPUT", "-d", "203.0.113.9",+ "-j", "DROP", "-m", "comment", "--comment",+ f"snitch-{rule['id']}"]))+ assert check.returncode == 0, check.stderr[:300]+ finally:+ fm.remove_rule(rule["id"])+ gone = _run(_sudo([+ "iptables", "-w", "-C", "OUTPUT", "-d", "203.0.113.9",+ "-j", "DROP", "-m", "comment", "--comment",+ f"snitch-{rule['id']}"]))+ assert gone.returncode != 0, "DROP rule still present"++ def test_iptables_block_really_drops(self):+ """EN: End-to-end — baseline connect to 1.1.1.1:443 succeeds, a+ real OUTPUT DROP makes it fail, removal restores it. Skips when+ the runner has no direct egress.+ FR: Bout en bout — la connexion de base réussit, un DROP réel la+ fait échouer, le retrait la restaure. Skip sans égress direct."""+ if not _tcp_reachable(_PROBE_IP, _PROBE_PORT):+ pytest.skip("runner has no direct egress to 1.1.1.1:443")+ add = _sudo(["iptables", "-w", "-I", "OUTPUT", "-d", _PROBE_IP,+ "-j", "DROP", "-m", "comment", "--comment",+ "snitch-itest"])+ delete = _sudo(["iptables", "-w", "-D", "OUTPUT", "-d", _PROBE_IP,+ "-j", "DROP", "-m", "comment", "--comment",+ "snitch-itest"])+ res = _run(add)+ if res.returncode != 0:+ pytest.skip(f"cannot insert iptables rule: {res.stderr[:200]}")+ try:+ assert not _tcp_reachable(_PROBE_IP, _PROBE_PORT, timeout=4)+ finally:+ _run(delete)+ assert _tcp_reachable(_PROBE_IP, _PROBE_PORT)++ def test_tc_throttle_through_manager(self):+ """EN: Real clsact + flower via FirewallManager — a throttle rule+ must install a tc filter on the default-route interface.+ FR: clsact + flower réels via FirewallManager — une règle throttle+ installe un filtre tc sur l'interface de la route par défaut."""+ from detection.firewall import FirewallManager++ if not shutil.which("tc"):+ pytest.skip("tc missing")+ fm = FirewallManager(tempfile.mkdtemp())+ real_run = fm._run+ fm._run = lambda args: real_run(_sudo(args)) # noqa: SLF001+ rule = fm.add_rule("ip", "203.0.113.10", action="throttle", rate=64)+ try:+ if not rule["applied"]:+ pytest.skip(f"tc setup refused: {rule['error']}")+ show = _run(_sudo(["tc", "filter", "show", "dev",+ fm._tc_iface, "egress"])) # noqa: SLF001+ assert "flower" in show.stdout+ finally:+ fm.remove_rule(rule["id"])+ if fm._tc_iface: # noqa: SLF001+ _run(_sudo(["tc", "qdisc", "del", "dev",+ fm._tc_iface, "clsact"])) # noqa: SLF001++ def test_perf_event_open(self):+ """EN: perf_event_open on own process through the production+ sample() — skips when the kernel paranoid level blocks it, asserts+ real counter reads otherwise.+ FR: perf_event_open sur le processus courant via sample() de+ production — skip si le noyau bloque, sinon vérifie de vrais+ compteurs."""+ from detection import perfprobe++ ok, why = perfprobe.available()+ if not ok:+ pytest.skip(f"perf unavailable here: {why}")+ res = perfprobe.sample(os.getpid(), 0.3)+ if not res.get("ok"):+ pytest.skip(f"perf_event_open refused: {res.get('error')}")+ assert res["instructions"] >= 0+ assert res["cpu_ms"] > 0+++# ══════════════════════════ Windows / Windows ══════════════════════════++[email protected](SYSTEM != "windows", reason="windows only")+class TestWindowsReal:+ """EN: Real WFP user-mode path — engine open, filter add, live block,+ delete. / FR: Chemin WFP user-mode réel — ouverture, filtre, blocage+ effectif, suppression."""++ def test_wfp_engine_and_live_block(self):+ """EN: FwpmEngineOpen0 + a real ALE_AUTH_CONNECT_V4 BLOCK filter:+ a TCP connect that worked before must fail while the filter is+ installed, and succeed again after delete-by-key.+ FR: FwpmEngineOpen0 + filtre BLOCK réel : la connexion TCP qui+ marchait doit échouer pendant le filtre et remarcher après+ suppression par clé."""+ from detection.wfp import WfpBackend++ wfp = WfpBackend()+ ok, err = wfp.open()+ assert ok, f"FwpmEngineOpen0 failed: {err}"+ try:+ if not _tcp_reachable(_PROBE_IP, _PROBE_PORT):+ pytest.skip("runner has no direct egress to 1.1.1.1:443")+ rid = "itestwfp"+ ok, err = wfp.add_block(rid, [{"remote": f"{_PROBE_IP}/32"}])+ assert ok, f"FwpmFilterAdd0 failed: {err}"+ try:+ assert not _tcp_reachable(_PROBE_IP, _PROBE_PORT,+ timeout=4), \+ "connect succeeded despite WFP BLOCK filter"+ finally:+ wfp.delete(rid, WfpBackend.tags_for(+ "ip", f"{_PROBE_IP}/32"))+ assert _tcp_reachable(_PROBE_IP, _PROBE_PORT), \+ "connect still blocked after filter delete"+ finally:+ wfp.close()++ def test_wfp_app_id_filter(self):+ """EN: Per-application filter — resolve python.exe through+ FwpmGetAppIdFromFileName0 and install an ALE_APP_ID block.+ FR: Filtre par application — ALE_APP_ID de python.exe via+ FwpmGetAppIdFromFileName0."""+ from detection.wfp import WfpBackend++ wfp = WfpBackend()+ ok, err = wfp.open()+ assert ok, f"FwpmEngineOpen0 failed: {err}"+ try:+ rid = "itestapp"+ ok, err = wfp.add_block(rid, [{"app": sys.executable}])+ try:+ assert ok, f"app-id filter failed: {err}"+ finally:+ wfp.delete(rid, WfpBackend.tags_for("process",+ sys.executable))+ finally:+ wfp.close()+++# ══════════════════════════ macOS / macOS ══════════════════════════++[email protected](SYSTEM != "darwin", reason="macos only")+class TestMacosReal:+ """EN: Real seatbelt path — the production run_sandboxed wrapper.+ FR: Chemin seatbelt réel — le wrapper production run_sandboxed."""++ def test_sandbox_exec_denies_egress(self, tmp_path):+ """EN: End-to-end through contain.run_sandboxed — the child must+ report NET_DENIED for a public TCP connect.+ FR: Bout en bout via contain.run_sandboxed — l'enfant doit+ rapporter NET_DENIED sur une connexion TCP publique."""+ from detection import contain++ ok, why = contain.available()+ assert ok, f"sandbox primitive missing: {why}"+ probe = tmp_path / "probe.py"+ probe.write_text(_probe_source())+ res = contain.run_sandboxed(sys.executable, [str(probe)], 10)+ assert res["ok"], f"sandbox run failed: {res.get('error')}"+ assert "NET_DENIED" in res["stdout"], (+ f"egress not denied: {res['stdout']!r} {res['stderr'][:200]!r}")++ def test_sinkhole_hosts_markers(self):+ """EN: Domain sinkhole is a marked hosts block — apply + remove+ through FirewallManager against a temp hosts path (no /etc write).+ FR: Le sinkhole domaine est un bloc hosts marqué — apply/remove+ via FirewallManager sur un hosts temporaire (pas d'écriture /etc)."""+ from detection.firewall import FirewallManager+ from pathlib import Path++ fake_hosts = Path(tempfile.mkdtemp()) / "hosts"+ fake_hosts.write_text("127.0.0.1 localhost\n")+ fm = FirewallManager(tempfile.mkdtemp())+ fm._hosts_path = lambda: fake_hosts # noqa: SLF001+ rule = fm.add_rule("domain", "itest-sinkhole.example",+ action="sinkhole")+ try:+ assert rule["applied"], rule["error"]+ body = fake_hosts.read_text()+ assert f"# snitch-sinkhole {rule['id']} begin" in body+ assert "127.0.0.1 itest-sinkhole.example" in body+ finally:+ fm.remove_rule(rule["id"])+ assert "itest-sinkhole.example" not in fake_hosts.read_text()