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 <公開金鑰> 解除）。