ROAMSWITCH SERVER · 最后更新:2026-10-24

RoamSwitch服务器版操作手册

云 VPS(AWS、GCP、Azure、Linode、DigitalOcean)、裸机数据中心和容器主机的官方安装、部署和操作参考。

1. 概述及要求

RoamSwitch Server Edition 是面向常年暴露在互联网上的 Linux 服务器的完全无头(零 GUI 依赖)的自主安全与完整性防护套件。

与根据所连接的 Wi-Fi 切换配置文件的客户端版不同,服务器版以“入站默认拒绝(Default Drop)”“关键路径篡改监控(FIM)”“对内核 LPE(Frag Gap)的预防性封堵”“eBPF 运行时威胁监控”“SSH 防锁定故障保护”“向 Telegram / LINE / Webhook 的自主紧急通报”为核心功能。

零遥测原则(不发送任何用户信息,默认的对外通信只有接收签名数据)
RoamSwitch 不会把服务器的 IP 地址、端口信息、文件哈希、系统日志、诊断结果发送给任何厂商或云。守护进程中不含 TLS / HTTP 客户端。

除软件包更新外,默认的对外通信只有匿名获取带签名的数据(cve_kernel_map_updates_enabled,默认开启)。它通过 HTTPS GET 从 lafine.net 接收带 Ed25519 签名的 CVE 数据、Web 规则、KEV、EPSS 等(清单和 KEV 每天一次,CVE 数据每周一次)。没有查询字符串和 Cookie,除固定的 User-Agent: RoamSwitch-Updater 外,不发送任何主机信息。关闭后,审计仍按内置基线运行,但 Ubuntu 操作系统软件包的 CVE 比对会显示“未获取 CVE 数据”。

其余仅在运维人员启用时才会发生:通知(Telegram / LINE / Webhook)、npm 签名验证、对自己域名的 DNS 和 RDAP 检查(domain_check_domains)、向自己组织目标地址的事件转发(forward_enabled,默认关闭)、Sensor 配对、accessscope 的 LLM 联动(仅在指定 --llm 时)、语言依赖的带签名映射(package_cve_map_languages_enabled,每周一次,仅接收)。例外列表见 Server Edition 安全设计文档的 Zero Telemetry 一节。

系统要求

2. 安装步骤

使用官方带签名的软件包仓库,依赖关系会自动解决,并可通过系统的更新命令安全地自动更新。

2.1 APT(Ubuntu / Debian / Raspberry Pi 操作系统)

# 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 [arch=amd64,arm64 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-server

2.2 DNF / RPM(Fedora / RHEL / AlmaLinux / Rocky Linux)

# 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-server

2.3 openSUSE(zypper)

sudo rpm --import https://lafine.net/rpm/RPM-GPG-KEY-roamswitch
sudo zypper addrepo https://lafine.net/rpm/opensuse/roamswitch.repo
sudo zypper refresh && sudo zypper install roamswitch-server

在启用 SELinux 的 Fedora、RHEL、AlmaLinux、Rocky Linux 上,安装时会为守护进程(/usr/lib/roamswitch/roamswitch-server-daemon)设置 initrc_exec_t,并以 initrc_t 的权限运行。没有该标签时会以 init_t 运行,读取 authorized_keys 等操作会被拒绝。有 semanage 时规则会保留;没有时只用 chcon,因此重新打标签后请重新安装软件包。权限可用 sudo ps -eZ | grep roamswitch-serv 确认。

包互斥(冲突)
客户端版(roamswitch)和服务器版(roamswitch-server)在软件包管理器的元数据中设为互斥(Conflicts),以防在同一主机上重复安装。用于服务器时,务必指定 roamswitch-server。

3. 初始设置和服务验证

3.1 服务状态

安装后,roamswitch-server.service 立即启动并在系统引导时启用。

sudo systemctl status roamswitch-server.service

首次使用时,请接着运行 sudo roamswitch server setup。在此之前,SSH 维护来源、通知渠道、agent_users 和文件扫描的目标都未设置。

更新软件包时,如果更新定时器(roamswitch-update.timer)处于禁用状态,且 server.conf 没有关闭更新,就会启用它。已关闭更新的设备会保持停止。

3.2 交互式设置向导

用下面的命令启动设置向导,以交互方式设置端口、维护来源 IP、通知目标和隔离动作(按 Enter 采用默认值)。

sudo roamswitch server setup
  1. 端口:分别以逗号分隔输入 SSH 维护端口(默认 22)和公开服务端口(默认 80,443)。
  2. 指定维护来源 IP:指定 SSH 跳板机或监控源的 IP / CIDR(例如 203.0.113.50/32)。向导中为必填项,不能留空。若要允许所有 IP 的 SSH,请输入 ANYWHERE(此时隔离期间管理用 SSH 也会向全世界开放)。
  3. 通知渠道设置:分别启用 Telegram Bot、LINE Messaging API、通用 Webhook(Slack / Discord / Teams)。
  4. eBPF 重大事件时的响应:选择 isolate(隔离主机)/ freeze(冻结该进程)/ alert_only(仅通知)。保存后会确认发送测试通知并重启服务。
  5. CVE 数据自动更新(默认 y):选择是否让容器隔离审计所使用的内核 CVE 数据库、Web 规则、KEV 列表、EPSS 评分、Node.js 漏洞数据,以及在 Ubuntu 服务器上用于操作系统软件包 CVE 比对的 Ubuntu 软件包 CVE 数据,从 lafine.net 匿名获取(签名清单每天确认一次,CVE 数据本体每周一次,KEV 列表每天一次,Web 规则只在清单版本更新时获取;仅 HTTPS GET,不含查询字符串和 Cookie,能表明软件身份的请求头只有固定的 User-Agent: RoamSwitch-Updater,并验证 Ed25519 签名)。不会发送任何有关本主机的信息。这是服务器版默认开启的唯一对外通信,选 n 即可停止(审计本身仍会基于内置基线运行,但 Ubuntu 服务器上的操作系统软件包 CVE 比对会显示“本地 CVE 数据未获取”)。如果现有的 server.conf 中已将其关闭,默认答案仍为 n。
  6. File Scan Guard 设置:设置是否为邮件中继、共享文件夹、上传目标启用病毒扫描(§13)及目标目录。可选功能,默认关闭。
  7. Resource Guard 设置:设置是否启用检测网络公开服务持续 RSS 增长(内存泄漏/DoS)或崩溃循环的资源枯竭防护。
  8. 常驻核心防护说明:显示无需通过向导、始终生效的核心防护功能列表,如入站默认拒绝、FIM、eBPF 集成等(无需输入)。
  9. 调查代理协作(investigation)设置:设置是否将 eBPF 重大事件,或关键路径 FIM/依赖锁文件篡改检测(均为仅通知判定时)的初步调查自动委托给外部 AI 代理 CLI(Claude Code / agy / Codex CLI / OpenCode,或自定义命令)(§10.1)。默认关闭。

向导接下来的步骤会在提问之前先检查当前状况,并告知缺少的内容。

向导的最后会显示用于确认的命令。服务器版不能使用 roamswitch guards,请用下面的命令确认。

sudo roamswitch status --server
sudo roamswitch doctor
sudo roamswitch detection-coverage
sudo roamswitch server config show
Telegram Chat ID 提示
超级群组的 Chat ID 是以 -100 开头的负数(例如 -1001234567890)。可在 curl -s "https://api.telegram.org/bot<token>/getUpdates" 响应中的 "chat":{"id":...} 字段确认正确的值。

3.3 42项服务器安全审计

sudo roamswitch status --server

对防火墙规则、Frag Gap 缓解、Yama LSM 限制、权限和 Docker 端口暴露执行即时 42 项检查审核,产生 0-100 的安全评分和等级(S 到 C)。 诊断还包括 Docker 的 daemon.json(user namespace、icc、live-restore、no-new-privileges、未启用 TLS 的 TCP 监听;没有 Docker 的主机不适用)、最近一次备份的运行时间(超过 7 天为不合格,不检查备份能否恢复),以及 Web 服务器实际提供的 TLS 证书的到期时间(剩余不足 30 天为不合格)。名称解析暴露项(server_name_resolution_exposure)在本机作为 LLMNR(UDP 5355)或 NBNS(UDP 137)的应答方运行时判为不合格。mDNS(UDP 5353)仅显示。42 是固定项目的数量,视主机情况,还会加入防护是否实际生效等项目。不适用的项目不计入分数。

极易被利用的漏洞(已安装的软件)(server_package_cve_exposure)。把操作系统软件包、PATH 上等位置的 PHP、GitLab 服务器与本机内的漏洞数据比对,查找属于 KEV 或 EPSS 达 0.9 以上的未修复漏洞(不联网)。软件包管理之外的其他软件,以及数据中没有的漏洞,都看不到。在每小时一次的诊断中,出现新的不合格、出现新的 KEV 标记、或保持原状满 24 小时时,会发送 1 条警报(附主机名和 IP)。恢复为合格时不通知。

每个检查项都会标注 NIST CSF 2.0 的职能/类别(适用时必定标注),以便用于合规报告。CIS Controls v8 的控制项编号,仅在存在高置信度对应关系时才标注。

Web 服务器的安全响应头与 Cookie:从本机请求 nginx、Apache、Caddy 的 TLS 站点首页(/),只查看响应头。检查 HSTS(30 天以上)、nosniff、防嵌入框架,以及 Cookie 的 Secure 和 HttpOnly,不判定 CSP 与 Referrer-Policy。不连接外部,也不记录正文和 Cookie 的值。

自有域名的 SPF、DMARC、MTA-STS 与到期时间:仅在 domain_check_domains 中填写了域名(最多 5 个)时才运行,检查 SPF 和 DMARC、SPF 是否允许任何人发信、距注册到期是否还有 30 天以上,以及有 MX 时检查 MTA-STS(CAA 和 DNSSEC 仅供参考显示)。

对外通信仅限此时,共 3 项。(1) dig 向 /etc/resolv.conf 中的解析器查询 TXT、CAA、DS、MX。(2) curl 通过 IANA 的公开列表(不含域名)查询注册机构,并把域名发送到该机构的 RDAP 服务器。(3) curl 读取该域名 mta-sts 主机上的 /.well-known/mta-sts.txt(验证证书,不跟随重定向,不带 Cookie)。结果缓存 6 小时。

未生效的防护会连同原因一起显示。可以用 roamswitch detection-coverage、roamswitch doctor,以及 MCP 的 get_guard_status(effectiveState 和 inactiveReason)确认。由安装状态造成的情况除外,从启动 2 分钟后起每 5 分钟检查一次,相同的原因每 24 小时向紧急通知渠道通知 1 次。

4. 防火墙和端口规则

配置文件 /etc/roamswitch/server.conf 出于保护敏感信息的目的,强制要求权限为 0600(仅 root 可读写)。格式为扁平的 key=value,形如 [network] 的分区标题行会被忽略。

# --- 防火墙 ---
ssh_ports=22                     # SSH 管理端口(紧急隔离时也保留)
allowed_ports=80,443             # 公开服务用的端口(仅 TCP。UDP 用 allowed_udp_ports)
whitelist_ips=203.0.113.10/32    # 维护来源 IP / CIDR(留空 = 全部允许,旧名 admin_source_ips 也可)
protect_docker_ports=true        # DOCKER-USER 保护(阻止容器绕过防火墙)
preserve_ssh_on_isolation=true   # 紧急隔离时也保留 SSH 管理通道(设为 false 则完全阻断)

# --- eBPF 运行时防护 ---
action_on_critical=isolate       # isolate | freeze(SIGSTOP+网络阻断) | alert_only
ebpf_socket_path=/run/roamswitch/events.sock

# --- Egress / C2 阻断与 DNS 黑洞 ---
egress_ip_blocklist_enabled=true # 默认 true。软件包自带的种子仅包含 JPCERT/CC 公布的 3 个攻击服务器;在安装情报源之前不会阻断其他任何内容
metadata_watch_enabled=true      # 默认 true。非 root 程序/容器连接云元数据时通知(仅记录、不阻断;用于发现 SSRF)
metadata_watch_allow_users=      # 正常使用元数据服务的账户(名称或数字 ID,逗号分隔;root 始终豁免)
dns_sinkhole_enabled=false       # 默认 false(避免破坏内部 DNS/split-horizon 环境)
dns_sinkhole_provider=quad9      # quad9 | cloudflare | adguard | cleanbrowsing

