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）。也就是说，登录用户的应用，以及沙盒内的 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 个条目），并且关闭“自动更新”意味着没有出站流量。