ROAMSwitch for LINUX · 操作參考

CLI/無頭操作指南

如何在沒有 GUI 的情況下在雲端 VPS 實例上透過 SSH、從 cron、監控腳本和編程式 AI 代理程式 (MCP) 操作適用於 Linux 的 RoamSwitch。

選擇版本

客戶端版本 (roamswitch)：專為筆記型電腦、行動工作站和開發人員設備而設計。根據連接網路的信任等級自動切換 nftables 防火牆設定檔。本指南主要關注客戶端版本的無頭/CLI 管理。
伺服器版 (roamswitch-server)：專為雲端 VPS 實例（AWS、GCP、DigitalOcean、Linode 等）和直接暴露於 Internet 的本機伺服器而設計。具有入站預設丟棄過濾、SSH 鎖定預防、關鍵路徑檔案完整性監控 (FIM)、eBPF / Falco 運行時整合和即時通知（Telegram / LINE / Webhooks）的功能。有關完整的安裝和管理說明，請參閱RoamSwitch 伺服器版操作手冊 和伺服器安全性白皮書.

1. 組件

組件	運行為	角色
`roamswitch-daemon`（客戶端）	根（systemd `Type=notify`）	所有客户端特权操作：nftables 控制、网络检测、勒索软件/恶意软件监控、fanotify、ARP/NDP 固定、DNS 强制。不開啟 TCP/UDP 偵聽套接字。
`roamswitch-server-daemon`（伺服器）	根（systemd `Type=notify`）	所有伺服器特權操作：入站預設丟棄、SSH 和管理堡壘保留、FIM（150 多個關鍵二進位雜湊）、具有自主 `SIGSTOP` 凍結功能的 Falco eBPF UNIX 套接字偵聽器、警報調度。
`roamswitch` (命令列)	登入使用者（某些操作需要 sudo）	瘦客戶端讀取守護程式狀態。在客户端版本上使用 `/run/roamswitch/roamswitch.sock` IPC，或在服务器版本上提供 `--server`、`server`、`fim` 和 `emergency-restore` 子命令。
`roamswitch-mcp`	人工智慧客戶端催生	只讀 MCP 伺服器（stdio / JSON-RPC），用於 AI 代理程式以程式方式檢索狀態。請參閱 MCP 設定
`roamswitch-app`	登入用戶	GTK GUI（僅限客戶端版）。在無頭環境中不需要。

無頭部署在守護程序 + roamswitch CLI 上執行（如果需要，也可新增 roamswitch-mcp）。 所有自主防禦機制都無需任何 GUI 即可運作。

互斥套餐

客戶端版 (roamswitch) 和伺服器版 (roamswitch-server) 是互斥的套件 (Conflicts)。在伺服器環境上部署 roamswitch-server。

2.守護程式（systemd服務）

客戶端版

sudo systemctl status  roamswitch.service      # 運作狀態
sudo systemctl enable  roamswitch.service      # 開機自動啟動（安裝時已啟用）
sudo systemctl restart roamswitch.service      # 重新啟動
journalctl -u roamswitch.service -f            # 日誌追蹤
journalctl -u roamswitch.service --since "1h ago"

客戶端守護程式在啟動時和每個週期（3 秒）自主執行的操作：

識別連線的閘道 MAC 並針對 trusted_networks 套用 nftables 設定檔 (open / balanced / lockdown)
行為勒索軟體檢測（fanotify + Shannon entropy + canary）
按存取惡意軟體掃描（fanotify，可選 ClamAV）
ARP 欺騙監控和預防性閘道 ARP/NDP 固定在不受信任的網路上
每個設定檔的核心強化（sysctl / Yama / core dumps / /tmp noexec）
威胁防护 DNS 强制执行 (dns_enabled + dns_scope)
用於網路釣魚攔截的連結防護 (NFQUEUE)
运行时状态输出到 /run/roamswitch/state.json

