RoamSwitch Sensor 运维手册

本指南是 RoamSwitch Sensor 的安装与运维指南。只需部署在局域网中，即可检测同一网段内的新设备出现与伪装行为，并对已安装 RoamSwitch（Mac / Linux Client / Server Edition）的端点执行主动漏洞审计。通过 apt / dnf 软件包分发。

1. 概述与定位

RoamSwitch（Mac / Linux Client / Server Edition）无论哪个版本，本质上都是常驻在主机上的代理程序。这种形态存在两个结构性盲区。

• 单一主机的自我诊断存在原理性盲区：所谓"对外部封闭，但在同一局域网内的其他终端看来却完全暴露"的横向移动（lateral movement）风险，仅靠主机自身审视自己是无法察觉的。
• 有些设备根本无法安装 RoamSwitch：IoT 设备（网络摄像头、智能插座、多功能一体机）、访客/BYOD 终端、网络设备本身、嵌入式设备等。

RoamSwitch Sensor 是部署在局域网中的专用节点，旨在填补这两个空白。目前已实现并验证的功能包括：针对同一局域网内已安装 RoamSwitch 的端点进行主动漏洞审计、通过 ARP 扫描和 ARP 表监控建立局域网设备台账，并检测新设备出现与欺骗行为，以及通过需主动开启的被动抓包，提供可疑行为（连接恶意 IP、僵尸网络化、DNS 隧道迹象等）的参考信息（参见 §6）。Sensor 只做检测和报告，不会阻断通信。它不是 EDR，而是被设计为轻量级 NDR（Network Detection & Response）与自研的实证型漏洞扫描器相结合的产品。

不内置自我防护功能（这是刻意的设计决策）。如需针对 Sensor 主机本身进行攻击防护，建议在同一台机器上另行安装 RoamSwitch for Linux 的 Server Edition。两者可作为完全独立的进程共存，互不冲突。

2. 当前验证环境

• 支持的操作系统：Debian 12 (bookworm) 及以上 / Ubuntu 22.04 及以上（apt）、Fedora / RHEL 系列（dnf）。仅支持 x86_64（amd64），arm64 目前尚不支持。
• 预期硬件（未来计划）：实际运行时设想使用无风扇 N100/N150 系列迷你 PC 等适合常驻运行的低功耗设备，但目前尚未提供针对此的专用构建与交付。
• 网络部署：需在物理或逻辑上连接到被监控局域网的网段（roamswitch-sensor.service 使用主机网络常驻运行——因为需要直接观测 ARP 表）。此外，为了接受端点侧的配对和审计请求，必须使用固定 IP 地址（静态分配，或在 DHCP 服务器上做地址保留）运行。监听 TCP 50543 端口（默认监听所有接口。可通过 control.bind_addr 更改，并在同一端口上接受 TLS 1.3 —— §4.4）。
• 资源占用：常驻内存约数十 MB，空闲时 CPU 负载极低。
• 推荐：nmap（用于 ARP 扫描、NSE 补充诊断和定期审计的 MAC 确认。未安装时其他功能仍可运行，但不会进行 ARP 扫描，只会变为仅观察 Sensor 曾通信过的设备的被动模式）。

3. 安装与启动

从官方签名的软件包仓库安装 roamswitch-sensor 软件包。安装后，roamswitch-sensor.service（systemd）会自动启用并启动。

3.1 APT（Ubuntu / Debian）

# 1. 注册仓库签名密钥
curl -fsSL https://lafine.net/apt/roamswitch-archive-keyring.asc \
  | sudo gpg --dearmor -o /usr/share/keyrings/roamswitch-archive-keyring.gpg

# 2. 添加仓库
echo "deb [signed-by=/usr/share/keyrings/roamswitch-archive-keyring.gpg] https://lafine.net/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/roamswitch.list

# 3. 安装
sudo apt update && sudo apt install roamswitch-sensor

3.2 DNF / RPM（Fedora / RHEL）

# 1. 导入 GPG 密钥
sudo rpm --import https://lafine.net/rpm/RPM-GPG-KEY-roamswitch

# 2. 添加仓库配置文件
sudo curl -fsSL -o /etc/yum.repos.d/roamswitch.repo https://lafine.net/rpm/fedora/roamswitch.repo

# 3. 安装
sudo dnf install roamswitch-sensor

3.3 确认启动

systemctl status roamswitch-sensor.service
sudo roamswitch-sensor status

3.4 运行 CLI / TUI

CLI（roamswitch-sensor）与交互式 TUI（roamswitch-sensor-tui）安装后即可直接运行。

sudo roamswitch-sensor status
sudo roamswitch-sensor-tui

4. 配对（配对码方式）