# --- 容器隔离 CVE 数据(默认开启) ---
cve_kernel_map_updates_enabled=true # 默认 true。默认开启的唯一对外通信(签名的内核 CVE 数据、Web 规则、KEV 列表,以及 Ubuntu 服务器上的 Ubuntu 软件包 CVE 数据;清单每天一次,CVE 数据本体每周一次,KEV 列表每天一次;匿名·仅接收·验证签名)。设为 false 即停止

# --- 通知 ---
telegram_enabled=false
telegram_bot_token=
telegram_chat_id=
line_enabled=false
webhook_enabled=false
webhook_url=
webhook_block_private_addresses=false   # opt-in SSRF guard
webhook_allow_addresses=

# --- 系统 ---
language=ja
fim_check_interval_secs=300      # 旧名 scan_interval 也可
isolation_hard_cap_secs=3600     # 高置信度隔离进入降级模式前的秒数(0 = 保持到解除)

allowed_ports 只针对 TCP 端口。来自外部的 UDP(WireGuard、DNS、NTP 服务器、HTTP/3 的 443/udp 等),除非写入 allowed_udp_ports,否则不会接受。例如 allowed_udp_ports=51820,443。默认为空,除对已建立连接的回复之外,所有 UDP 都会丢弃。

forward_* 的所有键都在 /etc/roamswitch/server.conf.example 中。无效的值和拼写错误的键会被忽略,并在 server config show 等处给出警告。如果存在 /etc/roamswitch/server.json,则不会读取 server.conf。config show 请以 root 身份运行。

如果直接编辑了设置,请重启服务使其生效(roamswitch-server 不支持 reload)。

sudo roamswitch server restart

4.1 按严重级别设置策略(guard.yaml,可选)

如果仅靠 action_on_critical 无法满足更精细的控制需求,可创建 /etc/roamswitch/guard.yaml(分发模板位于 /etc/roamswitch/guard.yaml.example)。若该文件不存在,会根据 server.conf 中的 action_on_critical 自动合成等效策略,不影响现有运行。

policies:
  on_warning:
    action: log_and_notify
  on_critical:
    server_action: isolate_process
    kill_process: true
    fallback_to_host_isolation_after_retries: 3   # 同一进程再次发生时自动升级为主机隔离
  on_emergency:
    action: isolate_host_all
    kill_process: true

server_safeguards:
  maintenance_ssh_ports: [22]
  safety_timer_secs: 300   # 低置信度隔离自动恢复前的秒数(0 为禁用)。不适用于高置信度隔离(见下文)

隔离的自动解除(按置信度):为避免被只会等待的攻击者突破,触发条件按置信度区分。低置信度(eBPF 的 Error / Warning 及以下、通用的端口异常等)在 safety_timer_secs(默认 300 秒)之后全部恢复。高置信度(金丝雀篡改、大量改写、eBPF 的 Critical / Emergency / Alert 等)只有在确认原因消失时才会解除并发出通知;若没有 ack 而达到 isolation_hard_cap_secs(默认 3600 秒,0 = 无上限),则进入降级(DEGRADED)模式。

降级模式会继续阻断管理路径以外的新通信,绝不会随时间流逝而自动开放。解除只能通过重新确认原因消失、ack 或 sudo roamswitch emergency-restore。无论哪种隔离,管理路径(maintenance_ssh_ports 和 whitelist_ips)以外的已建立连接都会被阻断,每次转换都以 10 种语言通知。

sudo roamswitch server ack

roamswitch server ack 在 FULL 隔离期间会保持隔离严格不变并做出确认应答(视为运维人员已接手,停止进入降级或自动解除),在降级期间则会解除隔离。

4.2 Egress / C2 阻断与 DNS 黑洞

egress_ip_blocklist_enabled=true(默认)时,会用 nftables 阻止向已知恶意 IP 的外发连接。列表在存在 /var/lib/roamswitch/threatfeed/malicious_ips.txt 时使用它,否则使用内置种子(二选一)。种子只有 JPCERT/CC 于 2026 年 10 月 15 日公布的 3 个攻击服务器地址(210.149.87.120、118.26.36.16、69.10.51.162)。如果正常的通信目标被阻止,请检查对应的行。

将 dns_sinkhole_enabled=true 设置为启用后,会强制通过过滤型 DNS 解析器(Quad9 / Cloudflare / AdGuard / CleanBrowsing)解析域名,阻断对已知恶意域名的解析。因可能破坏内部 DNS 或 split-horizon 环境,默认值为 false。

启用 metadata_watch_enabled(默认启用)后,当非 root 的程序或容器新连接到云元数据地址(如 169.254.169.254)时,inet roamswitch_metadata_watch 会记入内核日志,守护进程按账户每天通知 1 次。不会阻断通信。利用 302 重定向指向内部的手法在访问日志中看不到,而是通过这条外发通信捕获。正常使用可以用 metadata_watch_allow_users 排除(容器不可)。

4.3 入站端口扫描检测防护

通过将 nftables 日志规则与 journald 比对,检测在短时间内连接大量不同端口的来源 IP(默认启用)。置信度高的扫描源可在一定时间内自动封锁。与 RoamSwitch Sensor 并用时,会自动将 Sensor 一侧的 IP 排除在外(此检测与 §10.1 是不同的功能;为避免误报,已配对 Sensor 发出的全端口审计探测不在检测范围内)。

# --- 入站端口扫描检测(默认启用) ---
port_scan_detect_enabled=true              # false 表示禁用
port_scan_detect_min_distinct_ports=15     # 连接到不少于此数量的不同端口时判定为扫描
port_scan_detect_window_secs=300           # 判定的统计窗口(秒)
port_scan_block_enabled=true               # 自动封锁检测到的扫描来源 IP
port_scan_block_duration_secs=600          # 自动封锁的持续时间(秒)

可通过 roamswitch port-scan 命令查看检测历史。

4.4 DNS 隧道检测防护

用 NFQUEUE 检查本机发出的 DNS(UDP / TCP 的 53 端口)。当标签长度超过 40 字节且熵超过 3.8,或 qtype 为 TXT / NULL 的查询在 60 秒内达到 10 条时发出通知(再次通知需间隔 300 秒)。检测对象是 iodine、dnscat2 等 DNS 隧道。带有 bypass,即使守卫停止也完全不会妨碍域名解析。仅用于通知,不会自动阻断。dns_tunnel_detect_enabled 在重启后生效。

# --- DNS 隧道检测(默认启用) ---
dns_tunnel_detect_enabled=true              # false 表示禁用

也会检测子域名暴力枚举。同一域名下 40 个以上不同的名称在 60 秒内全部返回 NXDOMAIN 时发出通知(每个域名每小时 1 次,名称示例最多 5 个;ATT&CK T1590.002)。为此,UDP 的 DNS 响应(源端口 53)也通过 NFQUEUE 接收,但带有 bypass,不发送任何内容,也不会中断域名解析。

反向查询、.local 等内部名称、dns_tunnel_entropy_allowlist 中的域名等不计入。开关是 dns_tunnel_detect_enabled。TCP 响应、DoH 和 DoT、其他命名空间的容器、带扩展头的 IPv6 看不到。仅用于通知,不会阻断。

4.5 SSH 暴力破解防护

sshd 登录失败会在写入日志的瞬间按来源计数(默认启用)。在 600 秒内达到 6 次(默认)时,通过 nftables 的 inet roamswitch_sshguard 只丢弃发往 SSH 的新连接,并断开已建立的 SSH 连接。封禁从 1 小时起,每次重复变为 4 倍,上限 7 天。已认证的会话、公钥登录成功、被豁免的来源不在此列。不会与外部通信,只在本地运行 journalctl、nft 等。

日志通过 journalctl -f 读取,只使用 sshd 写入的行。没有 journald 时会跟踪 /var/log/auth.log 或 /var/log/secure,但伪造日志行有可能使第三方被阻断,因此请将 ssh_guard_log_source 保持默认的 auto。

统计密码失败、不存在的用户等,不统计公钥失败(Failed publickey)。来源从行末的 from <IP> port <N> 读取,因此伪造用户名无法使第三方被封禁。IPv6 以 /64 为单位(在包含需保护地址的 /64 中,仅限该地址)。

不封禁的对象:网关、DNS 解析器、本机、环回、whitelist_ips、ssh_guard_allow、已登录的来源、30 天内(ssh_guard_trust_key_days)用公钥登录成功过的来源、已配对的 Sensor。失败只做记录。私有地址不予豁免(因为内部被入侵的终端也可能成为来源)。

如果 fail2ban(sshd 的 jail 已启用)或 CrowdSec(firewall bouncer 在运行)已在防护,则把阻断让给它们,只做检测和通知(ssh_guard_yield_to_fail2ban,默认 true)。ssh_guard_block_enabled=false 也是同样的效果。通知只在封禁时(仅检测时为达到阈值)以及失败很多的来源登录成功时(严重。不会断开会话)发送。每小时超过 10 个的来源合并为 1 条。

用 roamswitch server bans 查看列表(支持 --json,需要 sudo),用 sudo roamswitch server unban <IP | IPv6 的 /64 | --all> 解除,失败次数也会一并清除。封禁在重启后会连同剩余时间一起恢复。roamswitch emergency-restore 不会解除封禁,roamswitch recover 和卸载会连表一起删除。MCP 的 get_ssh_guard_incidents 是只读的。在 Server TUI 的“SSH 暴力破解”中也可以查看和解除(root 时;§17)。

roamswitch server bans
sudo roamswitch server unban 203.0.113.9
sudo roamswitch server unban --all

设置项共有 10 个,都以 ssh_guard_ 开头(§18.1)。例如用 sudo roamswitch server config set ssh_guard_max_failures 10 修改,生效需要执行 sudo roamswitch server restart。要停止整个防护,设置 ssh_guard_enabled=false;只检测和通知,设置 ssh_guard_block_enabled=false。诊断(42 项)中的“SSH 暴力保护”,在本防护运行并执行封禁时也会通过。

局限:只反复产生公开密钥失败的尝试不计入。分散在大量来源地址上的暴力破解按来源逐个计数,因此在某个来源达到阈值之前不会被阻止。根本的对策是关闭密码认证,只允许公开密钥认证。

限定来源(可选启用):设置 ssh_allow_only_enabled=true,并在 ssh_allow_only_sources 中用逗号分隔写入 IP 或 CIDR,即可在 roamswitch_sshallow 表中从第一个数据包起切断来自其他来源的新 SSH 连接。已建立的连接、loopback 和本机自身地址会放行。IPv6 需要写 IPv6 条目。列表为空,或当前 SSH 来源不在列表中时,不会加载规则(可用 sudo roamswitch ssh-allow check 确认)。只要有一个条目无法解析,整个值都会被拒绝。设置每 30 秒重新读取,sudo roamswitch ssh-allow disable 会立即移除。emergency-restore 会保留规则,roamswitch recover 会移除规则。这与暴力破解封锁(ssh_guard_*)是分开的。即使设置损坏无法读取,也不会解除规则,而是用最后一次正确读取的值防护。无法确认时会通知一次,并在 ssh-allow status、TUI 和 doctor 中显示。

4.6 启动时的保护装置(xdp-gate)

sudo roamswitch xdp-gate enable 会启用一个关卡,保护从刚启动到防火墙加载之前的这段时间。没有 eBPF 对象时,不会更改任何内容就停止,并显示原因。标准软件包中不包含此对象。

启用时,先启用保护装置的定时器,再启用关卡。失败时会还原。下次启动时才会生效,并且只有定时器处于启用状态时,才会在启动 60 秒后放开关卡。可以用 sudo roamswitch xdp-gate status 确认状态。

5. SSH 锁定预防故障保护

运维远程服务器时最严重的事故是“防火墙配置错误导致 SSH 被锁在门外”。RoamSwitch Server Edition 配备了多重防护措施。

6.容器保护(Docker/Podman)

Docker 默认在发布容器端口(-p 8080:8080 等)时会创建自己的 iptables 规则,绕过(穿透)主机的标准防火墙,把端口直接暴露给全世界。这是一个已知问题。

protect_docker_ports=true(默认)时,发往容器的流量除 ssh_ports 和 allowed_ports 的端口外,也无法从外部到达。iptables 方式下,检查规则放入 DOCKER-USER 链;Docker 29 及以后的 nftables 方式下,放入 inet roamswitch_docker_guard 表(若 Docker 的 IPv6 已启用,IPv6 也同样处理)。判定依据是 DNAT 之前的目标端口,仅针对来自外部的流量。容器的出站流量和容器之间的流量不受影响。这是第二层防护:即使设为 false,默认拒绝的防火墙仍会从外部丢弃公开的端口。要从外部使用某个端口,请把主机侧端口加入 allowed_ports(UDP 为 allowed_udp_ports),然后运行 sudo roamswitch server restart。