伺服器版

sudo systemctl status  roamswitch-server.service      # 運作狀態
sudo systemctl restart roamswitch-server.service      # 重新啟動
sudo systemctl reload  roamswitch-server.service      # 重新載入設定檔
journalctl -u roamswitch-server.service -f            # 日誌追蹤

3. CLI 指令參考

基本語法：roamswitch <command> [options]。不带参数运行默认为 status。輸出語言會自動遵循作業系統區域設定 (LC_ALL / LC_MESSAGES / LANG)。

命令	權限	描述
`status [--server]`（别名 `report` / `server-status`）	使用者	安全健康評估（對客戶端進行 24 次檢查，對 `--server` 進行 30 次檢查）、0–100 分、等級和每項建議
`server [config\|setup\|test-notify\|restart\|ebpf]`	用戶/根用戶	伺服器版配置管理、互動式設定精靈和測試通知。`ebpf`（別名 `incidents`）顯示 eBPF 執行時防護的目前隔離狀態與已偵測到的事件記錄
`fim [verify\|update]`	用戶/根用戶	關鍵路徑檔案完整性監控驗證 (`verify`) 和基線雜湊資料庫更新 (`update`)
`emergency-restore`	根	解除所有緊急 eBPF/防火牆隔離並恢復網路基線
`ports [-a\|--all]`	使用者	監聽 0.0.0.0、未經身份驗證的資料庫和開發伺服器上的連接埠。 `-a` 包含僅環回端口
`guards`	使用者	自動防禦衛士的狀態（連接埠異常、ARP、USB儲存、下載、DNS威脅、金絲雀、開發伺服器隔離器、藍牙）
`wifi`	使用者	Wi-Fi 加密強度（開放/WEP/WPA/有線）和 SSID
`sharing [status\|on\|off]`	使用者	在不受信任的網路上自動停止/恢復 SSH/Samba/RDP（`on` 在不受信任時斷開活動的 SSH）
`audit-url <URL>`	使用者	透過本地來源 + 啟發式檢查 URL 網路釣魚和威脅風險（從不獲取目標）
`audit-secrets <text\|path\|directory>`	使用者	偵測文字、檔案或目錄（遞迴掃描，自動跳過 .git/node_modules 等）中的 API 金鑰、私鑰和令牌（從不傳輸資料）
`audit-logs [hours]`	使用者	聚合並分類過去 N 小時的系統日誌/身份驗證日誌（預設 24）。API 金鑰和權杖會自動遮罩。同時顯示記錄模式異常偵測結果（新模式與統計頻率激增）
`canary`	使用者	勒索軟體金絲雀誘餌文件狀態與完整性，以及已偵測到的事件記錄（最近50筆）
`port-anomaly`（別名 `port-guard`）	一般	未知連接埠暴露防護的基準線取得狀態、目前自動阻擋的連接埠，以及已偵測到的事件記錄（最近50筆）
`quarantine [list]`	使用者	惡意軟體隔離庫的內容（樣本、原始路徑、威脅名稱、日期）
`knowledge [query]`（別名 `faq`）	使用者	搜尋離線知識庫
`airgap [enable\|disable]`	用戶/根用戶	觸發或解除緊急氣隙隔離（`enable` 丟棄所有外部流量）
`help` (`--help` / `-h`)	使用者	顯示幫助（`roamswitch <command> --help` 表示子命令幫助）
`scan-packages [資料夾...]`	一般	將已安裝的OS軟體包（自動判定dpkg/pacman/dnf/zypper）與本機已知CVE對照表進行比對。傳入資料夾參數後，還會將該專案的相依關係（npm/PyPI/crates.io等7個生態系統）的鎖定檔案一併納入比對。完全不進行任何網路活動
`scan-vulns [--confirm]`	一般	僅當 `active_vuln_scan_enabled: true`（預設關閉）時執行：僅限127.0.0.1的Redis/Memcached/MongoDB/dockerd無驗證可達性確認、對偵測到的開發伺服器進行CORS設定錯誤・路徑遍歷・開放重新導向診斷、SMTP開放轉發診斷，以及Telnet/FTP/SSH的實證型暴露診斷。未帶 `--confirm` 則為演練模式
`notifications`（別名 `notification-history`）	使用者	RoamSwitch 傳送的通知（記錄稽核異常、ClickFix 偵測等）歷史記錄（過去1週，最新在前）
`frozen [list\|resume <PID>\|resume all]`	使用者/root	列出各防護模組（勒索軟體高速加密偵測、誘餌檔案遭竄改、核心漏洞攻擊偵測）目前以 `SIGSTOP` 凍結的行程，若屬誤判可解除（`SIGCONT`）。凍結並非強制結束，解除後將從暫停處原樣繼續。`resume all` 可全部解除。解除 root 擁有的行程需要 sudo
`resource-guard`（別名: `leak-guard`）	使用者	資源耗盡／行程異常偵測防護（僅 Server Edition）的偵測事件歷程。以信心等級顯示網路公開服務的持續 RSS 成長（記憶體洩漏／DoS）與當機迴圈
`timeline`（別名: `incident-timeline`）	使用者	將連結防護（ARP 欺騙）、勒索軟體 Canary、eBPF 執行期防護與資源防護的偵測整合為單一時間軸，含行程譜系與 MITRE ATT&CK 標籤（實驗性）
`xdp-gate [status\|enable\|disable]`	使用者/root	顯示或切換 XDP 啟動時閘門（實驗性）。`status` 顯示 `roamswitch-xdp-gate.service` 是否啟用及目前程式狀態。預設關閉
`sensor [key\|list\|pair\|unpair\|request-audit\|results]`	一般使用者/root	與另一儲存庫中、安裝於通用裝置上的網路感測器「RoamSwitch Sensor」之間基於配對碼的相互信任。`pair --addr <IP> --code <配對碼>` 使用 Sensor 端發放的配對碼完成配對（前提是 Sensor 以固定 IP 執行），`key` 顯示本端點自身的公鑰／位址，`unpair` 解除配對，`request-audit` 向 Sensor 請求執行主動弱點稽核（透過 `results` 取得結果）。需要 `sensor_pairing_enabled: true`（預設關閉）。詳情請參閱 Sensor 維運手冊
`port-scan` (alias `portscan`)	一般使用者	顯示入站連接埠掃描偵測防護的偵測歷史（來源 IP、是否自動封鎖及封鎖時長）。與偵測新增「暴露」未知連接埠的 `port-anomaly` 是不同的功能