Sensor 在初始状态下不信任任何设备。配对通过 Sensor 运营者发放的一次性配对码进行。「Sensor 可对该端点执行主动漏洞审计」这一信任关系，会在一次配对操作中同时向双向建立（不存在仅单向信任的状态）。

前提条件：请以固定 IP 地址（静态分配，或在 DHCP 服务器端预留地址）运行 Sensor。配对完成后，端点此后始终直接连接配对时确认的那个 Sensor IP 地址（不再通过 mDNS 等方式自动发现），因此若 Sensor 的 IP 后续发生变化，需要重新配对。端点一侧可以继续使用动态 IP。

4.1 发放配对码（Sensor 一侧）

# 在 Sensor 一侧执行（TUI 中为 c 键）
sudo roamswitch-sensor issue-code

系统会发放一个 8 位（大写字母与数字，已排除容易误读的 0/O/1/I/L）的一次性配对码。该码发放后 10 分钟即失效且仅可使用一次，请通过口头、聊天等任意带外方式尽快告知端点侧的操作者。同时还会显示此 Sensor 的 TLS 证书指纹（SHA-256）。这是需要在端点侧固定的值，请与配对码一并告知（也可随时通过 roamswitch-sensor pairing show 或 TUI 的 T 界面查看）。

4.2 使用配对码完成配对（端点一侧）

# 端点侧 (roamswitch-linux)
sudo roamswitch sensor pair --addr <SENSOR_IP> --code <CODE> --fingerprint <SHA256_FINGERPRINT>

在 Mac 版中，可通过菜单栏的「🔍 RoamSwitch Sensor 配对…」，输入 Sensor 的 IP 地址、配对码和证书指纹，以图形界面完成同样的操作。

配对成立后，此后的主动漏洞审计和审计结果获取都将通过 Ed25519 签名进行认证。Linux 版的端点仅与持有和所输入指纹一致的证书的 Sensor 通过 TLS 1.3 通信，不会自动回退为明文（§4.4）。知道 Sensor 所发放配对码的端点一侧，与收到该码的 Sensor 一侧，此时都会将对方视为已受信任。

4.3 手动配对（已直接掌握公钥的情况）

如果 Sensor 运营者已经通过带外方式掌握了端点的公钥和地址，也可以不经过配对码交换，直接在 Sensor 一侧完成登记（通常建议使用 §4.2 的配对码方式，让端点自行完成配对）。可通过以下命令查询自己的公钥和地址。

# 在端点侧查看自身的公钥/地址
sudo roamswitch sensor key

# 在 Sensor 侧查看自身的公钥/地址/MAC 地址
sudo roamswitch-sensor status

# Sensor 一侧
sudo roamswitch-sensor pair <完整公钥> --addr <IP 地址> --confirm

4.4 控制 API（TCP 50543）的安全：TLS、指纹、锁定

配对、审计请求和结果获取都通过 Sensor 的控制 API（TCP 50543）进行。其内置了以下防护。

• TLS 1.3 与证书固定：配置项 control.tls（重启守护进程后生效）可选 off（仅明文）/ optional（默认。在同一端口上同时接受 TLS 1.3 和旧的明文，每次接受明文都会发出警告）/ required（仅 TLS 1.3）。证书为自签名（ECDSA P-256），信任不取决于有效期或名称，而取决于 SHA-256 指纹的固定。固定值不会通过网络获取，而由运维人员把 Sensor 屏幕上显示的值输入到端点侧。
• 配对请求的指纹绑定：端点会用自己的私钥对所固定证书的指纹签名，并包含在配对请求中。经由持有其他证书的中间人转发的请求会因 fingerprint_mismatch 而失败，且配对码不会被消耗。
• 具备防重放能力的签名（v2）：审计请求和结果获取的签名采用包含时间（±300 秒）和 nonce 的 v2 格式，会拒绝重放。不含时间和 nonce 的旧 v1 签名可被重放，因此可通过 control.allow_legacy_signatures（默认 true＝供迁移期使用。每次接受都会发出弃用警告）设置是否接受。当所有端点都升级到 v2 后，请将其设为 false。
• 锁定：对配对码的暴力破解，同一来源 IP 在 10 分钟内失败 5 次将锁定 60 秒（重复触发时按指数方式延长，最长 1 小时），所有来源合计失败 20 次将触发全局锁定。签名失败的处理略为宽松（每个来源 IP 10 次，全局 100 次）。锁定时会通过通知 control_api_lockout 告知。
• 监听 IP：将 control.bind_addr（默认 0.0.0.0，重启后生效）限定为 Sensor 的局域网侧地址，可以减少暴露面。在使用通配符期间，守护进程会发出警告。
• 证书重新生成（轮换）：roamswitch-sensor tls rotate（TUI 中在 T 界面按 R）会重新生成证书。旧指纹的所有固定都会失效，需要在端点侧重新输入新值（sudo roamswitch sensor repin <公钥> --fingerprint <值>）。配对本身会保持。