此防护具有幂等性,并且每分钟自我修复一次。即使 dockerd 在 RoamSwitch 之后才启动、Docker 重启或重新加载导致规则被改写、手动执行了 nft flush 或 nftables 表丢失,也会在不触动当前有效防护的前提下重新设置。

监视 docker events,在以 --privileged 启动的容器或挂载了 /var/run/docker.sock 的容器(逃逸风险)启动后立即通知。容器 exec 防护(container_exec_guard_enabled,默认开启)会从已打开的描述符读取在容器内执行的二进制文件(即使已被删除),并用 YARA 检查。已在运行的容器也在检查范围内。两者都只通知,不会自动阻断。在 Docker 29 上也可运行。

7. 关键路径文件完整性监控(FIM)

使用 SHA-256 监控重要文件(/bin/login、/usr/bin/sudo、/usr/sbin/sshd 等重要二进制,/etc/shadow、/etc/sudoers 等认证配置,以及 systemd 单元)。

在重要目录(/etc/pam.d、/etc/sudoers.d、/etc/systemd/system、/root/.ssh 等)中,也会检测新文件的出现。所有可登录账户的 authorized_keys、/etc/ld.so.preload(出现即为 rootkit 的迹象)以及 RoamSwitch 自身的二进制文件同样在监控范围内。新文件检测需要包含此范围的基线,因此升级后请执行一次 sudo roamswitch fim update。非 root 的 fim verify 读不了的文件属于“因无法读取而跳过”,不是篡改。

7.1 手动哈希验证

sudo roamswitch fim verify

7.2 事件驱动检测(即时)

被监控的文件通过 fanotify(FAN_CLASS_NOTIF)监视,写入完成的同时核对哈希。周期扫描(默认 fim_check_interval_secs=300 秒)用于防止漏检。sed -i 等替换也能检测到,通知中会附上修改文件的进程和 SSH 登录(§7.5)。

7.3 操作系统更新时自动基线同步

在 Debian/Ubuntu 上,安装软件包时会自动配置 /etc/apt/apt.conf.d/99roamswitch-fim 的 DPkg::Post-Invoke 钩子。在 Fedora/RHEL/Rocky/AlmaLinux/openSUSE 上,监控 /var/lib/rpm 的 systemd.path 单元(roamswitch-fim-update.path)承担相同职责。更新过程中发现的篡改会保存在 /var/lib/roamswitch/fim_deferred.json 中,即使守护进程在此期间重新启动,也会在更新结束时连同写入者一起通知。

这样,当管理员执行 sudo apt upgrade(或 dnf upgrade / zypper update)使二进制文件被正常更新时,RoamSwitch 会自动检测到,并悄悄地重新同步哈希基线(避免误报警报)。若要手动应用更新,请执行下面的命令。

sudo roamswitch fim update

首次创建基线时,如果软件包管理(apt·dpkg、dnf·rpm、zypper、pacman)正在工作,最多等待 120 秒。即使在 apt install 之后立刻创建,也不会把 dpkg 的临时文件(*.dpkg-new 等)误认为篡改(1.11.18 及以后)。120 秒内仍未结束时,会记录一条警告并照常创建。

7.4 蜜罐凭据(Honeytokens)

守护进程启动时,会在 /root 放置 .aws/credentials、.ssh/id_rsa、.docker/config.json 3 种诱饵(蜜罐令牌)。已有真实文件时绝不覆盖。通过 inotify 发现这些文件被读取时,视为凭据搜寻(MITRE ATT&CK T1552),立即发出 Critical 通知并记入事件时间线。

默认启用。可通过 honeytokens_enabled(设为 false 会停止放置和监视,已放置的诱饵保留)和 honeytokens_home(默认 /root)更改。RoamSwitch 自身的 docker 命令对 DOCKER_CONFIG 使用空目录,因此不会触发诱饵。也会放置在 server.conf 的 agent_users(§20)的主目录中。通过 MCP 的 get_honeytoken_status 可以读取状态和最近 50 次访问(只读)。

诱饵被实际访问后,会添加相关的诱饵(.aws/credentials 对应 .aws/config,.ssh/id_rsa 对应 .ssh/config 等)。每次最多 2 个,总计最多 6 个。/root 中出现不熟悉的文件属于正常现象。

7.5 入侵路径(谁、通过哪次 SSH 登录做了修改)

文件变更通知(关键路径 FIM 和锁文件 FIM)会附上修改文件的进程(账户、可执行文件、命令)和 SSH 登录(来源 IP 和端口、时间、认证方式、密钥指纹)(默认启用;fim_intrusion_context_enabled)。为应对生命周期很短的进程,会在读取事件的当场抓取 /proc/<pid>,抓取不到时用执行记录器补充。即使 SSH 守卫被禁用也能工作,并且不向外部发送任何内容。

判定只使用内核报告的值(/proc/<pid>/exe、loginuid、cgroup 的 session-N.scope)。comm 等进程可以更改的值只用于显示,仅仅自称 sshd 不会被视为 SSH 登录。通知会区分已发现、“未发现 SSH 登录”、“无法查明登录途径”,即使获取失败也一定会发出。

/etc/ssh/sshd_config: modified
  进程: root(登录的账户: admin) / /usr/bin/tee / 命令: tee /etc/ssh/sshd_config (pid 4121)
  SSH 登录: 这是 admin 于 2026-10-17 03:12:08 从 203.0.113.25:51544 登录的会话(认证: publickey, 密钥 SHA256:AbCdEf0123456789)

/etc/sudoers: modified
  无法查明登录路径(这是定期检查发现的变更,不知道是哪个进程做的)

install、sed -i、同一目录内的 cp 和 mv 等以相同名称放入新文件的编辑,也会通过设在目录上的标记检测到。局限:从其他目录用 mv 移入的文件,要等到周期扫描(fim_check_interval_secs)才会发现,写入它的进程也无法得知。

除通知外,记录还会保留在时间线(类型 fim)和 /var/lib/roamswitch/fim_intrusions.json(仅 root 可读,最新 100 条)中,MCP 的 verify_fim 会将其显示在 recentIntrusionContext 中(仅限 root 时)。篡改的判定不变。局限:persistence_watch 的通知不附带该记录。能得知的只有修改的进程和登录,入侵的入口(被利用的漏洞等)无从得知。要关闭,请设置 fim_intrusion_context_enabled=false。

7.6 SUID / SGID 文件清单

查找 FIM 固定列表之外位置的新 SUID 文件,以及事后加上的 SUID。每隔 suid_watch_interval_secs(默认 600 秒)遍历本地文件系统,记录 SUID、SGID 可执行文件的模式、所有者、大小和 SHA-256(默认启用,suid_watch_enabled)。与 /var/lib/roamswitch/suid_baseline.json 中的初始列表比较,对新增、SUID 授予、模式或所有者或内容的变更,以 Critical 级别只通知一次(ATT&CK T1548.001)。

属于软件包(dpkg -S、rpm -qf 等)且 ctime 不晚于软件包数据库最新更新的文件发生的变化,不会通知,而是纳入基准。更新之后的 chmod u+s 会通知。确认用 sudo roamswitch fim verify,接受用 sudo roamswitch fim update。

局限:不遍历容器层(/var/lib/docker 等)、snap,以及网络、FUSE、overlay、squashfs 挂载。遍历期间设置后又去掉的位,以及软件包管理器运行期间的变化(最多推迟 3 次)都看不到。超过 300 秒的遍历,该轮结果会被丢弃。

7.7 日志清除检测

监视日志清除(ATT&CK T1070.002)。每隔 30 秒记录 auth.log、syslog、wtmp 等的 inode 和大小,对变小(原先 1024 字节以上)、消失或被替换的文件以 Critical 级别通知(默认启用,log_tamper_watch_enabled)。对于 journal,当归档总量从 4 MiB 以上降到不足五分之一时通知(如 journalctl --vacuum-time=1s)。

排除日志轮转(以相同名称开头的另一个文件具有相同的 inode 或在 120 秒内有变更,或 logrotate 的状态文件在 120 秒内更新)。局限:不改变大小而改写 wtmp、btmp、lastlog、清空后再写回原来大小的操作,以及守护进程停止期间的变化,都看不到。

7.8 勒索软件熵监控(entropy_watch_enabled)

在无法放置诱饵的位置(应用数据、文档根目录)发现文件加密。检查 entropy_watch_dirs(为空时为 /var/www、/srv、数据库存放位置等,最多 32 个)中文件的前 256 KiB,当同一写入者在 5 秒内写入 20 个看起来像随机数据的文件时通知。删除原文件的方式和用 rename 覆盖的方式也会监视。entropy_watch_enabled 默认启用,只做通知。

其设计不会使生产环境停止。不使用阻塞式 fanotify;每秒最多读取 entropy_watch_max_files_per_sec 个文件(5 到 2000,默认 50),且只读前 256 KiB,超过时切换为“部分运行”。只有在 entropy_watch_freeze=true 时,或在文档根目录中设为 entropy_docroot_action=freeze_writer 且 Web 服务替换已有文件时,才会停止写入者(SIGSTOP),protected_processes 不会被停止,可用 roamswitch frozen resume 恢复。

在 Ubuntu 24.04 的 VM 上,150 个文件的加密在第 20 个文件时被检测到(通知 1 条),cp -r、tar 等通知为 0 条,每秒 434 个文件时 CPU 约为 1 个核心的 2%。最近 50 条保存在 /var/lib/roamswitch/entropy_incidents.json 中(不保存命令行),由 MCP 的 get_ransomware_entropy_guard_status 读取。

8. eBPF 运行时防护和 Falco 集成

挂钩内核空间 eBPF 事件 (Falco / Tetragon) 以检测 Frag Gap 内核权限升级、容器逃逸和未经授权的反向 shell。

8.1 抗膨胀架构

为避免传统安全工具中常见的「syslog 爆炸式膨胀」和「磁盘空间被占满」问题,RoamSwitch 通过 UNIX 域套接字 /run/roamswitch/events.sock 与 Falco 直接对接。该套接字以仅 root 可用(0600)的方式创建,能写入的只有以 root 运行的 Falco(无需额外的权限设置)。

8.2 自主收容

检测到恶意代码执行或可疑通信时,守护进程会立即向该进程的 PID 发送 SIGSTOP 以冻结其执行,并用 nftables 规则阻断通信(Air-Gap)。

8.3 入侵证据自动保全(Forensic Evidence Capture)

eBPF 运行时防护封锁进程时(用 SIGSTOP 冻结并切断网络),会自动创建证据保全包(在 §4.1 的默认设置下相当于 Critical,相当于 Emergency 时在隔离之前)。内容是上限约 30 秒的数据包捕获(没有 tshark 则省略)和 /proc/<pid> 的快照,其中 environ 里名称包含 KEY/TOKEN/SECRET/PASSWORD 的值会替换为 [REDACTED]。manifest.json 记录所有文件的 SHA-256。

对于强制终止的封锁,/proc 快照在终止之前保存(最长 3 秒)。手动的 --pid 顺序相同,用 --no-packets 可省略数据包。

保存位置为 /var/lib/roamswitch/incident-evidence/<时间戳>-<ID>/。证据包不会自动删除。为避免占满磁盘,要删除超过保留期限(默认 30 天)的旧证据包,请执行以下命令:

sudo roamswitch-incident-capture prune [--keep-days N]

无需等待封锁,也可以随时手动创建快照:

sudo roamswitch-incident-capture snapshot [--pid PID] [--reason TEXT] [--trigger-event-id ID] [--json]

保存了证据包的检测,会在时间线中关联起来。roamswitch timeline 在检测下方用 └─ 显示保存的行,并附上证据包名称和 manifest 的 SHA-256。--json 和 MCP 的 get_incident_timeline 带有 evidence_refs(最多 8 条,只有名称和 SHA-256,不含内容)等。只在知道触发事件 ID 时才关联,不会按时间接近来关联。对于手动的 snapshot,可用 --trigger-event-id ID 传入。

8.4 隔离速度的测量与告警通路的心跳检测

