CLI/無頭操作指南

1. 組件

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

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      # 重新啟動
journalctl -u roamswitch-server.service -f            # 日誌追蹤

3. CLI 指令參考

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

隔離（Air-Gap）原則

如果僅靠固定計時器解除，會被只需等待的攻擊者突破，因此隔離的觸發條件依信賴度分類（用戶端版與伺服器版通用）。

• 低信賴度（手動 Air-Gap、通用異常、eBPF 的 Error / Warning 及以下等）：經過較短的計時器後全部復原（用戶端：airgap_low_confidence_secs，預設 600 秒。伺服器：guard.yaml 的 safety_timer_secs，預設 300 秒。0 表示停用計時器）。
• 高信賴度（金絲雀竄改、勒索軟體式的大量改寫、lockdown 期間的 ARP 偽冒、eBPF 的 Critical / Emergency / Alert、同一規則的重複觸發等）：不會靜默復原。計時器之後會重新確認原因（已凍結的 PID、金絲雀、ARP、規則的再次觸發），僅在確認原因消失時才會附帶通知解除。如果無法確認、也沒有 ack，並達到上限（用戶端：airgap_hard_cap_secs，伺服器：server.conf 的 isolation_hard_cap_secs。兩者預設均為 3600 秒，0 = 無上限），則進入降級（DEGRADED）模式。
• 降級模式絕不會因時間流逝而自動放開（用戶端僅允許迴路，伺服器僅允許維護 SSH 與白名單 IP 的管理路徑）。解除的方式只有：重新確認原因消失、明確的確認回應（伺服器：roamswitch server ack），或手動解除（GUI 的解除按鈕 / roamswitch emergency-restore）。在用戶端的降級模式下，除非將 airgap_degraded_lift_rfkill 設為 true，否則 Wi-Fi 的 rfkill 也不會被解除。
• 管理路徑以外的已建立連線會被切斷（伺服器：維護 SSH 連接埠與白名單 IP 以外。攻擊者已經建立的 C2 或反向 Shell 也會被阻斷）。手動 Air-Gap：透過無警告的選單 / GUI / roamswitch airgap enable 觸發時為低信賴度；但如果是從 ARP 偽冒警告的「立即阻斷」觸發，則繼承該警告的信賴度（高），並在不傳送任何網路資料的情況下重新確認閘道的 MAC 是否連續與受信任的 MAC 一致（arp_recheck_consecutive 次、arp_recheck_min_secs 秒以上）。每次狀態轉換都會記錄到事件時間軸。

勒索軟體復原(快照與依檔案復原)

以下指令屬於 roamswitch-ransomware-rollback（不是 roamswitch 的子指令）。其狀態儲存在 /var/lib/roamswitch。

範例

sudo roamswitch status                 # 用戶端綜合診斷（27項）
sudo roamswitch status --server        # 伺服器版綜合診斷（34項）
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             # 對緊急隔離做出確認回應（FULL 隔離期間維持嚴格隔離，降級期間解除）
roamswitch canary                      # 金絲雀誘餌事件記錄
roamswitch vuln-status                 # 顯示最近一次掃描結果與經過天數(pass_age)
roamswitch port-anomaly                # 未知連接埠暴露防護事件記錄
roamswitch server ebpf                 # eBPF 防護的隔離狀態和事件記錄
roamswitch server bans                 # SSH 暴力破解防護的狀態與目前被封鎖的來源位址清單
sudo roamswitch server unban 203.0.113.9   # 解除 SSH 暴力破解防護的封鎖（需要 root）
roamswitch notifications               # 過去1週的通知歷史
roamswitch frozen                      # 列出被凍結的行程
sudo roamswitch frozen resume 12345    # 解除誤判凍結的行程
sudo roamswitch sensor pair --addr 192.168.1.50 --code AB3DFGH2 --fingerprint 3F:45:89:E1:...:36:10  # 使用配對碼與 Sensor 配對
sudo roamswitch sensor key             # 顯示本端點自身的公鑰／位址
roamswitch port-scan                   # 連接埠掃描偵測歷史
roamswitch timeline --json             # all incident-timeline records as JSON
roamswitch notifications --export n.jsonl   # JSON Lines
sudo roamswitch events search --since 2h --exe curl
sudo roamswitch forward status
sudo roamswitch server allowlist add "<rule>" mytool --exe /usr/local/bin/mytool
sudo roamswitch sensor repin <PUBLIC_KEY> --fingerprint <NEW_FINGERPRINT>
sudo roamswitch server tui

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

4. 設定檔

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

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

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

伺服器版使用 INI 格式的設定檔，並以權限 0600（僅 root）保護。所有鍵的型別、可用值、預設值與是否需要重新啟動，請參閱 伺服器版 維運手冊 §18。可透過 roamswitch server config show|get|set 修改，也可以在 roamswitch server tui 的設定編輯器（server.conf 與 guard.yaml 的全部 146 個鍵）中編輯。伺服器版不支援設定的重新載入，因此修改後請透過 sudo roamswitch server restart 使其生效。

共享機器：僅管理員模式

在多人共用的機器上，可以用 sudo touch /etc/roamswitch/admin-only 開啟「僅管理員」模式。防火牆、DNS、VPN、USB、核心與掛載強化、無線電、Sensor 信任等影響整台機器的變更，只允許 root 或 sudo / wheel / roamswitch 群組的使用者執行。與自己的檔案和行程相關的操作（隔離、kill、freeze、掃描）與以前相同。/etc/roamswitch/admin-only 僅在由 root 擁有且其他使用者無法寫入時才有效（使用者不能自己建立它來切換模式）。預設關閉（沒有該檔案）。

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

直接呼叫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 / verify_security_findings / get_exposed_ports / get_guard_status / audit_url_safety / audit_secrets / audit_security_logs / audit_mcp_configs / audit_agent_setup / 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_port_scan_incidents / get_ssh_guard_incidents / get_canary_status / get_vulnerability_scan_history / get_notification_history / search_exec_events / get_process_tree / get_incident_timeline / get_fleet_status / get_vpn_status / get_link_guard_status / get_air_gap_status / get_sharing_services_status / get_bluetooth_guard_status / get_usb_guard_status / run_active_vuln_scan / run_package_cve_scan / run_package_cve_scan_languages / run_package_lifecycle_script_scan / run_typosquat_scan / run_npm_audit_signatures / get_sensor_audit_results)。

它不會連線外部主機，而是在本機連接常駐程式的套接字或直接呼叫 roamswitch-core。get_security_report 與 verify_security_findings 也不會向區域網路傳送任何內容（閘道只從 ARP 快取等資訊中讀取）。請參閱 MCP 設定指南

• RoamSwitch for Linux 產品頁
• 客戶端安全性白皮書
• 伺服器安全性白皮書
• 伺服器操作手冊
• AI助理與MCP整合指南
• 常見問題