sudo roamswitch-sensor pairing show                       # mode, fingerprint, warnings
sudo roamswitch-sensor tls rotate                         # regenerate the certificate
sudo roamswitch sensor repin <PUBLIC_KEY> --fingerprint <NEW_FINGERPRINT>   # on each endpoint

5. 主动漏洞审计

Sensor 会对已配对的端点执行非破坏性的实证型漏洞诊断，绝不执行任何破坏性操作（写入/删除数据、停止服务）。

sudo roamswitch-sensor scan <公钥或其开头部分>

审计由四个阶段构成。

1. 全端口扫描：全面检测目标主机上开放的所有 TCP 端口。
2. 已知特征诊断：针对已知漏洞模式执行非破坏性的实证确认，例如 Redis / dockerd / Memcached / MongoDB / Elasticsearch / CouchDB / Jenkins / VNC 的无认证暴露检查、SMTP 开放中继诊断（仅发送 MAIL FROM/RCPT TO、不发送 DATA 的安全方式），以及开发服务器的 CORS 配置错误、路径穿越、开放重定向诊断等。
3. 通用 Banner 抓取：对于未被上述特征覆盖的开放端口，仅通过连接获取 Banner 字符串（不发送任何数据）。
4. nmap NSE 补充诊断：通过 nmap --script safe 提供覆盖广泛协议的补充诊断。只要主机上安装了 nmap 就会自动执行（未安装时不执行任何操作）。

每次审计结果都会记录到 /var/lib/roamswitch-sensor/scan_history.json（无论是否检测到问题，因为在该时间点结果干净同样具有记录价值），可通过 CLI 或 TUI 查看。

roamswitch-sensor history
sudo roamswitch-sensor report <公钥或其开头部分> --out /tmp/report.md

5.1 从客户端一侧发起审计请求（拉取模式）

已配对的端点也可以主动向 Sensor 发起审计请求。Mac 版可使用菜单栏中的「向 Sensor 请求审计」，Linux 版则使用以下命令。

sudo roamswitch sensor request-audit

Sensor 执行审计后，端点会从请求发出 5 分钟后开始、每隔 5 分钟去获取一次结果，最多尝试 5 次（即最长 25 分钟后）。获取到的结果也会在端点本地保存。

roamswitch sensor results

在 Mac 版中，结果也会出现在设置窗口的「审计结果」列表中，或可通过 MCP 工具 get_sensor_audit_results 读取，作为 AI 代理制定处置方案时的输入。若 Sensor 一侧已解除该端点的配对，结果获取也可能被明确拒绝（参见 §10 Q6）。

6. 被动 ARP 监控与局域网可视化

Sensor 通过两种方式掌握局域网中的设备。(1) ARP 表监控：约每 10 秒读取一次 Sensor 自身的 ARP 表（/proc/net/arp），检测「从未见过的新 IP/MAC 出现」和「已知 IP 的 MAC 地址变化（网关欺骗等迹象）」。(2) 主动 ARP 扫描：通过 nmap -sn -PR 找出直连子网（最大 /22），并将 IP、MAC、主机名、厂商、在线状态、首次/最后发现时间、IP 历史保存到设备台账。扫描会每小时执行一次，也会在手动触发（refresh / TUI 的 r）和 TUI 启动时执行；未安装 nmap 时则退回为仅 (1) 的被动模式。还会根据 MAC 的 OUI 推断厂商和设备类别（是否为 IoT 设备等）。

roamswitch-sensor arp-events

检测到的事件可通过 roamswitch-sensor arp-events 或 TUI 的「ARP 事件」标签页（按 Enter 查看详情）查看。每个事件都附有发生时间、严重程度（致命～信息；网关 IP 的 MAC 变化为「致命」）、判断依据、相关设备的来历，以及具体的后续步骤。

6.1 被动局域网可视化扩展（选择性启用）

上述 ARP 监控仅覆盖「Sensor 自身曾通信过的设备」，但通过 ROAMSWITCH_SENSOR_PASSIVE_CAPTURE_IFACE 环境变量指定目标接口后，会观测该接口上的 Ethernet/IPv4 标头（不检查负载），检测以下内容。

• 被动观测新设备：ARP 监控无法覆盖的、Sensor 自身未直接通信过的设备的出现。通过广播/多播流量学习。
• 检测与已知恶意 IP 的通信：标记目标 IP 与本地威胁情报（与 RoamSwitch 本体的 Egress Guard 格式相同）匹配的通信（仅检测，不进行拦截）。