eBPF 隔离的准确度和速度,取决于传感器(Falco 或 Tetragon)的规则。实际上,Falco 0.45.0 的标准规则(29 条)里,没有检测主机上反向 shell 的规则:针对反向 shell 的规则只用于容器,其中一部分还会被 RoamSwitch 的 priority: warning 条件丢弃。RoamSwitch 不以规则本身的质量为前提,而是用三件事来弥补:测量隔离所花的时间、定期确认告警通路是否畅通,以及自己也检测反向 shell。

隔离延迟的测量:对每个 eBPF 事件,将 detect_to_receive_ms(检测到接收)、receive_to_action_ms(接收到处置)、detect_to_action_ms(合计)记录在 ebpf_incidents.json 和 MCP 的 get_ebpf_incidents 中,进程隔离的通知里也会写明“从检测到处置 N 毫秒”。在 Ubuntu 24.04 的 VM(Falco 0.45.0,modern eBPF)上的实测,合计为 42 到 64 毫秒(到接收 1 到 2,到隔离和 SIGKILL 41 到 62),主机 Air-Gap 为 109 毫秒,在 150 毫秒的目标以内。Tetragon 没有 detect_to_receive_ms。

心跳(ebpf_heartbeat_interval_secs,默认 600 秒,0 为禁用,启用时 60 到 86400)会打开一个仅 root 可用的一次性路径,测量随附规则 96-roamswitch-heartbeat.yaml 的警报从 Falco 返回所需的时间。只有连续 2 次没有返回时(复查在 1 分钟后),才会警告,24 小时内最多一次。心跳的行不经过隔离或通知,直接丢弃,也不会向外部发送任何内容。实测往返为 2 到 6 毫秒,移除规则后约 164 秒发出警告,恢复后约 75 秒恢复正常。

状态保存在 /var/lib/roamswitch/ebpf_heartbeat.json,由 MCP get_ebpf_incidents 的 heartbeat 字段和诊断 K-04(eBPF 运行时代理,诊断项目数仍为 42)读取。即使 Falco 在运行,只要心跳没有返回,K-04 就不合格。限制:确认的只是一条规则(open 系列系统调用)的往返,无法得知其他规则是否单独损坏。在两次确认的间隔(默认 10 分钟)内损坏的部分,要到下一次确认才会发现。对 Tetragon 不执行。在 Falco 未运行或规则文件缺失的主机上,不做任何确认,也不发任何警告(停止由原有的通知负责)。Falco 每次确认都会向 syslog 写一行警告(默认设置下每天 144 行)。

8.5 反向 shell 检测(RoamSwitch 自带)

与 Falco 的规则无关,每 2 秒读取一次 /proc,查找标准输入输出连接到一条对外 TCP 连接的 shell 和解释器(bash、python 等)。连续 2 次看到的,每个进程报告一次。目标为私有地址的,仅在 reverse_shell_watch_include_private=true 时才计入,环回和已接受的连接不检查。

在 Ubuntu 24.04 的 VM 上,bash 的 /dev/tcp、python、perl、nc -e、socat exec: 约 2.4 秒就被检测到,而 ssh、带 ProxyCommand 的 ssh、git over ssh、nc 客户端没有被检测到。

检测会作为 Critical 级别的 eBPF 事件 RoamSwitch Reverse Shell,进入与 Falco 警报相同的路径(允许列表、guard.yaml 等),默认隔离并 kill 该进程。root 所有的反弹 shell 会导致按进程隔离失败,因此会进一步升级为整台主机的 Air-Gap。对于误报,可用 reverse_shell_watch_notify_only=true(默认 false,仅 Warning 通知)或 sudo roamswitch server allowlist add "RoamSwitch Reverse Shell" <进程名> 处理。reverse_shell_watch_enabled 默认为 true,reverse_shell_watch_include_private 为 false。

内置列表(init、sshd、RoamSwitch 自身等)和 server.conf 的 protected_processes(逗号分隔)中的进程,防护既不会 SIGSTOP 也不会 SIGKILL,只做记录和通知。名称只有在可执行文件位于 /usr/、/bin/ 等系统位置时才有效,/tmp 中的同名伪造品不受保护。安装在其他位置的软件,请用绝对路径书写并设为 root 所有。无法读取路径时,按名称保护。

roamswitch server allowlist test <rule> <process> [--exe 路径] 不更改任何内容,只显示是否属于允许列表或冻结、kill 保护的对象。在 sudo roamswitch server restart 之后生效。

server allowlist 的条目有期限,过期的条目在防护看来等同于不存在(列表中保留为“已过期:允许未生效”)。引入期限之前的条目作为“无期限(旧条目)”继续有效,每天通知一次。Server 守护进程每 5 分钟检查一次,在到期前 7 天和到期时各通知一次。把时钟调回去也不会让过期恢复(标记为 /var/lib/roamswitch/allowlist_clock,并不是针对拥有 root 的攻击者的防护)。只有人才能添加条目,防护和 MCP 都不会添加。封锁不设期限。在 Server TUI 中,按 e 键可延长 30 天。

限制:检测按名称(进程名和可执行文件名)筛选,因此名字不是 shell 或解释器、却把标准输入输出接到套接字的自制二进制文件,无法被发现。经由回环地址的连接(例如 ssh -R 的折返)和短于 2 秒的连接不在检测范围,主机进程空间中看不到的进程同样无法检测。Linux 客户端版也有同样的检测,只发出通知。

还会检查标准输入输出未连接到网络连接的两种情形。一种是解释器或 openssl s_client、nc 等的对外连接,与不带 -c 的交互式 shell 通过管道、FIFO、pty 双向相连,仅以 Warning 级别通知并记录(无论 guard.yaml 如何设置,都不隔离也不 kill;同时监听的进程除外)。另一种是已连接的 UDP 套接字,与 TCP 相同,为 Critical。

9. 紧急警报(Telegram / LINE / Webhook)

发生严重事件(端口被非法暴露、FIM 篡改、eBPF 威胁检测、触发紧急隔离)时,会立即把情况发送到外部通知平台。

[notifications]
language = ja
# Telegram:Bot Token 与 Chat ID
telegram_bot_token = "123456789:ABCdefGHIjklMNOpqrSTUvwxYZ"
telegram_chat_id = "-1001234567890"

# LINE:Messaging API 频道访问令牌与用户 ID
line_channel_access_token = "YOUR_LINE_ACCESS_TOKEN"
line_user_id = "U1234567890abcdef1234567890abcdef"

# 通用 Webhook(Slack、Discord、Teams、自建监控平台)
webhook_url = "https://hooks.slack.com/services/T00/B00/XXXXX"

即使未配置这些外部通知渠道,已发送的通知也会在本地保留最近1周。可通过 roamswitch notifications 查看。新记录的通知会以运行 roamswitch notifications 的人的显示语言显示。发送给通知目标时,使用 server.conf 中 language 的语言。

没有通知渠道,或已启用但 token、收件目标、URL 为空时,紧急检测不会送达任何人。记录只保留在 journalctl 和 roamswitch notifications 中。一条途径都没有时,诊断的“紧急通知的途径”一项会不合格,分数下降。不使用通知、只用 Server TUI 运维时也一样。

roamswitch notifications 是已发出通知的记录,不显示是否送达。是否能送达,请用 sudo roamswitch server test-notify 确认。它会向已设置的渠道发送真实的测试消息。

通知(Telegram、LINE、Webhook)收到 2xx 即视为已发送;408、429、5xx 和连接失败会重试;其他 4xx 不重试。重试会立即进行 3 次(间隔 1 秒、5 秒)。仍未送达的,会存入 /var/lib/roamswitch/pending_deliveries.json(root 所有,0600,最多 50 条),每 5 分钟重发一次,满 24 小时或 24 次后放弃。重发的通知会带有“[延迟发送]”之类的标记(遵循 language)。日志中不会输出令牌、URL 中的机密(user:pass@)和 Authorization。

当防护功能连续 2 分钟以上无法读取输入,或记录到漏读(日志轮转、队列溢出等)时,也会通知上面的通知目标(同一防护功能和类型每天最多 1 次)。在此期间可能没有检测到。次数和时间保留在 get_guard_status 的 collectors 以及 /run/roamswitch/collectors.json 中。

Server 自身异常终止:守护进程异常终止(崩溃、OOM 终止、SIGKILL)并由 systemd 重新启动后,会向上面的通知目标发送通知(通知历史和时间线中也会保留)。连续终止时,每小时合并为 1 条带次数的通知。systemctl stop・restart、软件包更新、操作系统重启、断电之后不会发出。失去响应时,systemd 会按 WatchdogSec=30 在 30 秒后重新启动,这也会通知。终止原因可用通知中的 sudo journalctl -u roamswitch-server --since "…" 确认。

拒绝 Webhook 目标为内部地址(可选启用):webhook_block_private_addresses=true(默认 false)时,如果目标是环回、私有(10/8、172.16/12、192.168/16)、链路本地(169.254/16)、ULA(fc00::/7)或 CGNAT(100.64/10),则拒绝发送。主机名只要解析结果中有一个符合就拒绝,其他写法也会判定。由于连接固定到解析结果,也能防止 DNS rebinding。正当的目标可用 webhook_allow_addresses 允许,事件转发也有相同的设置。设置了 HTTP 代理环境变量时,不在此检查范围内。

10.AI代理/MCP集成(模型上下文协议)

RoamSwitch 服务器版包括 roamswitch-mcp,允许 AI 代理(Claude、Gemini、Cursor)监控基础设施健康状况和状态。

不含更改设置工具的设计
即使 Web 应用等的日志中混入了恶意的提示注入,AI 代理也不会被利用来打开防火墙或解除隔离,因为通过 MCP 提供的工具中,没有一个会更改设置、防御、端口或设备。工具大多只读,写入仅限于 3 个工具更新自己的记录文件。更改策略或解除进程冻结,必须在本地 TTY(SSH 终端)中显式执行命令。

诊断结果中如果有外部人员可以改写的字符串(日志文本等),会附上“不可信的外部数据”的提示。若有类似对 AI 的指令的写法,还会附上只含类型和数量的 WARNING。get_detection_coverage 返回每种手法能否检测、盲点以及负责的防护是否在运行(用 isServer 选择 Edition)。

MCP 的所有工具都带有注解。readOnlyHint 为 false 的只有更新自己记录文件的 run_active_vuln_scan、audit_security_logs、run_npm_audit_signatures,openWorldHint 为 true 的只有默认禁用的 run_npm_audit_signatures。域名的 DNS 和 RDAP 查询仅针对写入 domain_check_domains 的内容,默认为空。get_vulnerability_scan_history 返回探测留在对方上的痕迹(sideEffects),run_active_vuln_scan 返回 evidenceKind,表明是已确认还是仅版本匹配。

配置示例(`claude_desktop_config.json`)

{
  "mcpServers": {
    "roamswitch": {
      "command": "/usr/bin/roamswitch-mcp",
      "args": []
    }
  }
}

10.1 调查代理协作(investigation,将初步自动调查委托给 AI 代理)

§10 的 roamswitch-mcp 用于人工查询,而 investigation 联动是守护进程以检测为契机,自主启动外部 AI 代理 CLI。对象是仅以通知告终的 eBPF 重大事件,以及 FIM 和锁文件的篡改检测。守护进程会附上自己生成的初步判定报告来启动 CLI,并交给它进行追加调查和摘要。默认禁用。

# 追加到 /etc/roamswitch/guard.yaml(与 server.conf 是不同的文件)
investigation:
  enabled: true
  command: "claude"                 # "claude" | "agy" | "codex" | "opencode" | 任意自定义命令
  args: ["-p"]                      # 提示词会自动作为末尾参数追加
  timeout_secs: 180

也可以在 sudo roamswitch server setup 向导(§3.2)中设置。工具可选 Claude Code(claude -p)、agy(agy -p --dangerously-skip-permissions)、Codex CLI(codex exec)、OpenCode(opencode run)的预设,或任意命令。再次运行时,会选中已保存的设置。

关于提示词注入的注意事项
investigation 联动会把检测事件的详情(包含攻击者可部分操控的字符串)作为截断后的 JSON 字符串交给 AI 代理。无法伪造出指令字段,但内容仍有可能被当作指令读取。

因此不能以 root 运行,run_as 中没有普通用户的设置不会被向导保存,守护进程也不会启动。用 --dangerously-skip-permissions 等跳过权限确认会提高风险。在会混入不可信日志的环境中,建议使用不跳过的设置。

在网络中断期间(如 Air-Gap 触发时等,相当于 isolate_host_all 的状态)不会调用 investigation 协作。

11. CLI 命令备忘单

