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 的端点执行主动漏洞审计，以及以 Sensor 自身的 ARP 表为起点，被动检测新设备出现与伪装行为（如 §6 所述，这并非主动扫描并可视化局域网内所有设备的功能）。它的设计定位不是 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 端口。
• 资源占用：常驻内存约数十 MB，空闲时 CPU 负载极低。
• 可选：nmap（用于 NSE 补充诊断，未安装时其他功能仍可正常运行）。

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 分钟即失效且仅可使用一次，请通过口头、聊天等任意带外方式尽快告知端点侧的操作者。

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

# 端点侧 (roamswitch-linux)
sudo roamswitch sensor pair --addr <Sensor 固定 IP 地址> --code <配对码>

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

配对成功后，此后每一次主动漏洞审计与审计结果获取都会通过 Ed25519 签名进行认证。知道该配对码的端点，与发放该配对码的 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

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 会定期对自身持有的 ARP 表（相当于 /proc/net/arp）进行快照，并通过与上一次的差异比对，检测两类事件：「从未见过的新 IP/MAC 出现」以及「已知 IP 的 MAC 地址发生变化（网关伪装等迹象）」。不会主动发送任何数据包，且仅覆盖 Sensor 曾以某种方式通信过的设备（并非主动发现并枚举局域网内所有设备的功能）。不具备判别设备类型（是否为 IoT 设备等）的能力，仅检测 IP/MAC 的变化。

roamswitch-sensor arp-events

检测到的事件也可从 TUI 的「ARP Events」标签页中查看列表，会区分显示「新设备出现」和「已知 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

7. CLI 命令速查表

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

8. TUI 操作指南

交互式 TUI（roamswitch-sensor-tui）支持 10 种语言。用 Tab 键（Shift+Tab 反向）在 6 个标签页之间切换：已信任（各端点最新的审计状态）／网络设备（局域网内所有设备及备注）／ARP 事件／审计历史／变化（与上一次审计相比的变化——新增发现为红色，已解决为绿色，疑似不可达为黄色）／操作日志（谁在何时批准或执行了什么，顶部显示哈希链的校验结果）。

9. 信任模型与安全设计

• TOFU（Trust On First Use，首次使用即信任）：配对码本身并非密码学意义上的所有权证明，而是运营者依靠自身判断——即通过带外渠道（口头、聊天等）收到了 Sensor 运营者发放的配对码——来确认的，这与蓝牙配对的显式相互确认模型类似。配对成功后，此后每次探测/请求的合法性都会依据配对时交换的公钥进行验证。
• 即便不执行任何破坏性操作，也能发现允许破坏性操作的漏洞：所有主动漏洞审计均为非破坏性（绝不写入或删除数据，也不会停止服务）。但会检测出诸如「无需认证即可写入」「充当开放中继」等一旦被利用便会导致破坏性操作的配置缺陷本身。
• 误报对策（自我审计排除）：内置了基于来源 IP 比对的排除机制，以防止已配对 Sensor 自身执行的全端口审计被入站端口扫描检测防护（RoamSwitch 本体侧功能）误判为侦察行为（IP 仅用于此比对以避免自动封锁，不用于信任判定本身）。
• 未经配置不会发送任何内容：发现的设备信息、审计结果和 ARP 事件默认只保存在 Sensor 自身的本地存储中，绝不会发送给 Lafine 或任何第三方服务器。§11 所述的通知（Webhook / syslog）和向中央收集器的推送，只会在运维人员设置了目的地之后，发往贵组织自己的目的地。

10. 疑难排解与常见问题

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

可能有以下三种原因：(1) 距离发放已超过 10 分钟，配对码已失效（请让 Sensor 运营者用 issue-code 重新发放）；(2) 配对码输入有误（容易混淆的 0/O/1/I/L 在发放时已被排除，配对码中不会出现这些字符）；(3) --addr 指定的 IP 地址与 Sensor 当前的固定 IP 地址不一致。

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 解除该配对。请在端点侧执行 roamswitch sensor list、在 Sensor 侧执行 roamswitch-sensor list，确认双方都已登记对方。

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 <配对码> 重新完成配对。

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），导出这一行为本身也会记录到操作日志。

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 <公钥> 解除）。