RoamSwitch 架構與安全白皮書

§1

RoamSwitch 是一款適用於 Mac 的選單列應用程式。取決於您對網路的信任程度 目前連接到時，它會自動切換 macOS 防火牆、共享服務、AirDrop、 和 DNS。它還監視 ARP 欺騙、向外部開放的連接埠、USB 儲存和 類似勒索軟體的加密活動，當它檢測到危險的東西時，它會盡可能地 使用資料包過濾器 (pf) 切斷流量－緊急氣隙。

換句話說，RoamSwitch 安裝了一個具有 root 權限的守護進程，如果它願意的話，可以停止所有 Mac 上的網路流量。它是一個人建造的，「請相信我」是不夠的 證明這種特權是合理的。因此，本文檔以您可以驗證的形式解釋了設計。

這是給誰的

• 工程師決定是否安裝
• 想要在評論或文章之前了解內部結構的安全研究人員和記者
• 合作夥伴公司的安全人員評估內部部署或 OEM 捆綁

本文檔不涵蓋的內容

它不涉及檢測閾值調整、誤報統計或 UI 演練。 它解釋的是四件事：特權、進程邊界、資料流和 密碼學。功能規格本身位於捆綁的 MCP 資源中 roamswitch://docs/features 和應用程式內幫助。

揭露內容以及揭露程度（揭露政策）

本文檔是在攻擊者已經擁有分散式二進位檔案的假設下編寫的。 此處顯示的每個端點 URL、識別碼、檔案路徑、XPC 協定和嵌入式公鑰 可以在幾分鐘內從運輸 RoamSwitch.app 中取出 strings、codesign -d 或流量代理。因此將它們寫在這裡 給攻擊者帶來任何新東西。它唯一進步的是審稿人的理解。

另一方面，從二進位檔案看不到的伺服器端實作－rate-limit 閾值、金鑰、管理端點、資料庫架構、Firebase 專案佈局 - 不包括在內。 OEM 和合作夥伴整合設計也超出了本文的範圍，並在單獨的章節中介紹。 內部文件。 「透過觀察客戶你可以學到什麼」是這則訊息的揭露線 文檔。

§2

RoamSwitch.app 由三個可執行檔組成。其中只有一個人享有特權；的 另外兩個以登入使用者權限運行。所有三款產品均啟用了強化運行時、開發人員 ID 簽名並經過公證。

權利和簽署

• 三個目標都有 ENABLE_HARDENED_RUNTIME = true。
• 應用程式沙箱已停用 (com.apple.security.app-sandbox = false)。幫助程序和 MCPServer 的權利是空字典。
• 分發版本經過開發者 ID 應用程式簽署、Apple 公證並裝訂 (§10)。

§3

如何註冊

此幫助程式使用 SMAppService.daemon(plistName:) 註冊為 LaunchDaemon。的 嵌入到應用程式中的 plist (Contents/Library/LaunchDaemons/com.tetsuharu.RoamSwitch.Helper.plist) 僅聲明 Label、BundleProgram、單一 MachServices 條目，以及 AssociatedBundleIdentifiers。由於 SMAppService 的工作原理， 除非應用程式位於 /Applications 中，否則甚至無法註冊。在第一 註冊後，只有用戶在系統中手動批准後，助手才會激活 設定。

它接受誰的連結 (ClientValidator)

助手檢查 NSXPCListener 的連接過程 shouldAcceptNewConnection 並且只將 HelperProtocol 分發給那些 通過。檢查使用 audit_token 而不是 PID， 避免PID重複使用和TOCTOU。

# Release 版本對連線方要求的程式碼簽署條件
identifier "com.tetsuharu.RoamSwitch"
  and anchor apple generic
  and certificate leaf[subject.OU] = "GV76B6G4YU"

此要求透過 SecCodeCopyGuestWithAttributes 檢查並 SecStaticCodeCheckValidity，不通過則斷開連接。僅 為了開發方便，DEBUG 版本刪除了 team-ID 引腳。實際運送的始終是 發佈建置。

助手可以做什麼（完整清單）

Shared/HelperProtocol.swift 中定義的特權操作都是這些。 沒有此處未列出的特權 API。

助手內部的狀態