命令 特权 描述
sudo roamswitch status --server root 显示 42 项服务器安全诊断的评分和状态(使用 --json 以 JSON 输出相同内容)
sudo roamswitch ports root 审计开放的监听端口和绑定的进程
sudo roamswitch fim verify root 验证关键路径系统文件的 SHA-256 完整性
roamswitch notifications 用户 显示最近一周的通知历史(所有已发送的告警)(同样支持 --json / --export 文件)
sudo roamswitch server setup root 启动交互式初始配置向导
sudo roamswitch fim update root 刷新 FIM SHA-256 基线数据库
sudo roamswitch server config set <key> <value> root 修改并保存单个配置键(列表见 §18)
sudo roamswitch emergency-restore 根 解除全部 eBPF/防火墙紧急隔离,恢复到初始基线
roamswitch port-scan 普通用户 显示入站端口扫描检测防护(§4.3)的检测历史(来源 IP、是否自动封锁及封锁时长)
roamswitch sensor [key|list|pair|unpair|request-audit|results] 普通用户/root 与 Sensor 通过配对码方式建立双向信任。用 pair --addr <IP> --code <代码> --fingerprint <SHA-256> 配对,用 repin 在证书重新生成后更新固定值,用 request-audit 请求审计(结果用 results 查看)。需要 sensor_pairing_enabled: true(默认 OFF)。详见 Sensor 运维手册
roamswitch server tui 普通用户/root 启动可操作全部功能的 TUI(普通用户为只读,root 可进行全部操作。§17)
sudo roamswitch server ack root 对当前的紧急隔离做出确认应答(FULL 隔离期间保持严格隔离,降级期间则解除。§4.1)
roamswitch server ebpf 用户 显示 eBPF 运行时防护当前的隔离状态和已检测事件的历史
roamswitch server bans [--json] 普通用户/root 显示 SSH 暴力破解防护(§4.5)的状态,以及当前被封禁的来源地址(含剩余时间)。支持 --json。封禁列表只有 root 能读取
sudo roamswitch server unban <IP | IPv6 /64 | --all> root 解除 SSH 暴力破解防护的封禁,并清零该来源地址的失败计数(IPv6 以 /64 指定,--all 解除全部)
sudo roamswitch server allowlist [list|add <rule> <process> [--exe <path>] [--days N] <reason...>|renew <rule> <process> [--days N]|remove <rule> <process>] root 管理 eBPF 防护的允许列表(放行误报)。add 必须填写理由,并带有 --days N(1 至 365,默认 30)的有效期。用 --exe 绑定到路径后,伪造名称无法绕过。renew 重新设置有效期,list 显示有效期、剩余天数、添加者和理由
roamswitch server allowlist test <rule> <process> [--exe <path>] 普通用户/root 不做任何更改,显示该规则与进程的组合是否在允许列表中,以及该进程是否受到冻结和终止的保护(包括 protected_processes)。也可用 --pid PID 代替名称和路径。当防护的动作是由已到期的条目引起时,会指出这一点。
roamswitch frozen [list|resume <PID>|resume all] 普通用户/root 列出被防护以 SIGSTOP 冻结的进程,并在属于误报时解除(SIGCONT)。使用 resume all 可全部解除
sudo roamswitch events search|tree|export|verify|status root 搜索执行记录器(--since 2h --pid --exe --user --parent --text --json)、进程树、导出、哈希链验证、状态显示(§15)
sudo roamswitch forward status|test|queue root 查看事件转发的状态、发送测试事件、显示重发队列(§16)
roamswitch timeline / notifications [--json] [--export FILE] 用户 显示统一事件时间线(实验性)/通知历史。使用 --json 输出 JSON 数组,使用 --export 文件 输出 JSON Lines。在保存了证据包的检测下方,保存记录以 └─ 显示,并附上证据包名称。使用 --json 时,只有存在关联的记录才会带有 parent_event_id、root_event_id 和 evidence_refs。
roamswitch audit-agent-setup [--json | --format text|json|sarif] 用户 以只读方式检查 AI 智能体的指令文件、技能、记忆以及 OpenClaw 设置中的危险内容(仅限主目录,不进行网络通信)。检查结果带有 OWASP LLM 和 ATT&CK 标签,可用 --json 或 --format sarif(SARIF 2.1.0)输出。还会读取 ~/.claude/settings.json,以及 Gemini CLI、Codex、Cursor、OpenCode 的设置(.gemini/settings.json、.codex/hooks.json、.codex/config.toml、.cursor/hooks.json、opencode.json、.opencode/plugins/)中仅打开就会执行的钩子,以及 Codex 和 OpenCode 的 MCP 设置。
roamswitch detection-coverage [--server | --client] [--json | --format json|navigator] 用户 针对入侵者用来削弱防御、清除痕迹或长期潜伏的每种 MITRE ATT&CK 技术,列出 RoamSwitch 能否发现(检测 / 部分 / 未覆盖)、看不到的部分,以及负责的防护现在是否在运行(运行中 / 已停止 / 部分运行 / 未知)。只读取代码自带的对照表和本地设置,不执行任何操作,也不通信。测试会检查每项说法背后的代码是否仍然存在,不在列表中的技术未做评估。Client Edition 列出 38 种技术(部分 31、未覆盖 7),Server Edition 列出 38 种(部分 25、未覆盖 13),没有被评为“检测”的技术。用 --server / --client 选择 Edition(省略时为已安装的 Edition)。--json 输出与 MCP 工具 get_detection_coverage 相同的 JSON。也可以在 Server TUI 的“工具”中运行。 使用 --format navigator 可把同一张表输出为 MITRE ATT&CK Navigator 图层(layer 4.5):检测为绿色,部分为黄色,未覆盖为红色,未评估的技术不着色。
roamswitch vuln-accept <ECOSYSTEM> <PACKAGE> <CVE-ID> --version VERSION --reason TEXT [--days N] | --list | --revoke ... 用户 由人对软件包 CVE 比对的检出记录带期限的“接受”。roamswitch vuln-accept <生态系统> <软件包> <CVE-ID> --version VERSION --reason 原因 [--days 天数](原因必填。默认 90 天,最长 365 天)、--list、--revoke。已接受的检出仍保留在结果中,并与“需处理”分开计数。到期后恢复原状,并保留在通知历史中。仅对指定版本有效,无法通过 MCP 接受
roamswitch sigma-check [RULE.yml] [--against-exec-history] [--json] 用户/根用户 检查您放在 /etc/roamswitch/sigma.d 中的 Sigma 规则(process_creation 的一部分写法)能否加载。--against-exec-history 会拿已记录的执行(exec)事件试验匹配(执行日志仅 root 可读)。无法加载的规则会连同原因列出。只读取属于 root 且其他用户不可写的文件。执行记录器中的匹配只会产生通知、时间线记录和转发,不会进行拦截。不进行网络连接
roamswitch doctor [--json] 用户/根用户 检查本机能否支撑 RoamSwitch 的防御(不更改任何内容,也不进行通信)。检查必需工具(nft、systemctl 等)是否存在,它们和 RoamSwitch 的文件是否可被 root 以外的用户写入,dpkg --verify / rpm -V 的结果,手动安装的 CA 证书,以及守护进程和 ufw、fail2ban 等是否在运行。用 --json 输出 JSON。只要有 1 项失败,退出码即为 1(仅有提醒时为 0)。也可从 Server TUI 的“工具”使用。
roamswitch scan-frontend <FOLDER> 用户/根用户 在对外发布的前端文件中查找 API 密钥、私钥等(与 audit-secrets 相同的检测)、JWT 和 source map(.map)。读取 dist、build、public 等,没有则读取文件夹本身(audit-secrets <文件夹> 不检查 dist 和 build)。值只显示前 4 个字符和长度,发现问题时退出码为 1。上限为每个文件 5 MB、总计 200 MB、20,000 个文件,不跟随符号链接。

12. 故障排除和常见问题解答

Q1. RoamSwitch 会意外断开我的 SSH 会话吗?

不会。平时始终放行已建立的连接和 ssh_ports(默认 22),Air-Gap 紧急隔离期间,只要 preserve_ssh_on_isolation=true(默认),就会保留维护用 SSH 端口以及来自管理 IP 的管理会话(其他已建立的连接会被断开)。服务器版 1.10.4 及更早版本中隔离期间 SSH 无法连通的问题,已在 1.10.5 修复。

Q2。如果不小心被锁定,如何重新获得访问权限?

通过云服务商的 Web 管理控制台(VNC/串行控制台)登录,执行 sudo roamswitch emergency-restore 解除紧急隔离,或执行 sudo systemctl stop roamswitch-server 停止服务。

Q3。如何为新添加的 Web 服务(例如 Nginx)公开端口?

执行 sudo roamswitch server config set allowed_ports 80,443,3000(或直接编辑 /etc/roamswitch/server.conf),然后执行 sudo roamswitch server restart。allowed_ports 是 TCP 端口。要接受 UDP 时,请写入 allowed_udp_ports。

13. File Scan Guard(保护邮件中继、共享文件夹与上传目的地)

仅当此主机存在用于保存要交给他人的文件的目录(如邮件中继、Samba/NFS 共享、文件上传目的地)时才需要关注的可选功能。内置 YARA 引擎无需外部依赖即可持续扫描 clamav_scan_dirs,设置 clamav_enabled=true 后还会加入 ClamAV 作为第二重判断。确认的威胁会自动隔离至 /var/lib/roamswitch/quarantine,并通知运维人员。

# --- File Scan Guard(ClamAV,可选启用) ---
# 内置 YARA 引擎始终无条件扫描 clamav_scan_dirs。
clamav_enabled=false             # 设为 true 可启用 clamdscan 进行额外检查
clamav_scan_dirs=                # 扫描目标的绝对路径(以逗号分隔)
clamav_scan_interval_secs=86400  # 扫描间隔(秒,最小 3600)
clamav_freshclam_interval_secs=7200  # 特征库自动更新间隔(秒,最小 1800)

也可通过交互式向导 sudo roamswitch server setup 进行配置,并可通过 get_file_scan_guard_status MCP 工具查看配置与隔离状态。

服务只能写入 /var/www、/srv、/root、/opt、/etc/roamswitch 之内等位置,在此之外,放置诱饵和文件扫描的隔离会失败。其他位置请在 sudo systemctl edit roamswitch-server 的 [Service] 中添加 ReadWritePaths=-/路径,然后重启。无法写入的位置会由 roamswitch doctor 发出警告。

用 YARA 或 ClamAV 发现但无法隔离的文件,会连同文件名和原因一起通知。

14. Log Audit(日志模式异常检测与通知)

定期扫描 journalctl,把日志消息归并为模板,检测新模式(以往未出现过的日志形态)和频率异常(统计意义上的突增,Z-score > 3.0)。无需额外的守护进程或外部依赖,是一种轻量机制,因此默认启用。检测到后,会通知到与 File Scan Guard 和 FIM 相同的通知目标(Telegram / LINE / Webhook)。日志中可能包含的 API 密钥和令牌,会在写入通知正文之前自动遮蔽。

# --- Log Audit(默认启用) ---
log_audit_enabled=true           # 设为 false 可禁用
log_audit_interval_secs=1800     # 扫描间隔(秒,最小 300)

也可以通过交互式向导 sudo roamswitch server setup 进行设置。最新的检测结果可用 roamswitch audit-logs 命令或 audit_security_logs MCP 工具查看。

访问日志诊断工具 AccessScope(独立工具):Server Edition 的 deb / rpm 中附带 accessscope 命令,以只读方式诊断 Web 服务器和 SSH 的访问日志(无图形界面应用)。分析既不使用 LLM,也不使用网络。LLM 分析为可选项,默认关闭(建议以无特权用户运行)。用 accessscope scan --auto 诊断,用 accessscope discover 列出日志位置(AccessScope 页面)。同一软件包中的 PersonalSOC 和 PathScope(personalsoc、pathscope)本身也不进行通信,PersonalSOC 的 LLM 分析仅在带 --llm 时运行。

15. 执行记录器与关联规则(本地,仅通知)

通过 netlink 的 proc connector 记录进程执行(可执行文件、参数、父进程谱系、UID、cwd、容器 ID、SHA-256;默认开启)。记录以带哈希链的 JSON Lines(0600,默认 200 MB / 14 天)保存在仅 root 可访问的 /var/lib/roamswitch/exec_log 中,不向外发送。对篡改只做检测(events verify),不做防止。CPU 占用控制在预算(默认 3%)以内。

