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 个条目），并且关闭“自动更新”意味着没有出站流量。