• HelperTool.shared 是跨連線共享的單一實例。它曾經是每個連線的單獨實例，因此打開新連線的緊急遏制可能會引發一場失去「要帶回哪些服務」的競賽。
• 共享服務和 DNS 備份僅在序列佇列 (stateQueue) 上變更。

§4

touch pf 的四個功能：緊急氣隙、開發伺服器連接埠防護、VPN 隧道 WireGuard 終止開關（§5，1.7.6+）及其 Tailscale 終止開關（§5，1.8.0+ - 僅選定的後端）。他們所有人總是會走 透過單一入口點 PFRulesetCoordinator，並且從不執行 pfctl -f 他們自己。

為什麼只有一個入口點

先前，這兩個功能各自獨立加載帶有 pfctl -f 的規則，相互競爭 超過 pf 的單一主要規則集。如果港口警衛的狹義規則 block ... port {…} 是 在氣隙的 block drop all 之後加載，您最終可能會處於螢幕 說“隔離”，但 Mac 仍然可以訪問。這個bug是透過實際攻擊發現的 來自另一台主機的機器，並在 1.4.3 中修復（故事寫在 docs/marketing/zenn/03_lan_side_attack_test.md)。

現在如何運作

• 每次都完全重建。 整個所需的規則集從當前狀態重建並一次應用。它永遠不會作為 diff 來應用。
• 一個串列佇列。 每個 pf 變更都在同一個 DispatchQueue 上執行，因此無論它來自 XPC 連接、幫助程式的啟動還是故障安全計時器，變更都會按順序處理。
• 優先順序如下（排在上面的優先）。
  1. 緊急氣隙 → set skip on lo0 和 block drop all（不考慮其他）
  2. VPN 終止開關 → block drop all 加 pass quick 僅適用於：lo、隧道介面 (utunN)、與固定端點 IP 的 UDP 握手、DHCP 和 ICMP
  3. 開發伺服器守衛 → block drop in quick proto tcp ... port { … }
  4. None → 重新載入 /etc/pf.conf 並將 pf 返回原始狀態
• 應用後讀回。 pfctl -sr讀回規則以確認block drop all或每個連接埠的規則確實已載入。 pfctl -f 被默默忽略的情況不被視為成功。
• 臨時檔案被寫入包含 UUID 的路徑，並在應用後刪除（v1.4.5 放棄了固定路徑，取而代之的是難以猜測的路徑）。狀態目錄是/Library/Application Support/RoamSwitch。

§5

塊的種類各不相同

如何防止氣隙揮之不去

• 最多在 10 分鐘後解除。助手本身仍會在啟動後立即以及每 60 秒的計時器上執行 releaseAirGapIfExpired()，但作為與之完全獨立的安全網，一個完全不帶 KeepAlive 的專用 LaunchDaemon（AirGapFailsafe）會每 3 分鐘單獨喚醒一次，執行相同的判定與解除。即使助手本身當機、連同其自身的自動解除計時器一起失效，這個安全網也不受影響（1.8.6+）。
• 這個專用守護程式完全不會觸碰互動式助手本身的啟動設定。先前（1.8.5）曾使用助手自身的 KeepAlive.PathState 來實現這一恢復機制，但它偶爾會與正常的應用程式結束操作發生衝突，導致非預期的重新啟動，因此該方案已被撤回，改用目前完全獨立的守護程式方式。
• 時間戳的判定採用單調遞增時間（ProcessInfo.systemUptime）與掛鐘時間相結合的混合方式。通常優先使用單調遞增時間，因此不受 NTP 校正或手動修改系統時間的影響。僅在單調遞增時間不可信時（即重新啟動後：目前值小於已儲存的值，判定為發生了重新啟動）才會回退到掛鐘時間。
• 在重新啟動或守護程式重生後重新套用。 啟動時，幫助程式使用 reapplyFromDisk() 讀取磁碟上的狀態，並依氣隙、連接埠防護、系統預設的順序自行恢復（10 分鐘規則也適用於此）。
• 失敗的提升被視為失敗。 如果 block drop all 實際上無法刪除，則時間戳會被寫回，以便故障安全計時器和重試有一些收斂。螢幕絕不會錯誤地顯示「抬起」。
• 您可以隨時收回控制權 - 使用模式中的提升按鈕，或只需關閉 Wi-Fi。

如何恢復端口防護誤報