正在写入的记录由每 10 秒一次的 checkpoint 行保护,其后的部分(最多约 10 秒的量)无法验证,verify 会显示这部分的条数。

在本地搜索和导出(由于是仅 root 可读的日志,通常需要 sudo)。

sudo roamswitch events status
sudo roamswitch events search --since 2h --exe curl
sudo roamswitch events tree 4242
sudo roamswitch events export --since 1d > exec-events.jsonl
sudo roamswitch events verify

关联规则 EXR-001〜016(仅通知,附带 MITRE ATT&CK 技术 ID):EXR-001 由 Web 服务启动的 Shell / EXR-002 从 /tmp、已删除文件、memfd 执行 / EXR-003 下载后立即执行 / EXR-004 使用 base64、eval 的解释器单行命令 / EXR-005 非 setuid 来源的 uid 0 获取 / EXR-006 执行 cron、systemd 刚刚放置的二进制 / EXR-007 ld.so.preload 变更后的执行。各规则采用安静的默认值,单独不会触发隔离。可通过 exec_rules_disabled(例如 EXR-003,EXR-004)单独禁用,也可通过 exec_rule_service_users 调整 EXR-001 的目标用户。EXR-016 通知没有终端的 ssh 打开的 -R・-D 隧道(Medium,T1572,即使选择启用也不用于隔离)。sshd 会话打开监听时(接收 ssh -R 的一方),也会以 High 通知。固定的账户和端口可以用 sudo roamswitch server allowlist add ssh-remote-listen <账户>:<端口> <理由> 排除。

EXR-008 由已知管理工具之外的程序删除快照(btrfs、LVM) / EXR-009 在 30 秒内查找 8 种以上攻击工具 / EXR-010 脚本解释器在 2 分钟内启动 3 种以上攻击工具 / EXR-011 命令行反向 shell 的形态(严重度 高) / EXR-012 服务下的非 root 进程带 PID 启动 gdb、strace、ltrace(严重度 中)。EXR-011 和 EXR-012 依据命令文本判定,因此即使将 exec_rules_isolation_optin 设为 true 也不会隔离。

EXR-013 在由服务(如 nginx)启动、或以该账户运行的进程,带着指向系统之外库的 LD_PRELOAD 或 LD_AUDIT(严重度 高),或指向 /tmp 等的 LD_LIBRARY_PATH(中。不会触发隔离)运行时发出通知。针对的是用 putenv("LD_PRELOAD=…") 和 mail() 绕过 PHP 的 disable_functions 的手法。root 和登录用户除外。记录的只有这 3 个变量的值(最多 200 个字符),不读取其他环境变量。EXR-009 和 EXR-010 新增了 chisel、mimikatz 等,EXR-010 还扩展到 /home、/root、/tmp 中的程序。

EXR-014 在 AI 智能体(claude、codex 等)的子进程执行了把凭据或机密值发送到外部的命令时通知(文件为 High,仅值为 Medium),EXR-015 在读取凭据后 5 分钟内发送到外部时通知(Medium)(均为 T1048,仅通知)。能看到的只有子进程的命令,内置工具的读取、python 或 node 自身的通信、进程名为 node 的智能体都看不到。

只有明确将 exec_rules_isolation_optin(默认 false)设为 true 时,严重度高的规则才会被当作高置信度的隔离触发条件(§4.1)。默认情况下,规则只通知。也可通过只读的 MCP 工具 search_exec_events / get_process_tree 查询。

16. 事件转发(SIEM / syslog / Webhook,需主动开启)

可以把检测事件转发到运维人员指定的本组织目标。默认关闭。在设置 forward_enabled=true 并配置至少一个目标之前,不会发送任何内容,也未内置任何厂商的目标。转发的是事件时间线、通知历史、eBPF 防护、隔离状态转换、FIM、金丝雀和 exec 规则的告警,不转发 exec 的原始日志本身。目标有以下 3 种。

未能发送的事件(TCP / TLS / Webhook)会放入磁盘上的重发队列(0600,上限由 forward_queue_max_mb 默认 20 和 forward_queue_max_age_hours 默认 72 决定),重启后也会按指数退避重发。发送的严重度下限由 forward_min_severity(默认 low)决定。为避免阻塞热路径,发送在专用线程中进行,队列溢出时从最旧的开始丢弃。

查看状态、测试连通性、查看重发队列时,使用以下命令(更改设置后请重启服务)。

# /etc/roamswitch/server.conf
forward_enabled=true
forward_syslog_url=tls://siem.example.org:6514
forward_syslog_format=rfc5424
forward_tls_ca_file=/etc/ssl/certs/corp-ca.pem
forward_min_severity=medium

sudo roamswitch server restart
sudo roamswitch forward status
sudo roamswitch forward test
sudo roamswitch forward queue

17. Server TUI(可操作全部功能的终端 UI)

roamswitch-server-tui(也可用 roamswitch server tui 启动)是一个 TUI,可通过 SSH 仅用键盘操作分散在 CLI 子命令和两个配置文件(server.conf 与 guard.yaml)中的 Server Edition 全部功能(可在 80x24 下运行,支持 10 种语言)。如果新增了 CLI 子命令或配置键,而 TUI 中没有对应操作,开发时的测试会失败。

启动:

sudo roamswitch-server-tui    # full control
roamswitch-server-tui         # read-only
roamswitch server tui         # same as roamswitch-server-tui

18. 配置键一览(server.conf / guard.yaml)

roamswitch-server 不支持 reload,任何键都需要重启才能生效(sudo roamswitch server restart)。server.conf 用 roamswitch server config set <键> <值> 或 §17 的编辑器修改,guard.yaml 用编辑器或手动修改。

例外情况:ssh_allow_only_enabled 与 ssh_allow_only_sources 无需重启,保存后约 30 秒内生效。无法读取 server.conf 或其中的值行时,不使用默认值,而是使用最后一次正确读取的值(/var/lib/roamswitch/server.conf.last-good,仅 root 可读)运行,CLI 和 TUI 会显示有无法确认的设置。损坏的文件会在下次保存前保留为 server.conf.corrupt-…。

18.1 server.conf(131 个键)

键 类型 / 可取值 默认 重启
languagesystem | ja | en | zh-hans | zh-hant | ko | de | fr | es | it | ptja需要
ssh_portsport list22需要
allowed_portsport list80,443需要
allowed_udp_portsport list—需要
whitelist_ipslist—需要
preserve_ssh_on_isolationbooltrue需要
telegram_enabledboolfalse需要
telegram_bot_tokenstring—需要
telegram_chat_idstring—需要
line_enabledboolfalse需要
line_channel_access_tokenstring—需要
line_user_idstring—需要
webhook_enabledboolfalse需要
webhook_urlURL—需要
webhook_block_private_addressesboolfalse需要
webhook_allow_addressesCIDR list—需要
action_on_criticalisolate | freeze | alert_onlyisolate需要
ebpf_socket_pathabs path/run/roamswitch/events.sock需要
ebpf_heartbeat_interval_secs0 (off) | int 60–86400600需要
isolation_hard_cap_secsint ≥ 03600需要
protected_processeslist—需要
fim_check_interval_secsint ≥ 10300需要
fim_intrusion_context_enabledbooltrue需要
protect_docker_portsbooltrue需要
dns_sinkhole_enabledboolfalse需要
dns_sinkhole_providerquad9 | cloudflare | adguard | cleanbrowsingquad9需要
egress_ip_blocklist_enabledbooltrue需要
metadata_watch_enabledbooltrue需要
metadata_watch_allow_userslist—需要
cve_kernel_map_updates_enabledbooltrue需要
clamav_enabledboolfalse需要
clamav_scan_dirsabs path list—需要
clamav_scan_interval_secsint ≥ 360086400需要
clamav_freshclam_interval_secsint ≥ 18007200需要
lockfile_watch_dirsabs path list—需要
domain_check_domainsdomain list (max 5)—需要
npm_audit_signatures_enabledboolfalse需要
log_audit_enabledbooltrue需要
log_audit_interval_secsint ≥ 3001800需要
resource_guard_enabledbooltrue需要
resource_guard_rss_sample_interval_secsint ≥ 1060需要
resource_guard_rss_window_secsint ≥ 3001800需要
resource_guard_rss_min_samplesint ≥ 310需要
resource_guard_rss_min_growth_pctint ≥ 1050需要
resource_guard_rss_recovery_drop_pctint ≥ 110需要
resource_guard_rss_min_kbint ≥ 020000需要
resource_guard_crash_loop_window_secsint ≥ 60300需要
resource_guard_crash_loop_min_restartsint ≥ 23需要
resource_guard_correlation_window_secsint ≥ 60600需要
resource_guard_zombie_min_countint ≥ 020需要
resource_guard_load_min_normalizedfloat ≥ 0.00.5需要
resource_guard_load_enabledbooltrue需要
resource_guard_cpu_enabledbooltrue需要
resource_guard_cpu_sample_interval_secsint ≥ 060需要
resource_guard_cpu_window_secsint ≥ 0600需要
resource_guard_cpu_min_samplesint ≥ 08需要
resource_guard_cpu_pct_thresholdfloat 0.0–1000.080.0需要
container_exec_guard_enabledbooltrue需要
port_scan_detect_enabledbooltrue需要
port_scan_detect_min_distinct_portsint ≥ 015需要
port_scan_detect_window_secsint ≥ 0300需要
port_scan_block_enabledbooltrue需要
port_scan_block_duration_secsint ≥ 0600需要
ssh_guard_enabledbooltrue需要
ssh_guard_block_enabledbooltrue需要
ssh_guard_max_failuresint 2–10006需要
ssh_guard_window_secsint 10–86400600需要
ssh_guard_ban_secsint 60–25920003600需要
ssh_guard_ban_max_secsint 60–31536000604800需要
ssh_guard_allowIP/CIDR list—需要
ssh_guard_log_sourceauto | journal | abs pathauto需要
ssh_guard_yield_to_fail2banbooltrue需要
ssh_guard_trust_key_daysint 0–365030需要
ssh_allow_only_enabledboolfalse不需要(约 30 秒)
ssh_allow_only_sourcesIP/CIDR list—不需要(约 30 秒)
agent_usersname list—需要
agent_egress_allowaddr[:port] list—需要
agent_setup_watch_secsint 0, 30–86400300需要
prn_recordboolfalse需要
prn_retention_hoursint 1–16824需要
prn_max_mibint 16–4096256需要
dns_tunnel_detect_enabledbooltrue需要
reverse_shell_watch_enabledbooltrue需要
reverse_shell_watch_include_privateboolfalse需要
reverse_shell_watch_notify_onlyboolfalse需要
suid_watch_enabledbooltrue需要
suid_watch_interval_secs60 – 86400600需要
log_tamper_watch_enabledbooltrue需要
sensor_pairing_enabledboolfalse需要
sensor_colocatedboolfalse需要
forward_enabledboolfalse需要
forward_syslog_urlURL—需要
forward_syslog_formatrfc5424 | cefrfc5424需要
forward_syslog_framingoctet | lfoctet需要
forward_tls_ca_fileabs path—需要
forward_file_pathabs path—需要
forward_file_max_mbint 1–1000050需要
forward_file_keepint 1–1005需要
forward_file_group组名 | gid—需要
forward_webhook_urlURL—需要
forward_webhook_secretstring—需要
forward_webhook_secret_fileabs path—需要
forward_webhook_block_private_addressesboolfalse需要
forward_webhook_allow_addressesCIDR list—需要
forward_min_severityinfo | low | medium | high | criticallow需要
forward_queue_max_mbint 1–1000020需要
forward_queue_max_age_hoursint 1–876072需要
exec_recorder_enabledbooltrue需要
exec_recorder_retention_mbint 1–100000200需要
exec_recorder_retention_daysint 1–365014需要
exec_recorder_hash_chainbooltrue需要
exec_recorder_hash_exebooltrue需要
exec_recorder_cpu_budget_pctint 1–503需要
exec_rules_enabledbooltrue需要
exec_rules_disabledstring—需要
exec_rule_service_usersstring—需要
exec_rule_window_secsint 5–3600120需要
exec_rules_isolation_optinboolfalse需要
config_regression_notice_enabledbooltrue需要
honeytokens_enabledbooltrue需要
honeytokens_homeabs path/root需要
harden_userns_enabledbooltrue需要
dns_tunnel_entropy_allowlistlist—需要
fleet_forwarding_allowed_hostslist—需要
fleet_forwarding_allow_plaintextboolfalse需要
entropy_watch_enabledbooltrue需要
entropy_watch_dirslist (max 32)—需要
entropy_watch_freezeboolfalse需要
entropy_docroot_actionnotify | freeze_writernotify需要
entropy_watch_max_files_per_secint 5–200050需要
package_cve_map_languages_enabledboolfalse需要

