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) 上變更。

輔助程式內部的權限分離，以及為讀取 SSH 日誌而設的例外

輔助程式在啟動後立即替自己加上一道由核心強制執行的上限（執行階段沙盒，與上文 App Sandbox 的 entitlement 是兩回事），它啟動的子行程也會繼承。這道上限會阻止替換系統程式、註冊 LaunchDaemon 或 LaunchAgent、改寫 sudoers、PAM、sshd 的設定、直接寫入本機目錄儲存區，以及執行位於使用者目錄、外接磁碟區、暫存資料夾等可寫位置的程式。它不會阻止透過 Open Directory（dscl）進行的帳號變更，也不限制網路收發（那不是這道上限的對象）。

在這道上限之下，/usr/bin/log 無法執行。在 macOS 26 上，log 不能在沙盒內執行（log: Cannot run while sandboxed），以降權後的 nobody 身分也不能執行（Must be admin）。也就是說，登入使用者的 App，以及沙盒內的 root 輔助程式，都讀不了 sshd 的日誌（統一日誌）。SSH 暴力破解偵測必須讀取這份日誌，所以在權限分離上設了一個例外。

這個例外，是在輔助程式進入沙盒之前，先以 --ssh-log-reader 啟動同一個二進位檔而得到的一個小型 root 行程。該行程只接受 1 位元組的指令（開始與停止），只會以固定的引數（log stream --style ndjson --level info，以及只保留 sshd 行的固定條件）啟動 /usr/bin/log。它不傳遞環境變數，呼叫端也沒有任何途徑指定引數或指令。它不讀取、也不解譯日誌內容，輸出會流入輔助程式交給它的管線。

日誌行中含有使用者名稱等攻擊者可以寫入的字串，所以 root 輔助程式不解譯這些行。它把每一行交給以 nobody 身分執行、在禁止網路、寫檔案、啟動與複製行程的沙盒中的解析工作行程去解譯，來源位址則取自不受使用者名稱影響的行尾（IP port N）。在關閉了遠端登入的 Mac 上，這個行程不會啟動 log，什麼也不讀。可以透過輔助程式的 XPC 呼叫的 SSH 相關操作共有 5 個：套用設定、取得狀態、紀錄與登入，以及解除封鎖，沒有傳入任意指令的途徑。

§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

塊的種類各不相同

讓 Air-Gap 既不滯留、也不會被等出來的機制

• 結束方式取決於觸發的可信度（1.9.52 起）。勒索軟體誘餌檔案遭竄改、XProtect 的確定偵測，以及回應 ARP 警告的手動隔離屬於「高可信度」；ClickFix、連接埠異常等屬於「低可信度」。低可信度的隔離仍然最長 10 分鐘自動解除。高可信度的隔離在 10 分鐘時不會解除：僅憑時間就完全解除，攻擊者只要等待就能脫離隔離。
• 高可信度的隔離會維持完全隔離直到上限（預設 1 小時，可在設定中改為 5 分鐘到 24 小時），並在此確認原因。對勒索軟體而言，只有在可疑程序已被識別且已結束、並且誘餌檔案自偵測時起未再變動時，才認定原因已消除並解除。無法確認時轉入「降級模式」。降級模式持續阻擋新連線（迴路與 DHCP 除外），只恢復 Wi-Fi 無線電，讓使用者能確認狀況。它不會因為時間過去而開啟。只有使用者解除，或確認原因已消除時才會開啟。
• 開始隔離時，也會切斷先前已經開啟的對外連線。清空 pf 的狀態表（pfctl -F states），停止隔離之前就已持續的通訊。轉入降級模式時同樣會切斷。
• 由 ARP 詐騙引起的隔離，只有在無需任何通訊即可確認原因已消除時，才會自動解除。確認只讀取 ARP 快取（不傳送封包），當受信任的閘道 MAC 連續 3 次、跨度至少 60 秒都被看到時，判定原因已消除。但隔離期間，閘道的 ARP 項目可能會從鄰居表中消失（已在實際 Mac 上確認），此時無法確認。這種情況下，它會一直維持降級模式，直到手動解除。
• 即使輔助程式當機，解除判定也不會停止。完全沒有 KeepAlive 的專用 LaunchDaemon（AirGapFailsafe）每 3 分鐘獨立啟動一次，做出與輔助程式相同的判定（低可信度：10 分鐘解除；高可信度：在上限時確認原因後降級）。即使輔助程式本身當機、連同自我解除的計時器一併遺失，這道安全網也不受影響（1.8.6 起；依可信度判定自 1.9.52 起）。
• 這個專用守護程式完全不會觸碰互動式助手本身的啟動設定。先前（1.8.5）曾使用助手自身的 KeepAlive.PathState 來實現這一恢復機制，但它偶爾會與正常的應用程式結束操作發生衝突，導致非預期的重新啟動，因此該方案已被撤回，改用目前完全獨立的守護程式方式。
• 時間戳的判定採用單調遞增時間（ProcessInfo.systemUptime）與掛鐘時間相結合的混合方式。通常優先使用單調遞增時間，因此不受 NTP 校正或手動修改系統時間的影響。僅在單調遞增時間不可信時（即重新啟動後：目前值小於已儲存的值，判定為發生了重新啟動）才會回退到掛鐘時間。
• 重新啟動或常駐程式重建之後會重新套用。輔助程式啟動時以 reapplyFromDisk() 讀取磁碟上的狀態，依 Air-Gap、連接埠防護、系統預設的順序自行還原。隔離的狀態（可信度、完全或降級）與已經過的時間也會沿用，計時從最初觸發的時刻繼續（已在實際 Mac 上重新啟動輔助程式確認）。
• 失敗的提升被視為失敗。 如果 block drop all 實際上無法刪除，則時間戳會被寫回，以便故障安全計時器和重試有一些收斂。螢幕絕不會錯誤地顯示「抬起」。
• 使用者可以隨時奪回主導權：透過選單列的「解除 Air-Gap 隔離」、彈出視窗中的解除按鈕，或直接關閉 Wi-Fi。解除操作不需要 Pro 版（即使隔離過程中 Pro 到期也可以解除）。