未知端口自動阻止（Pro，啟動 Pro 後預設開啟）可以阻止合法端口 LAN 接收器 — LocalSend、Syncthing、啟用防護後啟動的任何內容。當那個 發生時，請透過通知橫幅上的「允許」按鈕或中的匹配行來允許它 “暴露連接埠”螢幕。一次允許的可執行檔被記錄為已知且不會被阻止 再一次（PortAnomalyGuard.allowPort(_:)）。請注意，通用腳本解釋器 （Python、Node.js、Netcat 等）嚴格受 path:port 限制，而非二進位 獨自一人以防止離地生活的攻擊。 Apple系統守護程式滿足 anchor apple（rapportd，支援切換等）不是 首先觀看。

自癒勒索軟體金絲雀誘餌和遏制抑制

如果金絲雀誘餌檔案被篡改或重新命名並觸發緊急氣隙，則釋放 驗證安全性後的遏制會自動重新產生遺失或損壞的金絲雀文件 返回從嵌入模板產生的真實基線雜湊值，立即恢復不間斷的 kqueue 監視（防止對手基線污染）。 此外，在主動遏制期間（顯示緊急模式時），會自動抑制冗餘通知警報和定期後台完整性輪詢的重新觸發事件，以避免在事件回應期間分散用戶的注意力。

下載檔案的多層偵測（靜態簽章 + ClamAV）— 1.8.7 新增靜態簽章層

新出現在下載、桌面或文件資料夾中的檔案，會先經過 StaticSignatureScanner 的輕量級靜態簽章比對（僅檢查前 4MB，只做簡單的 AND/OR 位元組樣式比對，不進行正規表示式或熵值計算）。它不需要 EndpointSecurity entitlement，即使未安裝 ClamAV 也能持續運作。偵測範圍被刻意限定在無需真實惡意軟體樣本也能確保準確性的部分——即業界標準的 EICAR 測試簽章，以及公開的攻擊手法文件（如 PayloadsAllTheThings）中記載的 5 種經典反向 shell 單行指令（bash/sh 的 /dev/tcp/、nc -e、Python 的 pty.spawn、Perl 的 Socket、PHP 的 fsockopen）。我們不會在沒有真實樣本的情況下，為特定惡意軟體家族撰寫位元組層級的「簽章」——那只會帶來一種無法驗證的虛假安全感。這些樣式本身以 XOR 0x5A 混淆後儲存，以避免 RoamSwitch 自身的執行檔因明文包含 EICAR 字串等內容而被 ClamAV 誤判。

只有被靜態簽章層判定為「乾淨」的檔案，才會繼續進入 ClamAV 掃描。新出現在下載、桌面或文件資料夾中的檔案，無論是否帶有 .tmp 副檔名或 com.apple.quarantine 屬性（例如透過終端機複製而來），都會立即被 ClamAV 掃描。EICAR 等業界標準測試簽章會被視為「無害」，不發出通知，僅記錄至通知歷史，也不會被隔離或攔截（只有真正的惡意軟體樣本才會被隔離）。此外，即使隔離資料夾（Quarantine）中已存在同名的歷史隔離檔案，新的威脅也會以帶時間戳記的唯一檔名可靠地移入隔離資料夾，徹底避免因命名衝突導致威脅殘留在原始位置的漏判情況。

監控新的自動啟動註冊（LaunchAgent/LaunchDaemon）— 1.8.7

透過 FSEvents 即時偵測新放置到 ~/Library/LaunchAgents、/Library/LaunchAgents、/Library/LaunchDaemons 中的 .plist 檔案（PersistenceMonitorGuard）。由於不使用 EndpointSecurity 的 ES_EVENT_TYPE_AUTH_CREATE，因此無法攔截寫入行為本身，能做到的是在寫入後的數秒內察覺並判定其內容。