18.2 guard.yaml(37 个键)

键 类型 / 可取值 默认 重启
sensor.typefalco | tetragonfalco需要
sensor.transportstringunix_socket需要
sensor.socket_pathabs path/run/roamswitch/events.sock需要
sensor.reconnect_interval_msint 100–36000001000需要
policies.on_warning.actionlog_and_notify | isolate_process | isolate_host_alllog_and_notify需要
policies.on_warning.server_actionlog_and_notify | isolate_process | isolate_host_all—需要
policies.on_warning.kill_processboolfalse需要
policies.on_warning.freeze_processboolfalse需要
policies.on_warning.fallback_to_host_isolation_after_retriesint 0–1000—需要
policies.on_error.actionlog_and_notify | isolate_process | isolate_host_allisolate_process需要
policies.on_error.server_actionlog_and_notify | isolate_process | isolate_host_all—需要
policies.on_error.kill_processboolfalse需要
policies.on_error.freeze_processboolfalse需要
policies.on_error.fallback_to_host_isolation_after_retriesint 0–1000—需要
policies.on_critical.actionlog_and_notify | isolate_process | isolate_host_allisolate_process需要
policies.on_critical.server_actionlog_and_notify | isolate_process | isolate_host_all—需要
policies.on_critical.kill_processbooltrue需要
policies.on_critical.freeze_processboolfalse需要
policies.on_critical.fallback_to_host_isolation_after_retriesint 0–10003需要
policies.on_emergency.actionlog_and_notify | isolate_process | isolate_host_allisolate_host_all需要
policies.on_emergency.server_actionlog_and_notify | isolate_process | isolate_host_all—需要
policies.on_emergency.kill_processbooltrue需要
policies.on_emergency.freeze_processboolfalse需要
policies.on_emergency.fallback_to_host_isolation_after_retriesint 0–1000—需要
server_safeguards.allow_established_connectionsbooltrue需要
server_safeguards.maintenance_ssh_portsport list22需要
server_safeguards.whitelist_cidrslist—需要
server_safeguards.whitelist_dns_serverslist—需要
server_safeguards.safety_timer_secsint ≥ 0300需要
adaptive_security.enabledbooltrue需要
adaptive_security.untrusted_network_actions.elevate_falco_profilestring—需要
adaptive_security.untrusted_network_actions.auto_enable_userns_restrictionboolfalse需要
investigation.enabledboolfalse需要
investigation.commandabs path—需要
investigation.argslist—需要
investigation.run_asstring—需要
investigation.timeout_secsint 1–86400180需要

19. Web Shell 与注入代码检测 (Web Rules)

检测 Web 服务器上的 PHP、JavaScript、JSP、ASP Web Shell 和注入代码、伪装成图片的 PHP,以及 .htaccess 滥用(Linux 1.11.23 及以后)。无需配置,会根据 Apache、nginx、Caddy 的配置自动找到文档根目录,并在文件写入并关闭后立即检查。它使用仅通知的 fanotify,因此不会阻止其他进程。还会每 6 小时进行一次定期扫描,不需要 ClamAV。

行为由 /etc/roamswitch/web_rules.conf 决定(root 所有,权限 0644;他人可写的文件会被忽略)。修改后用 sudo roamswitch server restart 使其生效。模板可用 roamswitch web-rules example conf 输出。

键含义(默认值)
quarantine自动隔离级别。off 不隔离,critical 仅隔离 critical,high 隔离 critical 与 high(默认:critical)。在 critical 级别下发现 high 时,只发送通知并触发钩子,不触碰文件。
account_action是否停用被检测文件所有者的登录 shell。off / revoke_shell / lock(默认:off)。仅针对已隔离的 critical 或 high。不会处理 root、UID 低于 account_min_uid 的账户、已登录的用户以及守护进程自身。原 shell 会被记录,可用 sudo roamswitch web-rules unlock-account <用户> 恢复。
account_min_uidaccount_min_uid:账户处置可作用的最小 UID(默认 1000,不能低于 100)。
scan_dirs, auto_docroots, watch, scan_interval_secsscan_dirs(逗号分隔的绝对路径)、auto_docroots(默认 true;设为 false 则不再从 Web 服务器配置自动发现)、watch(默认 true;设为 false 则关闭写入监视,仅保留定期扫描)、scan_interval_secs(默认 21600,最小 3600)。
# /etc/roamswitch/web_rules.conf
quarantine=critical
account_action=off
account_min_uid=1000
#scan_dirs=/srv/sites/a,/srv/sites/b
auto_docroots=true
watch=true
scan_interval_secs=21600

PHP 会话文件(以 sess_ 开头的文件)也通过同一路径检查。保存位置包括 php.ini 和 FPM 池中的 session.save_path、/var/lib/php/sessions、/var/lib/php/session、/tmp、/var/tmp,以及使用 PrivateTmp= 的 php、apache、httpd、nginx 单元的临时文件夹。只读取这些文件夹正下方的文件。如果 session.upload_progress 的标记和起始标签同时出现,则为 php-session-upload-progress-code(critical);只有起始标签则为 php-session-code(high)。

设为 account_action=lock 后,会撤销所检测文件所有者的登录 shell,并通过 nftables(roamswitch_web_account_block 表)阻止该账户的出站通信,因为正在运行的 Web Shell 不会因撤销 shell 而停止。对于在公网地址上监听的账户,只阻止新的出站连接(放行环回)。设为 account_stop_processes=on(默认关闭)后,会用 SIGSTOP 停止该账户的进程(protected_processes 和系统保护对象除外)。用 unlock-account 可以一次性恢复。