範例

sudo roamswitch status                 # 用戶端綜合診斷（24項）
sudo roamswitch status --server        # 伺服器版綜合診斷（30項）
sudo roamswitch ports -a               # 全部監聽埠
roamswitch guards                      # 守護程式運作狀態
roamswitch audit-url https://examp1e-login.com
roamswitch audit-secrets ./deploy.env
roamswitch audit-secrets .                          # 遞迴掃描目前目錄
roamswitch audit-logs 72               # 分析最近72小時的日誌
sudo roamswitch sharing on             # 在非信任網路下自動停止 SSH/Samba/RDP
sudo roamswitch fim verify             # FIM 檔案完整性驗證
sudo roamswitch fim update             # 更新 FIM 基準線
sudo roamswitch emergency-restore      # 完全解除緊急遮斷並復原
sudo roamswitch airgap enable          # 緊急遮斷
sudo roamswitch airgap disable         # 解除
sudo roamswitch server ack             # 確認回應安全計時器（停止自動復原）
roamswitch canary                      # 金絲雀誘餌事件記錄
roamswitch port-anomaly                # 未知連接埠暴露防護事件記錄
roamswitch server ebpf                 # eBPF 防護的隔離狀態和事件記錄
roamswitch notifications               # 過去1週的通知歷史
roamswitch frozen                      # 列出被凍結的行程
sudo roamswitch frozen resume 12345    # 解除誤判凍結的行程
sudo roamswitch sensor pair --addr 192.168.1.50 --code AB3DFGH2  # 使用配對碼與 Sensor 配對
sudo roamswitch sensor key             # 顯示本端點自身的公鑰／位址
roamswitch port-scan                   # 連接埠掃描偵測歷史

