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.

elevation: auto-elevate the backend on every OS, not just Windows

MoneyLisa8658b985f588
diff --git a/SECURITY.md b/SECURITY.md
index e05bc94..4e64812 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -36,25 +36,29 @@ conception :
## Privileges / Privilèges
**EN:** Packet capture requires elevated privileges — but only the backend
-holds them. The Electron UI runs unprivileged (`asInvoker`); on Windows the
-backend alone is spawned elevated (`Start-Process -Verb RunAs`, one UAC
-prompt per launch) and is stopped through the authenticated `/shutdown`
-endpoint since an unprivileged process cannot signal it.
+holds them. The packaged Electron app runs the UI unprivileged on every OS
+and elevates ONLY the backend through the platform's native prompt:
-- Windows: UI unprivileged + backend elevated via UAC + Npcap (installed by you from npcap.com)
-- Linux: `setcap cap_net_raw,cap_net_admin` on the binary, or root
-- macOS: read access to `/dev/bpf*` (experimental support)
+- **Windows:** `Start-Process -Verb RunAs` (one UAC prompt per launch) + Npcap (installed by you from npcap.com)
+- **macOS:** `osascript … with administrator privileges` (native password dialog)
+- **Linux:** `pkexec` (polkit dialog); falls back to unprivileged if polkit is absent
+
+The elevated child is stopped through the authenticated `/shutdown` endpoint
+since an unprivileged process cannot signal it. Declining the prompt offers
+retry / continue-without-capture instead of a hard quit.
**FR :** La capture de paquets exige des privilèges élevés — mais seul le
-backend les détient. L'UI Electron tourne sans privilèges (`asInvoker`) ;
-sous Windows, seul le backend est lancé en mode élevé (`Start-Process -Verb
-RunAs`, une invite UAC par lancement) et il est arrêté via l'endpoint
-authentifié `/shutdown` puisqu'un processus non privilégié ne peut pas le
-signaler.
-
-- Windows : UI non privilégiée + backend élevé via UAC + Npcap (installé par vos soins depuis npcap.com)
-- Linux : `setcap cap_net_raw,cap_net_admin` sur le binaire, ou root
-- macOS : accès en lecture à `/dev/bpf*` (support expérimental)
+backend les détient. L'app Electron packagée fait tourner l'UI sans
+privilèges sur tous les OS et n'élève QUE le backend via l'invite native de
+la plateforme :
+
+- **Windows :** `Start-Process -Verb RunAs` (une invite UAC par lancement) + Npcap (installé par vos soins depuis npcap.com)
+- **macOS :** `osascript … with administrator privileges` (dialogue mot de passe natif)
+- **Linux :** `pkexec` (dialogue polkit) ; repli non privilégié si polkit est absent
+
+L'enfant élevé est arrêté via l'endpoint authentifié `/shutdown` puisqu'un
+processus non privilégié ne peut pas le signaler. Refuser l'invite propose
+réessayer / continuer sans capture au lieu d'une sortie brutale.
## Dependencies / Dépendances
diff --git a/docs/threat-model.md b/docs/threat-model.md
index 5d09ec8..1cb3ef5 100644
--- a/docs/threat-model.md
+++ b/docs/threat-model.md
@@ -32,9 +32,10 @@ same process. There is **no cloud component** and **no telemetry**.
### Known limitations
- **Admin/elevation is still required for capture** — but scoped to the
- backend only: the Electron UI runs asInvoker while the backend is spawned
- elevated (`Start-Process -Verb RunAs`) and stopped via the authenticated
- `/shutdown` endpoint.
+ backend only: the Electron UI runs unprivileged while the backend is
+ spawned elevated through the platform prompt (`Start-Process -Verb RunAs`
+ on Windows, `osascript` on macOS, `pkexec` on Linux) and stopped via the
+ authenticated `/shutdown` endpoint.
- The API token protects HTTP/WS but **not** against another local process
running as you that can read `data/api_token.txt` or the Electron IPC.
- SQLite data at rest is unencrypted.
@@ -78,9 +79,10 @@ le même processus. **Aucun composant cloud, aucune télémétrie.**
### Limites connues
- **Capture = privilèges admin/root**, mais limités au backend : l'UI
- Electron tourne en asInvoker tandis que le backend est lancé élevé
- (`Start-Process -Verb RunAs`) et arrêté via l'endpoint authentifié
- `/shutdown`.
+ Electron tourne sans privilèges tandis que le backend est lancé élevé via
+ l'invite de la plateforme (`Start-Process -Verb RunAs` sous Windows,
+ `osascript` sous macOS, `pkexec` sous Linux) et arrêté via l'endpoint
+ authentifié `/shutdown`.
- Le jeton protège HTTP/WS mais **pas** contre un autre processus local
tournant sous votre compte qui lit `data/api_token.txt` ou l'IPC Electron.
- Les données SQLite au repos ne sont pas chiffrées.
diff --git a/electron/main.js b/electron/main.js
index 8f29078..cfc88d7 100644
--- a/electron/main.js
+++ b/electron/main.js
@@ -99,10 +99,12 @@ let backendProc = null
let tray = null
let backendPort = 0 // EN: chosen at launch / FR: choisi au lancement
let isQuitting = false
-let backendElevated = false // EN: Windows RunAs spawn — we can't kill it,
- // /shutdown is the exit path.
- // FR: spawn élevé Windows — on ne peut pas
- // le tuer, /shutdown est le chemin d'arrêt.
+let backendElevated = false // EN: Elevated spawn (RunAs/osascript/pkexec)
+ // — we can't kill it, /shutdown is the
+ // exit path.
+ // FR: Spawn élevé (RunAs/osascript/pkexec) —
+ // impossible à tuer, /shutdown est le
+ // chemin d'arrêt.
// ── API token + port / Jeton API + port ─────────────────────────────────────
// EN: 48-hex-char secret generated once per app launch. Passed to the backend
@@ -358,31 +360,76 @@ function backendDataDir() {
}
/**
- * EN: Windows privilege split — the UI runs UNPRIVILEGED (asInvoker); only
- * the backend asks for admin via `Start-Process -Verb RunAs` (one UAC
- * prompt per launch). Env vars can't cross UAC, so we pass the port as
- * an argv flag and pre-write the token to api_token.txt — the backend's
- * own resolution order picks it up. In dev we spawn normally: capture
- * will fail without rights but the UI stays usable.
- * FR: Séparation de privilèges Windows — l'UI tourne SANS privilèges
- * (asInvoker) ; seul le backend demande l'admin via `Start-Process -Verb
- * RunAs` (une invite UAC par lancement). Les variables d'env ne
- * traversent pas l'UAC, donc on passe le port en argument argv et on
- * pré-écrit le jeton dans api_token.txt — l'ordre de résolution du
- * backend le récupère. En dev on lance normalement : la capture échouera
- * sans droits mais l'UI reste utilisable.
+ * EN: Privilege split — the UI runs UNPRIVILEGED on every OS; only the
+ * backend asks for elevation, once per launch, through the platform's
+ * native prompt:
+ * Windows : Start-Process -Verb RunAs (UAC dialog)
+ * macOS : osascript "do shell script … with administrator privileges"
+ * (native password dialog — same as sudo, GUI-flavoured)
+ * Linux : pkexec (polkit dialog)
+ *
+ * Elevated processes get a different $HOME (root), so SNITCH_DATA_DIR is
+ * passed explicitly on macOS/Linux — the token file, DB and logs must
+ * land in the USER's data dir, not /var/root. On Windows env can't
+ * cross UAC, so the pre-written api_token.txt does the job and the
+ * frozen binary resolves %LOCALAPPDATA% itself.
+ *
+ * All elevated children are unreachable by kill() — /shutdown is the
+ * only exit path (see shutdownBackend).
+ *
+ * FR: Séparation de privilèges — l'UI tourne SANS privilèges sur tous les
+ * OS ; seul le backend demande l'élévation, une fois par lancement, via
+ * l'invite native de la plateforme :
+ * Windows : Start-Process -Verb RunAs (dialogue UAC)
+ * macOS : osascript « do shell script … with administrator
+ * privileges » (dialogue mot de passe natif — comme sudo,
+ * en version graphique)
+ * Linux : pkexec (dialogue polkit)
+ *
+ * Les processus élevés reçoivent un $HOME différent (root), donc
+ * SNITCH_DATA_DIR est passé explicitement sous macOS/Linux — le fichier
+ * de jeton, la DB et les logs doivent atterrir dans le dossier de
+ * données de L'UTILISATEUR, pas dans /var/root. Sous Windows l'env ne
+ * traverse pas l'UAC, donc le api_token.txt pré-écrit fait le travail
+ * et le binaire figé résout %LOCALAPPDATA% lui-même.
+ *
+ * Tous les enfants élevés sont inaccessibles à kill() — /shutdown est
+ * le seul chemin d'arrêt (voir shutdownBackend).
*/
function launchBackendElevated() {
const dataDir = backendDataDir()
fs.mkdirSync(dataDir, { recursive: true })
fs.writeFileSync(path.join(dataDir, 'api_token.txt'), API_TOKEN, { mode: 0o600 })
- // EN: -FilePath/-ArgumentList carefully quoted (paths may contain spaces).
- // FR: -FilePath/-ArgumentList soigneusement entre guillemets (chemins avec espaces).
- const ps = `Start-Process -FilePath "${backendExe}" -ArgumentList '--port ${backendPort}' -Verb RunAs -WindowStyle Hidden`
- backendProc = spawn('powershell.exe', [
- '-NoProfile', '-NonInteractive', '-WindowStyle', 'Hidden', '-Command', ps,
- ], { windowsHide: true, stdio: 'ignore' })
+ if (isWindows) {
+ // EN: -FilePath/-ArgumentList carefully quoted (paths may contain spaces).
+ // FR: -FilePath/-ArgumentList soigneusement entre guillemets (chemins avec espaces).
+ const ps = `Start-Process -FilePath "${backendExe}" -ArgumentList '--port ${backendPort}' -Verb RunAs -WindowStyle Hidden`
+ backendProc = spawn('powershell.exe', [
+ '-NoProfile', '-NonInteractive', '-WindowStyle', 'Hidden', '-Command', ps,
+ ], { windowsHide: true, stdio: 'ignore' })
+ } else if (process.platform === 'darwin') {
+ // EN: Escape for the AppleScript double-quoted string, then the shell.
+ // FR: Échapper pour la chaîne AppleScript entre guillemets, puis le shell.
+ const esc = s => s.replace(/(["\\$`])/g, '\\$1')
+ const shellCmd = `SNITCH_DATA_DIR="${dataDir}" "${backendExe}" --port ${backendPort}`
+ backendProc = spawn('osascript', [
+ '-e', `do shell script "${esc(shellCmd)}" with administrator privileges`,
+ ], { stdio: 'ignore' })
+ } else {
+ // EN: pkexec strips the environment — `env` re-injects SNITCH_DATA_DIR.
+ // If polkit isn't installed (minimal distros), fall back to a plain
+ // spawn: the UI still works, capture just won't start.
+ // FR: pkexec purge l'environnement — `env` réinjecte SNITCH_DATA_DIR.
+ // Si polkit n'est pas installé (distros minimales), repli sur un
+ // spawn simple : l'UI marche, la capture ne démarrera juste pas.
+ const pkexecBin = ['/usr/bin/pkexec', '/bin/pkexec', '/usr/local/bin/pkexec']
+ .find(p => fs.existsSync(p))
+ if (!pkexecBin) { spawnBackendPlain(); return }
+ backendProc = spawn(pkexecBin, [
+ 'env', `SNITCH_DATA_DIR=${dataDir}`, backendExe, '--port', String(backendPort),
+ ], { stdio: 'ignore' })
+ }
backendElevated = true
backendProc.on('error', err => {
@@ -390,33 +437,38 @@ function launchBackendElevated() {
dialog.showErrorBox('Snitch', `Failed to start backend / Échec du démarrage du backend :\n${err.message}`)
app.quit()
})
- // EN: No 'exit' crash-watch here — the powershell wrapper exits as soon as
- // the elevated child is up; waitForBackend() is the liveness check.
- // FR: Pas de surveillance 'exit' ici — le wrapper powershell sort dès que
- // l'enfant élevé est lancé ; waitForBackend() est le test de vie.
+ // EN: No 'exit' crash-watch here — the wrapper exits as soon as the
+ // elevated child is up; waitForBackend() is the liveness check.
+ // FR: Pas de surveillance 'exit' ici — le wrapper sort dès que l'enfant
+ // élevé est lancé ; waitForBackend() est le test de vie.
}
function launchBackend() {
- /** EN: Spawn the compiled backend with SNITCH_TOKEN + SNITCH_PORT in its
- * environment; windowsHide keeps a console window from flashing;
- * stdout/stderr stream to the log file for diagnostics.
- * FR: Lancer le backend compilé avec SNITCH_TOKEN + SNITCH_PORT dans son
- * environnement ; windowsHide évite l'éclair d'une fenêtre console ;
- * stdout/stderr vont dans le fichier de log pour le diagnostic. */
+ /** EN: Dispatcher — packaged builds elevate the backend on EVERY platform
+ * (capture needs it); dev mode spawns plain so developers can iterate
+ * without password prompts (capture fails without rights, UI works).
+ * FR: Répartiteur — les builds packagées élèvent le backend sur TOUS les
+ * OS (la capture l'exige) ; le mode dev lance sans privilèges pour
+ * itérer sans invite mot de passe (la capture échoue, l'UI marche). */
if (!fs.existsSync(backendExe)) {
dialog.showErrorBox('Snitch', `Backend not found / Backend introuvable :\n${backendExe}`)
app.quit(); return
}
- // EN: Windows packaged build → elevated child, unprivileged UI.
- // Everything else → normal spawn, same privilege as the UI.
- // FR: Build packagé Windows → enfant élevé, UI non privilégiée.
- // Le reste → spawn normal, même privilège que l'UI.
- if (isWindows && !isDev) {
- launchBackendElevated()
+ if (isDev) {
+ spawnBackendPlain()
return
}
+ launchBackendElevated()
+}
+function spawnBackendPlain() {
+ /** EN: Spawn the compiled backend with SNITCH_TOKEN + SNITCH_PORT in its
+ * environment; windowsHide keeps a console window from flashing;
+ * stdout/stderr stream to the log file for diagnostics.
+ * FR: Lancer le backend compilé avec SNITCH_TOKEN + SNITCH_PORT dans son
+ * environnement ; windowsHide évite l'éclair d'une fenêtre console ;
+ * stdout/stderr vont dans le fichier de log pour le diagnostic. */
fs.mkdirSync(logDir, { recursive: true })
const logFd = fs.openSync(logFile, 'a')
@@ -486,20 +538,54 @@ app.whenReady().then(async () => {
createSplash()
backendPort = await findFreePort()
- launchBackend()
- try {
- await waitForBackend()
- } catch (e) {
- // EN: On Windows an elevated backend that never answers usually means
- // the UAC prompt was declined — say so explicitly.
- // FR: Sous Windows un backend élevé qui ne répond jamais signifie
- // généralement une invite UAC refusée — le dire explicitement.
- const extra = backendElevated
- ? '\n\nDid you decline the admin (UAC) prompt? Capture requires it.\nAvez-vous refusé l\'invite administrateur (UAC) ? La capture l\'exige.'
- : ''
- dialog.showErrorBox('Snitch', `Backend unavailable / Backend indisponible :\n${e.message}${extra}`)
- app.quit(); return
+ // EN: Boot loop — if the elevated backend never answers (declined admin
+ // prompt is the usual cause), offer: retry elevation, continue
+ // unprivileged (UI works, capture stays off), or quit.
+ // FR: Boucle de démarrage — si le backend élevé ne répond jamais (invite
+ // admin refusée, cause habituelle), proposer : réessayer l'élévation,
+ // continuer sans privilèges (l'UI marche, la capture reste coupée),
+ // ou quitter.
+ let booted = false
+ while (!booted) {
+ launchBackend()
+ try {
+ // EN: 90 s of patience when elevated — the user may type a password.
+ // FR: 90 s de patience quand élevé — l'utilisateur tape son mot de passe.
+ await waitForBackend(backendElevated ? 90 : 40)
+ booted = true
+ } catch (e) {
+ if (!backendElevated) {
+ dialog.showErrorBox('Snitch', `Backend unavailable / Backend indisponible :\n${e.message}`)
+ app.quit(); return
+ }
+ const choice = await dialog.showMessageBox({
+ type: 'warning', title: 'Snitch',
+ message: 'The admin prompt was declined or timed out. Capture needs it to watch traffic.\n' +
+ 'L\'invite administrateur a été refusée ou a expiré. La capture en a besoin pour observer le trafic.',
+ detail: `Backend unavailable / Backend indisponible : ${e.message}`,
+ buttons: [
+ 'Retry / Réessayer',
+ 'Continue without capture / Continuer sans capture',
+ 'Quit / Quitter',
+ ],
+ defaultId: 0, cancelId: 2,
+ })
+ if (choice.response === 2) { app.quit(); return }
+ if (choice.response === 1) {
+ backendElevated = false
+ spawnBackendPlain()
+ try {
+ await waitForBackend()
+ booted = true
+ } catch (e2) {
+ dialog.showErrorBox('Snitch', `Backend unavailable / Backend indisponible :\n${e2.message}`)
+ app.quit(); return
+ }
+ }
+ // EN: response 0 loops back to launchBackend() → fresh admin prompt.
+ // FR: la réponse 0 reboucle vers launchBackend() → nouvelle invite admin.
+ }
}
createMain()