检测到后,会通知规则名称和是否已隔离(Telegram、LINE、Webhook)。如果只想检查,请使用 sudo roamswitch web-scan <文件夹>(用 --quarantine 隔离)或 Server TUI 的“工具”界面。自定义规则放在 /etc/roamswitch/rules.d/*.json,检测后脚本是 /etc/roamswitch/hooks/post-detection(只执行 root 所有且安全的脚本,不经过 shell,30 秒后中止)。规则通过每日的仅接收更新来更新。停用 cve_kernel_map_updates_enabled 后,完全不进行通信,使用随附的规则运行。

roamswitch web-rules status 显示当前正在监控的文档根目录的数量和列表。为 0 个时,Web shell 检测什么也没有监控。请在 web_rules.conf 的 scan_dirs 中写入文件夹。反向代理后面的应用,或非标准的 nginx 配置,可能无法自动发现。为 0 个时,启动时也会发出 1 次警告。

20. 运行 AI 智能体的账户(agent_users)

这是在专用账户下运行 AI 代理(Claude Code、Codex CLI 等)时的功能(Linux 1.12.7 及以后)。对应 NIST、NSA 和 CISA 于 2026 年 10 月 16 日发布的 AI 代理事件响应指南(10 项做法)中,可在 1 台服务器上实现的项目。使用专用账户时,代理无法改写 root 的文件和防火墙规则。

由 server.conf 中的 3 个键控制。需要重启才能生效(sudo roamswitch server restart)。

键含义(默认值)
agent_users运行智能体的账户(名称或数字 uid,以逗号分隔,默认为空)。拒绝 root。不存在的名称和没有主目录的账户会在启动时给出警告并被忽略。
agent_egress_allowagent_users 可以连接的目标(默认为空 = 不限制):ADDR、ADDR/PREFIX、ADDR:PORT、ADDR/PREFIX:PORT,IPv6 为 [ADDR]:PORT。不能写名称。只要有一条,就会丢弃这些账户发往其他地方的新出站数据包。像 0.0.0.0/0 这样不带端口的全部放行会被拒绝(0.0.0.0/0:443 可以)。
agent_setup_watch_secs将每个账户的指令文件、技能和 MCP 定义与 root 持有的基准线比对的间隔(秒。默认 300,0 为关闭,30 到 86400)。
# /etc/roamswitch/server.conf
agent_users=agent
agent_egress_allow=10.0.0.5:3128
agent_setup_watch_secs=300

出站允许列表:nftables 的 inet roamswitch_agent_egress(output 钩子,优先级 -145)在目标账户的通信中,只放行环回、已建立的连接和列表中的目的地(带端口的为 TCP 和 UDP),其余的丢弃,并记录日志 rs_agent_egress_drop: (每分钟最多 10 条)。被丢弃的通信每 60 秒收集一次,按账户和目的地每小时通知 1 次。列表按地址匹配,无法按名称限定。可以只允许 1 台代理(agent_egress_allow=10.0.0.5:3128),或按网络范围使用。

由 root 持有的基准线:指令文件(CLAUDE.md、AGENTS.md 等)、技能、MCP 服务器定义的已确认状态,仅以 SHA-256 保存在 /var/lib/roamswitch/agent_setup/<账户>.json(root 所有,0600)中。该账户既不能改写也不能删除。创建和更新请以 root 使用下面的命令,仍有发现项时加上 --accept-with-findings。

sudo roamswitch audit-agent-setup --user agent             # check only
sudo roamswitch audit-agent-setup --user agent --accept    # make this state the baseline

守护进程通过 inotify 在约 1 秒内发现配置文件的变更,并按每 agent_setup_watch_secs 一次的比对补上遗漏。它把主目录及其正下方的工作副本(含 .git、.mcp.json、CLAUDE.md、AGENTS.md 之一的文件夹,最多 50 个)与基准线比较,变更和新增只通知 1 次,并记入事件时间线。没有基准线的账户,会在启动时和每 5 分钟检查一次,并附上创建命令通知(同一账户每 24 小时最多 1 次)。

诱饵凭据:§7.4 的诱饵也会放在 agent_users 各账户的主目录中,每个账户启动一个监视进程。以其他账户运行的智能体无法打开 /root 下的诱饵。

无法做到的事:白名单只针对所列账户的套接字,因此能成为 root 的智能体,或让 root 所有的服务代为连接的途径,无法阻止。UDP 不等待应答,所以即使被丢弃,发送方也不会察觉。Mac 版和 Linux 客户端版没有此功能。

请不要加入供人登录使用的账户。对没有 .ssh/id_rsa 的账户,会放置假的密钥。ssh 会把它当作默认密钥来尝试,因此可能造成误报。

服务以只读方式查看 /home。因此,如果没有添加 ReadWritePaths=-/home/<账户> 的 drop-in,就不会放置诱饵。sudo roamswitch server setup 的步骤13会在确认后写入(/etc/systemd/system/roamswitch-server.service.d/agent-users.conf)。

设置步骤如下。(1) 设置 agent_users。(2) 运行 sudo roamswitch server restart。(3) 用 sudo roamswitch audit-agent-setup --user NAME 检查。(4) 阅读内容,用 --accept 创建基线。(5) 用 roamswitch detection-coverage 确认。在创建基线之前,不会监视该账户的变更。创建之后的变更会在约 1 秒内通知。

检查的位置只有 ~/.claude、~/.codex、~/.cursor、~/.gemini(包含 antigravity-cli)、~/.agents、~/.openclaw,以及主目录下的工作副本。其他位置既不检查,也不检测变更。什么都没有的状态也可以作为基准线。

21. Web 访问防护与 Web 关卡(检测并阻止对标识符的遍历)

在 Web 服务器的访问日志中,发现依次替换受理编号、订单编号、用户 ID 等数字进行查询的行为。使用 AI 的攻击工具会把工作分散到很多 IP 上,因此按 IP 统计次数或查看 User-Agent 都看不出来。这里看的是编号的查询方式,正常用户使用网站时不会出现这种方式。nginx 和 Apache 的访问日志会被自动找到,并在写入的同时读取。

检查以下 4 点。(1) 查询了预留的编号(canary,不会发放)。(2) 同一来源对不存在的编号得到 5 次 404。(3) 同一来源在同一位置查询了 20 种以上的编号。(4) 多个来源按到达顺序遍历编号(满 100 种后识别;此后,查询后续编号的新来源在第一次请求时就会被发现)。如果一个地址背后出现 3 种以上的浏览器(CDN、公司代理、运营商的共享地址),则不会封锁。

行为由 /etc/roamswitch/web_guard.conf(root 所有)决定。默认是 mode=warn(只通知并记录,不封锁任何内容)。修改会在 30 秒内生效。

键含义(默认值)
modemode:off / warn / block(默认:warn)。block 会在 ban_secs 秒内阻断符合条件的来源对 80/443 的新连接。允许列表(whitelist_ips)、网关、DNS、本主机自身,以及能看到 3 种以上浏览器的共享地址不会被阻断。私有地址默认也不阻断(用 ban_private=yes 阻断)。
ban_secs, window_secs, not_found_limit, distinct_limit, ban_privateban_secs(默认 3600)、window_secs(默认 600)、not_found_limit(默认 5)、distinct_limit(默认 20)、ban_private(默认 no)。
canarycanary:写明不会发放的编号范围及其位置(可写任意多行)。例如:canary=/loan/status?receiptNo=2026100090-2026100099、canary=/api/orders/{n}=5000001-5000009。查询了这些编号的来源,在第一次请求时就会被发现。
gate_*gate_budget_floor(默认 30)、gate_budget_factor(默认 3)、gate_learn_secs(默认 3600)、gate_socket(默认 /run/roamswitch/webgate.sock):Web 关卡的设置(见下)。
recon_notify, summary_hourrecon_notify(默认 summary)决定探查网站结构的行为如何通知。summary 是每天一次的汇总,immediate 是每个来源一条,off 是不通知。summary_hour(0 到 23,默认 9)是发送汇总的时刻(服务器的本地时间)。封锁、日志和事件记录不受这两个键影响。
# /etc/roamswitch/web_guard.conf
mode=warn
canary=/loan/status?receiptNo=2026100090-2026100099
#ban_secs=3600
#ban_private=no

检测到对标识符的遍历时会发送通知(Telegram、LINE、Webhook)。每个位置(路径和编号参数)每次检查发一条。通知会写明原因,以及是否已封锁还是仅通知。封锁(mode=block)可用 roamswitch emergency-restore 解除。只想观察时,保持 mode=warn 即可。

Web 网关(roamswitch-webgate)是放在 nginx 前面、只保护接收编号的位置的可选组件。为应对不断更换 IP 的攻击,它为每个位置设定每分钟新编号查询的额度(启动后 1 小时学习正常量,之后为正常最大值每分钟的 3 倍,最低 30)。超过后,对未知编号返回 429,对上面 4 种判定从第 1 次请求起就返回 403。

它只通过 Unix 套接字运行,不访问网络,停止时会放行请求。用 sudo systemctl enable --now roamswitch-webgate 启动,并添加 roamswitch web-gate-config /loan/status 输出的 nginx 配置(此命令不会更改任何内容)。在 mode=warn 期间只做记录。

sudo systemctl enable --now roamswitch-webgate
roamswitch web-gate-config /loan/status --proxy http://127.0.0.1:8080
sudo nginx -t && sudo nginx -s reload

即使关卡停止,nginx 也会放行请求,所以无法察觉它已停止。是否在运行,请用下面的命令确认。关卡每 10 秒更新一次 /run/roamswitch/webgate.status,其中的 ts 落后 60 秒以上时,服务器的守护进程会发出通知。重启后忘记执行 enable 时,也可以用 is-enabled 发现。

systemctl is-active roamswitch-webgate
systemctl is-enabled roamswitch-webgate
sudo cat /run/roamswitch/webgate.status

在本地测试(模拟暴力破解,每秒 5 次)中,按顺序遍历编号的 700 次请求,即使分散到 9 个 IP,也在 100 次时阻断了所有 IP(之后的新 IP 在第 1 次请求时就被阻断)。有网关时,在 30 次时停止。每次更换 IP 并随机查询的攻击,被网关压制在每分钟 30 次(没有网关则无法阻止)。以正常量缓慢持续的攻击无法阻止,根本对策是在应用中按用户授权。用 roamswitch web-id-check 'http://127.0.0.1/loan/status?receiptNo={n}' --start 202610060001 可以确认是否会在未登录的情况下按编号返回内容(只对连续最多 10 个编号发送 GET)。

当 nginx、Apache、PHP-FPM 的工作进程在 5 分钟内 3 次因崩溃信号(SIGSEGV、SIGABRT 等)而终止时,也会发送通知(读取错误日志)。主进程会重新创建工作进程,因此不会被计为服务重启。这是利用漏洞的攻击尝试或程序缺陷的线索。每台服务器每小时最多通知一次,不会停止或封锁任何内容。

探测站点结构的行为,也从同一访问日志中发现(与标识符暴力破解是分开的检测)。对一个来源,在 window_secs(默认 600 秒)内按 5 种理由计数。(1) path_walk:不存在的路径(404)有 12 种以上(含标识符的路径除外)。(2) asset_harvest:不带 Referer 请求 .js、.css 等 40 次以上。(3) api_probe:/api/ 下不同路径出现 401、403、404 共 20 种以上。(4) param_fuzz:同一路径上有 30 种以上不同查询,且超过一半为 4xx。(5) probe_walk:.env、.git 等机密、配置或管理界面路径有 6 种以上,或不同的机密路径有 12 种以上(不论响应)。(5) 用于发现对任何路径都返回 200 的站点上的遍历。

设置写在同一个 /etc/roamswitch/web_guard.conf 中。包括 recon=off|warn|block(默认 warn)、5 个上限(path_walk_limit 等,3 到 10000,probe_walk_limit 的默认值为 6),以及排除项 exempt_path=/health(前缀匹配)和 exempt_ua=uptimerobot(部分匹配,小写,3 个字符以上)。仅在 mode=block 且 recon=block 时才会阻断,能看到 3 种以上浏览器的共享地址不会被阻断。

通知默认是每天一次的汇总。在 summary_hour(默认 9 点,服务器本地时间)之后的第一次检查时,发送来源数量、检测和阻断的数量,以及次数最多的 10 个来源(没有检测的日子不发送)。recon_notify=immediate 按来源逐个通知,recon_notify=off 不通知。阻断、日志、事件记录不变。统计保存在 /var/lib/roamswitch/web_recon_summary.json(来源最多 500 个)。搜索引擎和监控的巡访,用 exempt_ua 或 exempt_path 排除。Web 网关看不到 Referer 和响应码,所以不检查这 4 项。

在本地测试中,我们让 Docker 里的 nginx 写出的真实访问日志,经过实际的解析器和防护。用 python-requests 巡回的来源,在第 12 个 404 时被识别为 path_walk,在第 40 个 JavaScript(累计第 70 个)时被识别为 asset_harvest,在第 20 个 API(累计第 110 个)时被识别为 api_probe,在第 30 个查询(累计第 145 个)时被识别为 param_fuzz。浏览器的正常使用 120 条(页面 20 条、带 Referer 的 JavaScript 60 条、搜索 40 条)中,一条都没有检出。测得的只有这个范围。

是否适合启用封锁,可用 roamswitch web-guard-check [--hours N] 检查(root。不会更改任何内容)。它会根据访问日志和 Web 服务器配置,检查来自私有地址或共享地址的比例、是否有还原访问者地址的设置(RemoteIPHeader、real_ip_header 与 set_real_ip_from)等。结果分为“适合”“仅部分有效”“不适合”“无法判断(请求不足 200 条)”,不适合时退出码为 1。如果 CDN 或代理不传递访问者的地址,所有人都会显示为同一个地址,封锁会拦住很多人。成功(2xx、304)不足 5 条中 1 条的地址,即使更换了 User-Agent,也不视为共享。

仅通知的警报(每日汇总除外),只有在当前设置与此检查结果不一致时才附上指引:封锁关闭而检查认为适合时,说明如何开启封锁;封锁开启而检查认为不适合时,说明如何停止封锁(检查结果由日志算出,并沿用 6 小时)。其余情况只写明未封锁。已封锁的地址用 roamswitch unban <IP>(--all 全部解除)解除,同时解除 SSH 防护和 Web 访问防护的封锁。

22. 随机数记录(prn_record,有期限)

勒索软件在受害机器内部利用操作系统的随机数生成文件密钥。设为 prn_record=true 后,会为 getrandom 返回的随机数以及对 /dev/urandom、/dev/random 的读取所返回的随机数(8 字节以上,最多前 128 字节)设置期限并记录。这是解密工具(如 KDDI Research 的 Memento)重新生成密钥的材料。RoamSwitch 不进行解密。默认关闭,Mac 版和 Linux 客户端版中没有此功能。

键含义(默认值)
prn_recordprn_record: 记录随机数(默认 false)。关闭后,守护进程启动时会删除已记录的内容。
prn_retention_hoursprn_retention_hours: 记录保留的时长(1 到 168 小时,默认 24)。
prn_max_mibprn_max_mib: 记录可使用的磁盘上限(MiB,16 到 4096,默认 256)。
# /etc/roamswitch/server.conf
prn_record=true
prn_retention_hours=24
prn_max_mib=256

记录不会超过期限保留。超过 prn_retention_hours 的记录,每 10 分钟按文件用零覆盖后删除(最多延迟 10 分钟)。超过 prn_max_mib 时从旧的开始删除,因此保留时间只会变短,不会变长。超出范围的值会被拒绝,时钟出错也不会延长期限。守护进程停止期间,/usr/lib/tmpfiles.d/roamswitch-prn.conf 每天一次删除 7 天(最长保留时间)没有写入的文件(systemd 247 及以后)。

通过对内核随机数函数(get_random_bytes_user、urandom_read_iter、random_read_iter)使用 fentry/fexit 进行记录,因此不会给其他读取和系统调用带来负载。实测中,100 万次读取的差异在误差范围内,一条记录约 1.2 微秒、约 67 字节(Linux 7.0、aarch64)。在无法使用 fentry 的内核(x86-64 低于 5.5、arm64 低于 6.0)等情况下,会附上原因进行通知。设置 RS_PRN_HOOK=syscall 后,可以用 tracepoint 记录,代价是所有系统调用会稍微变慢。

记录存放在 /var/lib/roamswitch/prn/(0700,文件 0600,root 所有),不会出现在通知、证据包、MCP 和事件转发中。有些看不到:不经系统调用就返回随机数的路径(glibc 2.41 及以上通过 vDSO 调用 getrandom() 的环境),以及在用户空间执行的 RDRAND。在 x86-64 上,内核参数 vdso=0 可以关闭 vDSO 路径。

状态可用 sudo roamswitch-prn-recorder status 查看。sudo roamswitch-prn-recorder export --output FILE [--since-hours N] [--pid PID] 会把期限内的记录以 memento.prn/v1 的 JSON Lines 格式写入新的 0600 文件。期限不适用于导出的文件,用完后请安全删除。sudo roamswitch-prn-recorder purge 会立即删除所有记录。

记录中也包含该机器建立的 TLS 和 SSH 会话的秘密。一旦 root 被夺取,期限内通信的密钥可能被重建。保留时间和容量上限请只设为所需。

23. 随附的独立工具(AccessScope、PersonalSOC、PathScope)

Server Edition 的 deb、rpm 会把 3 个独立于 RoamSwitch 的工具(AccessScope、PersonalSOC、PathScope)的命令安装到 /usr/bin/。不含界面应用和 WebKitGTK。许可证为 Apache License 2.0,不适用 RoamSwitch 的使用许可协议(EULA)。更新随 RoamSwitch 安装包的更新一起进行。

命令功能
accessscope从 Web 服务器和 SSH 的访问日志中找出攻击尝试,并附上作为依据的日志行。只读,诊断既不使用 LLM,也不使用网络。用 accessscope discover 列出日志位置,用 accessscope scan --auto 诊断,用 accessscope fleet 汇总多台主机。详情请参阅 AccessScope 操作手册。
personalsoc检查本主机的日志和 RoamSwitch(MCP)的检测结果,生成检出列表或报告。像 sudo personalsoc scan 这样以 root 身份运行。personalsoc scan --report 生成 Markdown 报告,--format json 和 --format sarif 是面向机器的输出。--fail-on high 在出现 high 级检出时以退出码 3 结束。只有加上 --llm 时,摘要和依据行等才会传给所选的 LLM 命令(不属于 Zero Telemetry 的范围)。详情请参阅 PersonalSOC 操作手册。
pathscope找出从普通用户到达 root 和敏感数据的路径,并给出修复顺序。只读,不调用 LLM。pathscope 分析从当前用户到 root 的路径。pathscope --baseline=上次.json --fail-on=new 在路径增加时以退出码 1 结束。sudo pathscope --check-agent-users 一并分析 agent_users 中的账户。详情请参阅 PathScope 操作手册。

界面应用(accessscope-app、personalsoc-app、pathscope-gui)只包含在客户端版安装包中。

← 服务器版白皮书 前往 Linux 版安装页面 →