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.

Add real-OS integration job: unshare/iptables/tc/WFP/sandbox-exec

MoneyLisa1d1b28bf71b9
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 08e8fed..492d1bd 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -57,6 +57,39 @@ jobs:
npm test
npm 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 compile
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.py
new file mode 100644
index 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()