如何恢復端口防護誤報

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

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

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

通用熵值型勒索軟體偵測 — 1.10.0，Pro，預設開啟

透過 FSEvents 監控 Documents・Desktop・Downloads・Pictures 資料夾，當 Shannon 熵超過閾值（7.92）的寫入在 5 秒內以 20 個以上檔案的突發形式出現時進行偵測。與金絲雀（誘餌檔案）方式不同，本功能不依賴於對誘餌檔案的操作，因此也能偵測到沒有誘餌檔案位置發生的加密。僅在達到閾值時才使用 lsof 確定當時的處理程序，並與允許清單（cp・mv・ditto・tar・ffmpeg・Xcode・Time Machine・主流瀏覽器等）進行核對。偵測到後，會透過與金絲雀防護相同的 RansomwareContainmentManager 自動封鎖網路。

Linux 版透過 fanotify 為寫入事件附加 PID，因此可以按處理程序追蹤突發寫入。由於 macOS 既沒有 fanotify，（基於方針）也沒有 EndpointSecurity，本實作僅透過 FSEvents 取得路徑，並不依賴處理程序而是全域計算突發寫入。侷限：當多個合法處理程序同時寫入大量高熵檔案時（例如多個壓縮・加密工作重疊的情況），本功能可能比 Linux 版更容易出現誤判。

用於勒索軟體復原的事前快照（Mac）

偵測時拍攝的快照已包含偵測之前被加密的檔案，因此不能作為回復點。所以無論是否偵測到，都會定期建立 APFS 本機快照（預設每 6 小時，可選關閉、1、3、6、12、24 小時）。一旦發生偵測，新的事前快照與舊快照清理會暫停最多 7 天（保留模式），避免加密後的狀態擠掉最後一份加密之前的快照。復原一律由人手動進行，只把選定的檔案取出到 ~/RoamSwitch-Recovered/ 下，不會覆寫目前的檔案，也不提供整個磁碟區的還原。取出檔案需要掛載快照，因此特權輔助程式需要完整磁碟取用權限（沒有該權限時仍會建立快照）。macOS 可能在可用空間不足等情況下自行刪除本機快照，無法保證保留超過約 24 小時。復原視窗屬於 Pro 功能（快照的建立本身在非 Pro 下也會執行）。

鑑識證據包 — 1.10.0

當金絲雀偵測或勒索軟體熵值偵測等觸發緊急 Air-Gap 時，會在不阻擋隔離處理本身的背景佇列中，將當時的處理程序清單（ps）・網路連線（lsof -i）・最近 5 分鐘內變更的檔案・可疑處理程序已開啟的檔案清單，儲存至 ~/Library/Application Support/RoamSwitch/incident-evidence/<時間戳記>/manifest.json。manifest 中記錄了每項證據的 SHA-256，可用於事後竄改偵測。可透過 MCP 的 get_forensic_evidence_bundles 工具取得清單。侷限：由於設計上不使用 EndpointSecurity 等權限，本功能不會擷取封包或處理程序的記憶體・檔案描述符快照。