sudo systemctl edit roamswitch-sensor.service
# [Service]
# Environment=ROAMSWITCH_SENSOR_PASSIVE_CAPTURE_IFACE=eth0

sudo systemctl restart roamswitch-sensor.service
roamswitch-sensor passive-events

6.2 设备台账与设备备注

台账可通过 roamswitch-sensor device-inventory（TUI 的「网络构成」标签页）查看。通过 device-note（TUI 中为 n）登记名称、用途、位置等备注后，该设备即为「已掌握」，未登记备注的设备则显示为「需确认」（用于与设备台账对照）。

sudo roamswitch-sensor refresh
roamswitch-sensor device-inventory
sudo roamswitch-sensor device-note aa:bb:cc:dd:ee:ff "3F copier"

6.3 可疑行为参考信息（全部仅为检测）

启用被动抓包（§6.1，需主动开启）后，会提供以下参考信息。全部仅做检测和显示，Sensor 不会阻断通信。

• IoT 设备行为（iot-events）：已分类设备对已知恶意 IP 或管理端口（SSH/RDP/SMB 等）的连接。同时结合 mDNS/SSDP/DHCP 的自我声明来识别机型。
• 可疑通信（network-threats）：30 秒窗口内对大量目的地的连接（疑似扫描或跳板）、对同一目的地的大量连接（参与 DDoS 的迹象）、DNS 隧道/C2 迹象（仅使用查询名的结构特征进行判断，不保存域名）。
• 漏洞信息（iot-advisories）：与已知 IoT 厂商产品相关的公开 CVE 参考信息（静态内置，不会通过网络更新）。

7. CLI 命令速查表

CLI 仅支持日语和英语（遵循 LANG 环境变量）。

8. TUI 操作指南

交互式 TUI（roamswitch-sensor-tui）支持 10 种语言，可操作 CLI 的所有子命令、守护进程 IPC、所有配置键以及收集器运维（按 m 查看功能列表）。使用 Tab 键（反向为 Shift+Tab）切换 6 个主要标签页：已配对（各端点最新的审计状态）／网络构成（局域网内所有设备与备注登记）／ARP 事件／审计历史／差异（与上次审计相比的变化。新发现为红色，已解决为绿色，疑似不可达为黄色）／操作日志（谁在何时批准、执行了什么。顶部显示哈希链的验证结果）。80 列放不下的界面（被动监控、IoT 行为、可疑通信、IoT 漏洞信息）请从 m 菜单打开。

9. 信任模型与安全设计

• 带外确认（不是 TOFU）：运维人员通过口头、聊天等方式，把 Sensor 屏幕上显示的证书指纹和配对码告知端点侧。端点不会通过网络获取固定值（不是无条件信任首次连接的 TOFU），只会与持有和所输入值一致的证书的 Sensor 通信和配对。配对成立时交换的公钥，会用于验证此后探测和请求的合法性。
• 即便不执行任何破坏性操作，也能发现允许破坏性操作的漏洞：所有主动漏洞审计均为非破坏性（绝不写入或删除数据，也不会停止服务）。但会检测出诸如「无需认证即可写入」「充当开放中继」等一旦被利用便会导致破坏性操作的配置缺陷本身。
• 误报对策（自我审计排除）：内置了基于来源 IP 比对的排除机制，以防止已配对 Sensor 自身执行的全端口审计被入站端口扫描检测防护（RoamSwitch 本体侧功能）误判为侦察行为（IP 仅用于此比对以避免自动封锁，不用于信任判定本身）。此外，仅在本终端向 Sensor 请求审计后、收到报告之前（若一直没有报告，最长约 25 分钟），Mac 版会把来自 Sensor 地址的检测以及没有来源地址的“SYN 大量接收”警告，Linux 版会把“SYN 大量接收”警告，改用“多半是审计引起”的平和措辞通知。未请求审计的时段仍保持原来的强警告，Sensor 自行发起的审计不在此范围内。
• 对外发送有限，默认不发送设备信息：发现的设备信息、审计结果和 ARP 事件默认仅保存在 Sensor 自身的本地存储中，不会发送到 Lafine 或第三方的服务器。对外通信只有获取检测用数据（CVE 映射和 nmap NSE 数据库，可通过 updates.fetch_cve_map 停止。不含设备和审计数据），以及 §11 的通知（Webhook、syslog）和向中央收集器的发送（仅在运维人员配置了发送目的地时，才会发送到自己组织的目的地）。

10. 疑难排解与常见问题

Q1. 输入配对码却被拒绝。

