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集成指南
• 常见问题解答