程序執行記錄（Mac，Pro，預設關閉）

特權輔助程式把 macOS 內建的 /usr/bin/eslogger（exec、fork、exit）當作子程序啟動，只在這台 Mac 內記錄程序的啟動。不申請 EndpointSecurity 權限（不呼叫 es_new_client），需要在系統設定的「完整磁碟取用權限」中允許 RoamSwitch（清單中沒有時，用「+」加入 /Applications/RoamSwitch.app）。沒有授權期間，狀態顯示為「無法使用」並等待，每 60 秒重新確認一次（不會切換為高負載的輪詢）。只做通知。不會阻止執行、切斷通訊或隔離。

對以下 10 種行為發出通知。瀏覽器・Office・郵件應用程式直接啟動 shell／從暫存資料夾或帶隔離屬性的位置執行未簽章的二進位檔案／下載後傳給 shell 的單行指令（伴隨原始 IP 的 URL、base64、eval、停用 TLS 驗證等情況）／使用 base64 或 eval 的 osascript／剛移除隔離屬性後立即執行該檔案／從剛寫入的自動啟動註冊（LaunchAgent・LaunchDaemon）啟動未簽章的二進位檔案／非 Apple 簽章的父處理程序取得鑰匙圈中的機密資訊（如 security find-generic-password -w）／base64・eval 解碼與 curl・wget・exec・system 呼叫同時出現在同一行的 python3・perl・ruby・php・pwsh 的 -c／-e／-Command 單行執行（1.10.0 起。僅使用 base64 或僅使用 eval 不會觸發）／設定 DYLD_INSERT_LIBRARIES 環境變數後啟動處理程序（1.10.0 起。為避免洩漏機密，僅讀取這一個環境變數的值，且不針對 Apple 簽章的處理程序）／指令列直接指定 RoamSwitch 放置的誘餌憑證檔案（如 ~/.aws/credentials、~/.env.backup，內容中帶有標記）的執行（如 cat、tar、curl -F；真實檔案不會符合，透過函式庫讀取的情況由蜜罐權杖監視負責）。每項偵測都會附帶 MITRE ATT&CK 技術 ID。

只有嚴重程度高的偵測才會以橫幅顯示，同一種類每 10 分鐘合併為一次（記錄中保留全部）。Claude Code、GitHub CLI 等開發工具讀取自己憑證的行為預設不通知。若其他程式讀取，可用通知中的「允許此程式」只放行該項目（有簽章時依 Team ID，沒有時依執行檔名稱，並與項目名稱配對）。

記錄以僅 root 可讀的形式儲存（目錄 0700、檔案 0600），預設保留 200 MB、14 天。不儲存環境變數，但命令列引數中可能含有機密。每個區段以連接到前一區段雜湊的雜湊鏈封存，「驗證鏈」可偵測竄改、區段缺漏與封存被刪除（均已在實際 Mac 上確認）。這是對竄改的偵測，而非防止。最新區段的刪除或回溯無法偵測。讀取經由輔助程式的 XPC，MCP 則經由應用程式（含 Pro 再確認）。

限制：輔助程式啟動前，或啟用記錄之前的執行不會被記錄。eslogger 是事後觀察，無法阻止。在每秒數千次程序啟動的負載下會有遺漏（會在畫面顯示數量，並持續運作）。這項記錄不能取代 EDR（端點偵測與回應）。

憑證蜜罐權杖 — 1.10.0，Pro，預設開啟

在 ~/.aws/credentials・~/.ssh/id_rsa_backup・~/.docker/config.json 三處放置帶有標記的偽造憑證檔案。如果該位置已存在真實檔案，絕不會覆寫。存取偵測除了使用與金絲雀防護相同的 kqueue（DispatchSource.makeFileSystemObjectSource）之外，由於沒有 EndpointSecurity 無法可靠捕捉 open() 事件，還並行採用每 30 秒一次的存取時間輪詢。偵測僅發出通知，不會封鎖或隔離。ssh 誘餌使用 ssh 預設不會尋找的名稱（而非 id_rsa），因此不會破壞正常的 ssh 執行，也不會產生誤報。AWS 誘餌使用獨立的設定檔名稱而不是 [default]，Docker 誘餌指向不存在的內部映像倉庫，並且都以 0600 權限放置（自 1.10.3 起）。除這三處外，還會在 ~/.pypirc 與 ~/.env.backup 放置誘餌（針對搜尋 PyPI 權杖、.env 與 AI API 金鑰的行為）。不使用 ~/.npmrc，因為 npm 平時每次都會讀取；也不使用 GCP 憑證，因為偽造的檔案會破壞正常驗證。誘餌一旦被真實存取，就會額外放置一個相關誘餌（~/.aws/config、~/.ssh/config 或 ~/.kube/config）並一併監視（連鎖只延伸一步，不會覆寫既有檔案）。