可能的原因有以下 4 种：(1) 配对码发放后已超过 10 分钟而失效（请让 Sensor 侧操作员通过 issue-code 重新发放）；(2) 配对码输入有误（容易误读的 0/O/1/I/L 在发放时已被排除，因此配对码中不会包含这些字符）；(3) --addr 指定的 IP 地址与 Sensor 当前的固定 IP 地址不一致；(4) --fingerprint 与 Sensor 的证书不一致（pin_mismatch / fingerprint_mismatch。请确认 roamswitch-sensor pairing show 的值。错误持续出现会被锁定并返回 rate_limited）。

Q2. NSE 补充诊断结果为空。

原因可能是以下两者之一：(1) 容器中未安装 nmap；(2) 已执行，但目标端口对应的安全脚本确实没有产生输出。只要主机上安装了 nmap，nmap NSE 补充诊断就会自动执行。

Q3. 审计完成大约需要多长时间？

仅全端口扫描本身大约需要数十秒，但只要主机上安装了 nmap，就会自动加入 NSE 补充诊断，根据目标开放端口的数量，最长可能需要约 2 分钟。TUI 会持续显示已耗用的秒数，您可以一边查看进度一边等待。

Q4. 明明已经配对了，却无法执行审计。

可能的原因如下：(1) 端点侧未设置 sensor_pairing_enabled: true（默认关闭）；(2) 配对后 Sensor 的固定 IP 地址发生了变化，端点无法再连接到其保存的旧地址（需要重新配对）；(3) Sensor 侧通过 unpair 解除了配对；(4) Sensor 重新生成了证书（tls rotate），端点侧的固定值已过期（通过 roamswitch sensor repin 输入新的指纹）。请在 roamswitch sensor list（端点侧）和 roamswitch-sensor list（Sensor 侧）两边都确认对方已登记。

Q5. Sensor 本身可以与 RoamSwitch 本体（Client/Server Edition）并用吗？

可以。由于 Sensor 在设计上不具备自我防护功能，建议在同一台机器上同时部署 RoamSwitch for Linux Server Edition。两者以完全独立的进程和数据存储运行，互不冲突。

Q6. roamswitch sensor results 提示「配对已被解除」。

该端点的配对已在 Sensor 一侧通过 unpair 解除。请让 Sensor 运营者重新发放一个配对码，然后使用 roamswitch sensor pair --addr <IP> --code <配对码> --fingerprint <SHA-256> 重新完成配对。

11. 面向组织的审计运维功能（可选启用）

供大型组织的安全人员留存审计证据、掌握变化的功能集合。全部默认关闭，不会向 Lafine 或任何第三方发送任何内容；通知与汇总的目的地均由运维人员设置，属于贵组织自身。使用 sudo roamswitch-sensor config set <键> <值> 修改设置（无需重启守护进程，每次修改都会记录到操作日志），config show 可查看当前值。

11.1 定期审计与差异对比

将 schedule.enabled 设为 true，即可自动定期审计所有已配对的端点（默认每 24 小时：schedule.interval_hours；允许开始的本地时间段：schedule.window_start_hour / window_end_hour，可跨午夜；并发数：schedule.max_parallel）。每次审计都会与上一次比较，可用 roamswitch-sensor diff 查看新增发现（回归）、已解决项以及新开放的端口。如果之前开放的端口全部看不到了，将按疑似不可达处理，而不是“已解决”（关机的设备与关闭了所有端口的设备，从外部无法区分）。

无人值守的审计同样不会破坏“只审计已同意的端点”这一保证。端点的 IP 可能被 DHCP 分配给其他设备，因此系统会保存端点最近一次完成认证（配对或带签名的审计请求）时的 MAC 地址，并在每次定期审计前后用 nmap 的实时 ARP 请求确认该 IP 上应答的仍是同一 MAC。若不一致，则不进行审计（或丢弃结果）并发出通知。当有证据表明该地址已属于其他设备时，手动 scan 也会被拒绝。此检查需要 nmap；在本功能引入之前完成配对的端点，需重新配对或发送带签名的审计请求后才会纳入定期审计；仅覆盖同一二层网段内的端点。

11.2 通知（Webhook 与 syslog）

回归、新设备、ARP 欺骗、可疑通信等会发送到 notify.webhook_urls（Slack、Discord、Teams 等的 Incoming Webhook，或任意通用 JSON 接收端点）以及 notify.syslog.host / port / protocol（RFC 5424，UDP 或 TCP）。可通过 notify.min_severity（info / medium / high / critical）和 notify.cooldown_minutes（同一事件的最小重发间隔）进行筛选。roamswitch-sensor notify-test 可逐个检查目的地的连通性。

11.3 导出审计证据

