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).

§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 is kept from lingering

• It lifts after 10 minutes at most. The helper itself still runs releaseAirGapIfExpired() right after startup and on a 60-second timer, but as a fully independent safety net, a dedicated LaunchDaemon (AirGapFailsafe) with no KeepAlive at all wakes on its own every 3 minutes and performs the same check and release. If the helper itself crashes and takes its own self-release timer down with it, this safety net is unaffected (1.8.6+).
• 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 re-applies after a reboot or a daemon respawn. On startup the helper reads the on-disk state with reapplyFromDisk() and restores it itself, in the order air-gap, port guard, system default (the 10-minute rule applies here too).
• 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 back control at any time — with the lift button in the modal, or simply by turning off Wi-Fi.

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.

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.

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 CLI (brew install 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.
• 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 these eight, 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 no traffic occurs during normal use
sudo tcpdump -i any -n 'host not 127.0.0.1' and 'not port 53'
# No traffic other than license activation, update checks, and ClamAV definition updates

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 identifiers. 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 definitions of 5 tools. 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}'