伺服器版守護行程以root權限運行,因此需要讀取nftables規則集或識別行程擁有者的命令(status / status --server / ports -a)在沒有sudo的情況下會傳回不準確的結果(錯誤的「未執行」判定或行程資訊缺失)。變更設定的命令(sharing / fim update / airgap / emergency-restore等)同樣需要sudo。其他唯讀命令即使不使用sudo也能正確運作。

注意事項和限制

透過 roamswitch <command> --help.
機器可讀狀態應透過 MCP (§6) 或 /run/roamswitch/state.json (§5).
在客戶端版本中，沒有直接命令來強制防火牆設定檔；守護程式根據網路信任自主管理這一點。若要強制級別，請在 config.json 中設定 manual_override 或直接呼叫 set_security_level IPC (§5).
status 都會回傳退出代碼 0。對於自動監控，解析分數線（參見§7）.

4. 設定檔

客戶端版本 (`~/.config/roamswitch/config.json`)

該守護程式以 root 身分執行，並使用它找到的第一個有效檔案（或僅 root 環境中的 /root/.config/roamswitch/config.json）掃描 /home/*/.config/roamswitch/config.json。

鑰匙	類型/預設	描述
`language`	字串/作業系統區域設置	UI 和 CLI 語言（`ja` / `en` / `ko` / `zh-Hans` / `zh-Hant` / `de` / `fr` / `es` / `it` / `pt-PT`）
`trusted_networks`	`[{name, mac, level}]`	值得信賴的網路； `mac` 是閘道 MAC，`level` 是 `open` / `balanced` / `lockdown`
`away_protection_level`	字串/`lockdown`	未知網路上的預設設定檔
`manual_override`	字串/空	強制 `open` / `balanced` / `lockdown` （自動為空）
`dns_enabled`	布爾 / `true`	威脅防護 DNS 實施
`dns_provider`	字串/`quad9`	`quad9` / `cloudflare` / `adguard` / `cleanBrowsing`
`dns_scope`	字串/`untrusted_only`	`untrusted_only` / `always_on`
`arp_spoof_guard_enabled`	布爾 / `true`	ARP欺騙監控
`gateway_arp_lock_enabled`	布爾 / `true`	不受信任網路上的預防性閘道 ARP/NDP 鎖定
`port_anomaly_guard_enabled`	布爾 / `true`	自動阻止新的監聽端口
`system_wide_fanotify_enabled`	布爾 / `true`	系統範圍內的 fanotify 惡意軟體防護
`pre_exec_blocking_enabled`	布爾 / `true`	執行前阻塞 (`FAN_DENY`)
`entropy_freeze_enabled`	布爾 / `true`	勒索軟體快速結凍 (`SIGSTOP`)
`mount_hardening_enabled`	布爾 / `true`	`/tmp` 和 `/dev/shm` 上的 `noexec`（套用於非開放式設定檔）
`yama_memory_protect_enabled`	布爾 / `true`	Yama ptrace 限制
`usb_storage_guard_enabled` / `usb_keyboard_guard_enabled`	布爾 / `false`	USB 儲存 / BadUSB 鍵盤防護（預設為關閉）
`usb_zero_trust_enabled`	布爾 / `false`	USB匯流排authorized_default=0
`bluetooth_guard_enabled`	布爾 / `false`	在不受信任的網路上停用藍牙無線電
`sharing_service_control_enabled`	布爾 / `true`	自動停止/恢復 SSH / Samba / RDP
`scan_exclusions`	`[string]`	排除掃描的絕對路徑
`link_guard`	物件	`{enabled, mode: "off"\|"warn"\|"block", allowlist, blocklist_extra, use_threat_dns}`
`vpn_on_untrusted_enabled`	布爾 / `false`	在不受信任的網路上自動啟動 VPN 隧道
`vpn_backend`	字串/`wireguard`	`wireguard` / `tailscale`
`active_vuln_scan_enabled`	bool / `false`	允許執行 `scan-vulns`（預設關閉）。因會傳送僅限127.0.0.1的可達性探測，需要明確啟用
`pkgcve_watched_folders`	`[string]`	GUI版相依關係比對所鎖定的專案資料夾清單（絕對路徑）。CLI的 `scan-packages` 不參照此設定，僅以命令列參數指定的資料夾為對象
`sensor_pairing_enabled`	bool / `false`	允許與 RoamSwitch Sensor 之間基於配對碼的相互信任（預設關閉）。使用 `sensor` 指令的前提條件
`port_scan_detect_enabled`	bool / `true`	入站連接埠掃描偵測防護
`port_scan_detect_min_distinct_ports`	int / `15`	在偵測視窗內連線到不少於此數量不同連接埠的來源將被判定為掃描
`port_scan_detect_window_secs`	int / `300`	掃描判定的統計視窗（秒）
`port_scan_block_enabled`	bool / `true`	自動封鎖偵測到的掃描來源 IP
`port_scan_block_duration_secs`	int / `600`	自動封鎖的持續時間（秒）

遠端 SSH 注意

使用 sharing_service_control_enabled: true，連線到不受信任的網路 會中斷活動的 SSH 會話。在無頭伺服器上將其停用。

伺服器版 (`/etc/roamswitch/server.conf`)

伺服器版使用具有嚴格權限（0600，僅限 root）的 INI 格式設定檔。請參閱伺服器版操作手冊

5. 日誌和運行時狀態文件

路徑	目標	描述
`journalctl -u roamswitch.service`	客戶	客戶端守護程序日誌（設定檔切換、偵測、錯誤）
`journalctl -u roamswitch-server.service`	伺服器	伺服器守護程序日誌（FIM 事件、Falco 偵測、隔離）
`/run/roamswitch/roamswitch.sock`	客戶	客戶端守護程式 IPC Unix 域套接字
`/run/roamswitch/events.sock`	伺服器	Falco / Tetragon eBPF 整合式套接字（root:root，模式 0660；Falco 預設以 root 身分執行，啟用零配置直接套接字寫入）
`/run/roamswitch/state.json`	客戶	循環狀態：`{active_level, network_trusted, fanotify_ready}`
`/run/roamswitch/alerts.json`	客戶	最近的警報佇列
`/run/roamswitch/approvals.json`	客戶	待批准隊列
`/run/roamswitch/fanotify.ready`	客戶	指示 fanotify 防護正在運作的標誌文件
`/var/lib/roamswitch/fim_baseline.db`	伺服器	FIM SHA-256 基線哈希資料庫
`~/.local/share/roamswitch/quarantine/`	兩者都	隔離庫（`0700`，樣本 `0400`）+ `.metadata.json`

直接呼叫IPC（進階）

守護程式在 /run/roamswitch/roamswitch.sock 上接受換行符號分隔的 JSON：

# 強制切換設定檔（用戶端版）
printf '{"id":1,"method":"set_security_level","params":{"level":"lockdown"}}\n' \
  | sudo socat - UNIX-CONNECT:/run/roamswitch/roamswitch.sock

# 立即核對閘道器 ARP 鎖定
printf '{"id":1,"method":"reconcile_gateway_lock","params":null}\n' \
  | sudo socat - UNIX-CONNECT:/run/roamswitch/roamswitch.sock

6. 程序化狀態 (MCP)

roamswitch-mcp 在 stdio 上透過 JSON-RPC 公開唯讀工具 (get_security_report / get_exposed_ports / get_guard_status / audit_url_safety / audit_secrets / audit_security_logs / get_app_help / get_quarantine_status / get_file_scan_guard_status / verify_fim / get_port_anomaly_incidents / get_ebpf_incidents / get_resource_guard_incidents / get_canary_status / get_notification_history / get_incident_timeline / run_active_vuln_scan / run_package_cve_scan / run_package_cve_scan_languages)。

它不使用外部網路通信，本地連接到守護程式套接字或調用 roamswitch-core。請參閱 MCP 設定指南

7. 自動化食譜

每日 cron 健康檢查 → 如果分數低於閾值則發送電子郵件

#!/usr/bin/env bash
# /etc/cron.daily/roamswitch-health
out=$(runuser -u "$SUDO_USER" -- roamswitch status 2>&1)
score=$(printf '%s\n' "$out" | grep -oE '[0-9]+/100' | head -1 | cut -d/ -f1)
if [ -n "$score" ] && [ "$score" -lt 80 ]; then
  printf '%s\n' "$out" | mail -s "RoamSwitch health: ${score}/100" root
fi

監控警報隊列（輪詢alerts.json）

#!/usr/bin/env bash
last=0
while :; do
  ts=$(jq -r 'max_by(.timestamp).timestamp // 0' /run/roamswitch/alerts.json 2>/dev/null || echo 0)
  if [ "$ts" -gt "$last" ]; then
    jq -c ".[] | select(.timestamp > $last)" /run/roamswitch/alerts.json | logger -t roamswitch-alert
    last=$ts
  fi
  sleep 10
done

驗證 fanotify 防護健康狀況 (state.json)

jq -e '.fanotify_ready == true' /run/roamswitch/state.json >/dev/null \
  || echo "WARNING: fanotify guard is not running" >&2

8. 故障排除

症狀	解析度
`roamswitch` 退出並顯示“檢查漫遊交換器-mcp 是否已安裝”	守護程式未執行 → `sudo systemctl start roamswitch.service`（或 `roamswitch-server.service`）。驗證套接字是否存在
`roamswitch status` 顯示 fanotify 🔴 “守衛停了下來”	短暫的 `fs.fanotify.max_user_groups` 疲憊。使用 `sudo systemctl restart roamswitch.service` 重新啟動並在日誌中驗證
設定檔停留在 `balanced`，永遠不會達到 `open`	驗證網關 MAC 已在 `trusted_networks` 中註冊到 `level: open`
SSH 意外斷開	客戶端版本在不受信任的網路上有 `sharing_service_control_enabled: true`。透過 `roamswitch sharing off` 停用
配置更改不生效	The client daemon reads the first of `/home/*/.config/…`; apply with `systemctl restart roamswitch.service`. For the server edition, edit `/etc/roamswitch/server.conf` then run `sudo roamswitch server restart` (no reload).
伺服器通訊意外被阻止	存取雲端控制台（VNC/串列埠）並執行`sudo roamswitch emergency-restore`

1. 組件

2.守護程式（systemd服務）

客戶端版

伺服器版

3. CLI 指令參考

範例

4. 設定檔

客戶端版本 (~/.config/roamswitch/config.json)

伺服器版 (/etc/roamswitch/server.conf)

5. 日誌和運行時狀態文件

直接呼叫IPC（進階）

6. 程序化狀態 (MCP)

7. 自動化食譜

每日 cron 健康檢查 → 如果分數低於閾值則發送電子郵件

監控警報隊列（輪詢alerts.json）

驗證 fanotify 防護健康狀況 (state.json)

8. 故障排除

9. 參考文獻

客戶端版本 (`~/.config/roamswitch/config.json`)

伺服器版 (`/etc/roamswitch/server.conf`)