roamswitch-sensor export <scans|inventory|audit-log|all> --format csv|json|html [--out 文件] [--endpoint 公钥开头部分] [--since 日期]。html 是单个文件，在浏览器中打开并「另存为 PDF」即可得到用于提交的 PDF。CSV 已针对电子表格公式注入做了防护。设备台账（inventory）带有一列，标明各设备是否处于 RoamSwitch 管理之下（已配对）。输出文件仅所有者可读（0600），导出这一行为本身也会记录到操作日志。在 TUI 中按 e 键可通过表单进行同样的指定，报告和导出以显示语言（10 种语言）生成（CLI 为日语和英语）。

11.4 操作与审批日志（防篡改）

配对、解除配对、审计的开始与完成、配置变更以及被拒绝的访问，都会连同执行者（UID／端点公钥／来源 IP）一起记录。每一行都包含上一行的 SHA-256（哈希链），因此任何编辑或删除都能用 roamswitch-sensor audit-log verify 检出（异常时退出码为 2）。查看列表用 roamswitch-sensor audit-log [--limit N]。Webhook URL 往往带有令牌，因此配置变更日志不会记录其值。仅靠哈希链无法发现末尾条目被截断，所以链头（序号与哈希）也会发送给收集器（§11.6）。

11.5 保留期限

为 retention.scan_history_days、retention.audit_log_days、retention.inventory_stale_days 设置天数后，将自动删除过期的审计历史、操作日志以及长期未出现的设备（0 = 不按期限删除，默认值）。已填写备注的设备不会从清单中删除。

11.6 汇总多个 Sensor（中央收集器，可选）

在多个站点运行多个 Sensor 时，可在另一台主机上运行 roamswitch-sensor-collector（随软件包提供，默认不启用），收集各 Sensor 带签名的摘要。

# On the collector host (a separate host from the Sensor is recommended)
sudo systemctl enable --now roamswitch-sensor-collector   # listens on 127.0.0.1:8443 by default
sudo roamswitch-sensor-collector token                     # read token for the dashboard
sudo roamswitch-sensor-collector enroll <Sensor public key> --name Tokyo --site Tokyo

# On each Sensor
sudo roamswitch-sensor config set collector.url https://collector.example.org:8443
sudo roamswitch-sensor config set collector.enabled true

• 仅接受已登记（enroll）的 Sensor 发来的、带 Ed25519 签名的请求，并通过时间戳拒绝重放。
• 凡是可从 LAN 之外访问，都必须启用 TLS。请在 /etc/default/roamswitch-sensor-collector 的 COLLECTOR_ARGS 中指定 --bind 0.0.0.0:8443 --tls-cert … --tls-key …，或在终结 TLS 的反向代理之后使用 --allow-plain-http。若未启用 TLS 却要监听 127.0.0.1 以外的地址，启动将被拒绝。
• 仪表板受令牌保护，提供按站点筛选、按严重程度查看事件以及 CSV 导出。会突出显示失去响应的 Sensor，以及审计日志疑似被截断、回滚或分叉的 Sensor（调查后用 clear-anomaly <公钥> 解除）。
• 启用 collector.send_unmanaged_devices（默认 true）后，Sensor 会把未配对的设备（非受管设备）纳入摘要。各设备会被分类为「未配对的 RoamSwitch 主机」（mDNS/SSDP 的自我声明中出现 RoamSwitch 时。启用 collector.probe_control_port 后，还会检查到控制端口 50543 的 TCP 连接。默认禁用）或「未知设备」，仅发送 MAC、厂商、设备类别和首次发现时间（不含通信内容）。在 TUI 中按 O 可打开收集器管理界面。

11.7 检测数据的获取（updates.fetch_cve_map）

Sensor 每天从更新服务获取带签名的 CVE 映射（主动诊断所使用的已知漏洞数据）和 nmap NSE 数据库。此通信不包含设备和审计数据。若要完全离线运行，请执行 sudo roamswitch-sensor config set updates.fetch_cve_map false（变更无需重启，自下一个周期起生效，此后仅使用内置数据）。

11.8 配置键一览

使用 roamswitch-sensor config show 查看当前值，使用 config set <键> <值> [<键> <值> …] 修改（多个键会以原子方式保存，在 TUI 中也可通过 C 的配置编辑器修改）。只有「重启」列为「需要」的键，才需要重启守护进程（sudo systemctl restart roamswitch-sensor）后生效。

12. 非法 DHCP 与 IPv6 检测

发现被带入网络的其他路由器或攻击者的设备假冒合法设备、劫持终端通信去向的攻击。仅做检测和通知，Sensor 不会阻断流量。默认启用，无需设置被动抓包。结果会出现在 roamswitch-sensor network-threats、TUI 的“可疑通信”标签页（从 m 进入）、通知（dhcp_rogue_server ipv6_rogue_router ndp_spoof ipv6_unknown_device）、操作与审批日志以及导出中。

12.1 非法 DHCP 服务器（IPv4 与 DHCPv6）