瀏覽器憑證存取監控 — 1.10.0，Pro 內也需主動啟用，預設關閉

透過 FSEvents 監控 Chrome・Brave・Edge・Vivaldi・Chromium・Firefox 已儲存密碼/Cookie 資料庫的寫入。發生突發寫入時，使用 lsof 確定處理程序，將瀏覽器本身・Spotlight 等索引程式・備份守護程序以外的情況作為偵測對象。與其他新增防護不同，即使啟用 Pro 也不會自動開啟。這是因為瀏覽器擴充功能或密碼管理器的匯入功能等仍存在固有的誤判風險。

與 Sensor 的通訊（TLS 與簽章）

與同一區域網路內的 RoamSwitch Sensor（另一產品）進行配對、稽核請求與結果取得時，使用固定憑證指紋（SHA-256）的 TLS 1.3（Sensor 0.3.9 及以上）。指紋不透過網路取得，而由使用者輸入 Sensor 畫面上顯示的值。不驗證憑證授權單位、主機名稱與有效期限，只信任固定的值。TLS 失敗也不會切換為明文（切換會讓中間人得以降級）。請求簽章包含時間戳記與 nonce（v2），以防重送。只有沒有指紋的舊格式配對仍照舊以明文連線，並給出警告。

憑證變更時會拒絕連線。固定值的更新不會自動進行，只有當使用者輸入並確認新值、且實際透過 TLS 往返並成功完成帶簽章的探測時才會儲存。限制：這項探測並不能用金鑰核對該 Sensor 與先前配對的是否為同一台。它以使用者輸入在 Sensor 畫面上確認過的值為前提。

下載檔案的多層偵測（靜態簽章 + 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）中已存在同名的歷史隔離檔案，新的威脅也會以帶時間戳記的唯一檔名可靠地移入隔離資料夾，徹底避免因命名衝突導致威脅殘留在原始位置的漏判情況。

開發用 Web 資料夾中的 Web Shell 偵測（Web Rules）

對本機 Web 開發（~/Sites、MAMP、Herd、Local、/Library/WebServer/Documents，以及登記用於套件 CVE 比對的專案資料夾）中的 PHP、JavaScript、JSP、ASP 檔案，使用與 Linux 版相同的 18 條偵測規則進行檢查。規則只描述公開記載的手法，不含從真實樣本擷取的簽章。規則分三層：內建於應用程式、每天一次帶簽章的僅接收更新（併入現有的同一次取得），以及 ~/Library/Application Support/RoamSwitch/rules.d 中的自訂規則（只讀取擁有者為 root 或本人、且群組與其他使用者不可寫的檔案）。下載等已在監視的資料夾在寫入後立即檢查，開發用 Web 資料夾每天一次並可手動檢查（每天一次的檢查不會進入 node_modules 與 .git；指定資料夾的檢查會進入 node_modules）。由於不使用 EndpointSecurity，無法在執行前阻止，全部為事後偵測。

預設只自動隔離 critical。high 不會觸碰檔案，只會出現在通知與設定畫面的清單中，並可選擇「今後不再偵測」（隔離層級可在設定中變更）。偵測後掛鉤（~/Library/Application Support/RoamSwitch/hooks/post-detection）僅在擁有者為 root 或本人且他人不可寫時執行，30 秒後終止。帳號處置（預設關閉，開啟需要管理員密碼）會停用被隔離檔案擁有者的登入 shell，但不會處理 root、UID 低於 501 的帳號以及已登入的使用者（包括正在使用這台 Mac 的您）。已在 macOS 26 虛擬機中，以 root 身分在與輔助程式相同的沙盒下，驗證了真實的 dscl 變更並還原 shell（沙盒會阻止對 dslocal 的直接寫入，但不會阻止透過 dscl 進行的變更）。管理員密碼確認以及從應用程式到輔助程式的呼叫路徑尚未在真機上驗證。在開發資料夾的 114,501 個檔案中偵測到 0 筆。

監控新的自動啟動註冊（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 個條目），並且關閉「自動更新」意味著沒有出站流量。