判定的關鍵不在於「執行檔本身的簽章」，而在於「它直接要啟動的是什麼」。2026 年報告的實際手法——例如偽裝成 Google Update 的 LaunchAgent 中隱藏經 Base64 編碼的 bash 指令碼，或 root 權限的 LaunchDaemon 在每次啟動時重新執行經 Base64 編碼的 AppleScript 酬載——都是把惡意程式碼藏在指令碼本身裡，同時直接呼叫簽章合法的 /bin/bash 或 /usr/bin/osascript。只檢查執行檔本身簽章的驗證方式會被這類手法完全繞過。因此，任何新註冊的 LaunchAgent/LaunchDaemon，只要直接啟動裸腳本直譯器（bash、sh、zsh、osascript、python3、perl、ruby、php 等），即使該直譯器本身的簽章合法有效，也會被無條件發出警告。傳遞給它的引數還會進一步交給 StaticSignatureScanner 判定，如果包含已知的可疑樣式，會一併寫入通知。透過 BundleProgram（指向應用程式套件內已簽章的編譯執行檔的形式，包括 RoamSwitch 自身的 Helper）註冊的項目，則照常僅透過 codesign --verify --strict 進行簽章驗證。

偵測 ClickFix 並觸發緊急遮斷 — 1.8.7，預設關閉

「ClickFix」是一種社交工程攻擊手法：偽造的 CAPTCHA 或錯誤提示畫面會指示您「開啟終端機並貼上以下指令以完成驗證」，誘使使用者親自執行該指令。偵測到的數量在 2024 至 2025 年間激增超過 500%，截至 2026 年，它已被視為 macOS 上最猖獗的攻擊途徑之一。由於實際執行的是使用者自己合法的 shell 操作，因此會完全繞過 Gatekeeper 的簽章驗證。

選單列 →「惡意軟體防護」→ ClickFix 防護（Pro，預設關閉）。透過 FSEvents 監控對 ~/.zsh_history、~/.bash_history 的附加寫入（僅針對該防護啟動後新增的行，不會回溯既有歷史記錄），只偵測與 StaticSignatureScanner 共用的反向 shell 單行指令，以及將 Base64 解碼內容直接透過管線傳入 shell 或 osascript 的特定組合樣式。正規安裝程式中極為常見的單獨 curl | bash，由於與 Homebrew、rustup、nvm 等官方安裝步驟難以區分，被刻意排除在偵測範圍之外。一旦偵測到符合項，就會觸發前文所述的緊急氣隙。由於指令已經執行完畢，這屬於事後應對，但仍有可能攔截正在進行中的多階段酬載下載或憑證外洩。與其他氣隙觸發條件一樣，它最多會在 10 分鐘後自動解除（見本節開頭）。

已知的限制。 由於偵測的前提是寫入 shell 歷史記錄，因此無法應對繞過終端機、直接透過 applescript:// URL scheme 呼叫 Script Editor、且完全不向磁碟寫入酬載的無檔案（fileless）變種。針對此類變種，Apple 自身也導入了一定的緩解措施（對未識別指令碼彈出確認對話框），但也有報告指出存在繞過該措施的變種。我們在真機上使用 macOS 統一日誌（log show／log stream）對這條路徑進行了驗證，但未能找到可用於判定的特有日誌訊號。與其把無法涵蓋的部分標榜為已涵蓋，我們選擇如實說明這項限制。

Docker 風險偵測防護 — 1.8.9，Pro・預設關閉

選單列 →「惡意軟體防護」→「偵測 Docker 特權容器・docker.sock 掛載」（DockerEventGuard）。由於該程式碼庫中沒有像 docker events 那樣建立持久串流連線的先例，因此採用與 PortAnomalyGuard 相同的定時輪詢方式。每 20 秒透過輕量的 docker ps -q 取得容器 ID 集合，僅對與上次的差異（新啟動的容器）透過 docker inspect --format 進行詳細確認。用於判定的格式字串特意與 Linux 版的 roamswitch_core::health::LinuxHealthChecker::DOCKER_INSPECT_RISK_FORMAT 保持一致，因此兩個平台會偵測完全相同的條件（--privileged 啟動，或 /var/run/docker.sock 綁定掛載）。

即使偵測到也不會自動封鎖。特權容器或 docker.sock 掛載是可能導致容器逃逸的高風險「設定」，但並非已確認的入侵（也存在正當用途，例如刻意以 privileged 模式執行監控代理）。由於大多數使用者並不使用 Docker，因此即使在 Pro 授權下也預設保持關閉。不使用 EndpointSecurity entitlement；docker CLI 依 Docker Desktop 預設安裝路徑・Homebrew・which 的順序尋找。已在真實 Docker Desktop（29.7.2）環境中驗證 privileged 容器・docker.sock 掛載容器・一般容器三種情境，確認無誤判也無漏判。