每小时（以及每次执行 roamswitch-sensor refresh 时），Sensor 会用随机 MAC 地址发送一个 DHCP 探测包（DHCPv6 为 SOLICIT），并统计所有应答的服务器。它不发送请求（REQUEST），因此不会租用 IP 地址。被动抓包看到的 DHCP 应答也会走同样的判定。首先发现的服务器被学习为合法服务器，之后出现的其他服务器会被通知。分发与合法服务器不同的网关或 DNS 的服务器，会劫持接受其租约的终端的通信去向，因此属于最严重的 critical。如果第一次探测时有多台服务器同时应答，Sensor 无法判断哪台合法，因此一台也不学习，而是全部报告。

12.2 IPv6（非法路由器通告、NDP 欺骗、仅 IPv6 可见的设备）

非法路由器通告：局域网内任何设备都能自称 IPv6 路由器。Sensor 会综合内核的邻居表和默认路由、被动抓包看到的路由器通告以及对路由器请求的应答，当 IPv4 默认网关以外的设备表现为路由器时发出通知（登记到 ipv6.allowed_routers 即视为合法；IPv6 路由器与 IPv4 网关是不同设备的网络属于正常情况，此时请登记）。跳数限制不是 255 的通告是伪造或经路由转入的，会被忽略。NDP 欺骗：某个 IPv6 地址的持有者 MAC 变成另一个 MAC 时发出通知（若是路由器地址则为 high）。仅 IPv6 可见的设备：在 ARP 中看不到、只出现在邻居表中的设备，会在经过一次 ARP 扫描后才报告。设备台账（CSV 的 ipv6 列、JSON 的 ipv6_addrs）也会记录 IPv6 地址。

12.3 谁算合法，以及相关设置

设置 dhcp.allowed_servers 和 ipv6.allowed_routers（MAC 或 IP）后，其余所有应答者都会被报告；留空则学习第一个发现的。可用 dhcp.active_probe 和 ipv6.active_probe（默认 true）关闭主动检测，用 ipv6.enabled 关闭全部 IPv6 监控。控制 API（50543）的 IPv6 监听通过 control.listen_ipv6 添加（默认 false，重启后生效）；路由器没有 IPv6 防火墙时，全局 IPv6 地址可能从互联网直达，所以默认不启用。连接数与锁定按 /64 统计 IPv6。从链路本地地址连接的终端因无法在没有作用域 ID 的情况下回连，不会被记作审计目标。

13. 未部署 RoamSwitch 设备的轻量审计（可选启用）

§5 的主动漏洞审计只针对已配对并同意的终端。对于未配对的打印机、摄像头、NAS 等设备，如果仍想知道“有哪些服务对外开放”，还有一种范围小得多的独立检查。OpenVAS 之类的深度诊断、登录尝试、漏洞利用、nmap NSE 和全端口扫描，只对已同意的终端进行。

13.1 检查内容

仅对固定的 54 个端口（Telnet、FTP、RDP、VNC、SMB、Redis、MongoDB、Docker API、MQTT、RTSP 等）做 TCP 连接检查，读取开放端口上服务主动发出的信息（banner）（对 Web 端口发送一次 HEAD /），并在厂商已公开漏洞时（IoT 漏洞通告表）加注。结果表述为“局域网可访问该服务”，而不是“存在漏洞”（每条检出都会注明未检查认证是否启用）。

13.2 启用方法

要启用 unmanaged_audit.enabled，需先设置 unmanaged_audit.authorization（谁批准的：姓名、工单号或制度名称等）和 unmanaged_audit.allowed_cidrs（允许审计的范围；比 IPv4 的 /16、IPv6 的 /48 更宽的范围会被拒绝）。定期执行每隔 interval_hours（默认 168 小时）一次，并遵循 schedule 的时间段。手动执行需要 --confirm 作为第二次确认。

sudo roamswitch-sensor config set unmanaged_audit.authorization "IT policy 2026-07, approved by A. Suzuki"
sudo roamswitch-sensor config set unmanaged_audit.allowed_cidrs 192.168.10.0/24
sudo roamswitch-sensor config set unmanaged_audit.exclude 192.168.10.1
sudo roamswitch-sensor config set unmanaged_audit.enabled true
sudo roamswitch-sensor audit-unmanaged 192.168.10.40 --confirm
roamswitch-sensor unmanaged-audits --detail

13.3 保障措施

allowed_cidrs 之外、unmanaged_audit.exclude（IP、范围、MAC）中的设备、已配对的终端以及 Sensor 自身，无论如何都不会被检查。执行前后，会通过实时查询（IPv4 用 ARP，需要 nmap；IPv6 用邻居请求）确认该地址上设备的 MAC，若已变为其他设备，则中止或丢弃结果并发出通知。authorization 的文本每次执行都会写入操作与审批日志，也会出现在导出（export unmanaged、JSON、HTML 报告）中，因此可以证明“是谁批准并进行的审计”。

13.4 产品确认（是否为 CISA KEV 收录漏洞的产品。需主动开启）

开启 unmanaged_audit.product_check（默认关闭）后，轻量审计会从设备正常返回的网页中读取产品名称，并告知该产品是否有 CISA KEV 收录的漏洞。发送的内容仅限：对可连接的 Web 端口（80、8080、8181、443、8443、10443）发出的 GET /、设备自己指向同一地址的重定向（最多两次），以及读取 HTTPS 证书的颁发者和主体名称。不会发送登录、密码尝试、猜测的路径，或任何利用漏洞的输入。每台设备最多 12 个请求，间隔 150 毫秒。同意条件（enabled、authorization、allowed_cidrs、exclude、排除已配对设备、MAC 复核）与 §13.2～13.3 完全相同；轻量审计关闭时，即使 product_check 为开启也不会发送任何内容。

只有当某产品界面上的标志在同一个响应中全部出现时，才会指名该产品。只有读到设备自己显示的版本、且有 CVE 的 NVD 影响范围包含该版本时，才判为“受影响”（high）。读不到版本时，仅给出提示（medium）：该产品有 KEV 收录的漏洞，但没读到版本，是否受影响未确认；绝不断言设备存在漏洞。目前只有 MikroTik RouterOS 会在界面上显示版本，其他产品通常只会得到“未确认”提示。支持 Fortinet FortiGate、Ivanti Connect Secure、Citrix NetScaler、Cisco（ASA 的 SSL VPN 和 IOS XE 的 Web UI）、UniFi OS、GeoVision、TerraMaster、Check Point 的 Security Gateway、MikroTik RouterOS（Aruba 设备在 KEV 中没有条目，不在范围内）。产品标志基于公开的检测特征，尚未在真机上验证；不匹配的标志会倾向于不检测。KEV 副本随产品附带，仅当 product_check 与 updates.fetch_cve_map 都开启时，才每 24 小时获取一个 CISA 公开订阅文件来更新（不会发送任何局域网信息）。

14. 丢失、被盗或报废时

Sensor 中保存着各终端的漏洞清单、已配对终端的地址和签名密钥。此外，已配对的终端会把这台 Sensor 视为“获准扫描端口的对象”，因此被盗的 Sensor 接入同一局域网后就能冒充该对象。可通过以下机制阻止。

14.1 在收集器中吊销与锁定

执行 roamswitch-sensor-collector revoke <公钥> --reason 原因 后，该 Sensor 之后的上传会被以 403 sensor_revoked 拒绝（只对签名正确的请求返回，因此只有持有密钥的一方才会知道）。被吊销的 Sensor 会在下次上传时得知此事，并自行停止（锁定）。锁定期间，控制 API 只回答 sensor_locked_down，并停止配对、审计（定期与手动）、向收集器上传、通知以及对网络的探测。停止状态保存在文件中，重启后依然有效，状态文件无法读取时也会保持锁定。数据会保留，因此只有在确认设备已回到可信人员手中时，才用 roamswitch-sensor lockdown off（TUI 中为 K）解除；若在收集器中仍处于吊销状态，下次上传时会再次锁定。revoke 还会显示曾与该 Sensor 配对的终端列表以及各终端上的解除方法。

14.2 清除、报废与离线检测

将 security.on_revoked 设为 wipe 后，被吊销时会用 0 覆盖并删除密钥、TLS 密钥、设置（包括 Webhook URL）、已配对终端列表、审计结果和设备台账。只保留操作与审批日志作为证据。lockdown（默认）停止并保留数据，none 仅发出通知。要手动报废手边的 Sensor，请使用 roamswitch-sensor decommission --confirm（锁定并清除，无法恢复）。把 security.lockdown_after_offline_days 设为天数，则长期无法向收集器上传的 Sensor 会自行停止（用于防范被盗后在其他网络中使用；仅在启用了收集器上传且曾成功过一次时生效，默认 0＝不启用）。

14.3 此机制做不到的事

已与其配对的终端在各自解除配对之前，会一直信任这台 Sensor。由于 Sensor 无法通知终端，请在 revoke 和 decommission 显示的列表中的每台终端上操作：Linux 执行 roamswitch sensor unpair <该 Sensor 的公钥>，Mac 进入 设置 > Sensor > 解除配对。在关机状态下或未接入网络时被带走的 Sensor，收不到停止指令，磁盘加密（LUKS 等）才是真正的防护。覆盖式清除在闪存或写时复制文件系统上不能保证完全清除。