機密資訊・API 金鑰外洩稽核 — 1.8.4 新增，1.8.9 支援資料夾掃描

選單列 →「惡意軟體防護」→「機密資訊・API 金鑰外洩稽核」。貼上文字後會立即偵測 API 金鑰與權杖的外洩模式，顯示行號、已遮罩的字串以及依類型給出的建議處理方式（SecretLeakAuditor，完全本機處理）。1.8.9 新增「選擇資料夾掃描」功能，使用相同的偵測引擎對目錄（如原始碼簽出目錄）進行遞迴稽核（auditDirectory(at:)）。會自動排除 .git・node_modules・target・vendor・dist・build・__pycache__・venv，並跳過超過 2MB 的檔案或判定為二進位的檔案。處理在獨立執行緒中進行以避免阻塞主執行緒，且絕不會向外部傳送任何內容。

Link Guard（阻止網路釣魚連線）— 1.7.2 及更高版本，在 1.8.0 中得到強化

選單列→「惡意軟體防護」→「連結防護」（專業版）。阻止裝置上所有瀏覽器和應用程式與網路釣魚/詐騙網站的連線。 有兩個執行點，依優先權順序一起使用。

• ① 內容過濾系統擴充（RoamSwitchLinkFilter，1.8.0+，一旦獲得批准即首選）。 NEFilterDataProvider 系統擴充 — 未經 Apple 審查（內容過濾器提供者為自助服務，無核准佇列）。它檢查 名稱解析之後的實際出站 TCP 流 。目標名稱來自作業系統解析的主機名，或未能從流的第一個位元組解析 TLS SNI — 因此瀏覽器執行自己的 DoH/DoT 並連接到裸 IP 仍會被阻止。它從不重寫 /etc/hosts 並將每個流歸因於一個進程。 QUIC (UDP/443) 沒有可讀的 SNI，因此在 block 模式下它會被丟棄，迫使瀏覽器回退到 TCP 上的 HTTP/2。需要在系統設定中一次性批准。
• ② /etc/hosts 水槽（回退，當擴充未核准/拒絕時）。 特權幫助程式將目標網域寫入 /etc/hosts 的分隔託管部分作為 0.0.0.0 並刷新快取。上限為 60,000。一旦擴充功能處於活動狀態，此部分就會被刪除。
• 三種模式。 「關閉」停用它。 「僅警告」 暫停 匹配的連線並詢問使用者（請參閱下方的 Real warn）。 「自動阻止明顯的詐騙網站（建議）」立即下降。 從 1.7.2. 開始預設為區塊
• Real warn（1.8.0+，僅限擴充）。 在 warn 上點選系統擴充功能 holds 流（作業系統命名的路徑和 SNI 路徑）與 .pause() 且應用程式會引發「允許/阻止」通知。當使用者的點擊達到 allowlist.txt / extra.txt 時（擴充功能每 1.5 秒輪詢一次小狀態檔案），保留的流將恢復（允許）或刪除（封鎖）。 25 秒內沒有答案將失敗 open（警告是建議性的）。此決策會按主機快取（允許 5 分鐘/阻止 1 小時），因此頁面的其他流程和後續存取都是即時且強制執行的。 block 通知未更改：「已封鎖…」和「允許一次（5 分鐘）」按鈕。
• 只有明確的案例才會被阻止。 威脅來源上的清單或品牌名稱 Unicode 同形異義詞 - 其他所有內容（高風險 TLD、子網域模仿等）都是警告。判決引擎與 Linux 版本共享，並且不會向任何地方發送 URL。
• 從錯誤的區塊中恢復。 從通知或選單允許網域（5分鐘或永久）。重新產生該部分時，將減去允許清單。
• Pro-gate. 強制執行 (applyMode()) 僅發生在有效的 Pro 許可證上。如果沒有 Pro，模式會被存儲，但 /etc/hosts 永遠不會被觸及。許可證的啟動或失效將在會話期間生效。
• 源和捆綁種子。 阻止清單來自簽署的威脅來源（第 7 節，使用來源專用金鑰進行驗證）。即使在第一次提取之前，它也適用於應用程式的捆綁種子（約 60,000 個條目），並且關閉「自動更新」意味著沒有出站流量。