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 的自主紧急通报”为核心功能。
除软件包更新外,默认的对外通信只有匿名获取带签名的数据(
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 一节。系统要求
- 支持的发行版:Ubuntu 22.04 / 24.04 LTS、Debian 12+、AlmaLinux / Rocky Linux / RHEL 9+、Fedora 39+、openSUSE Leap 15.5+、Raspberry Pi OS(64 位)
- 架构:
x86_64(amd64) 或aarch64(arm64) - Kernel:Linux 5.10+(推荐
nftables、cgroups v2、eBPF BTF) - Footprint:20–30 MB 驻留内存,空闲/正常工作负载期间 <0.1% CPU
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
- 端口:分别以逗号分隔输入 SSH 维护端口(默认
22)和公开服务端口(默认80,443)。 - 指定维护来源 IP:指定 SSH 跳板机或监控源的 IP / CIDR(例如
203.0.113.50/32)。向导中为必填项,不能留空。若要允许所有 IP 的 SSH,请输入ANYWHERE(此时隔离期间管理用 SSH 也会向全世界开放)。 - 通知渠道设置:分别启用 Telegram Bot、LINE Messaging API、通用 Webhook(Slack / Discord / Teams)。
- eBPF 重大事件时的响应:选择
isolate(隔离主机)/freeze(冻结该进程)/alert_only(仅通知)。保存后会确认发送测试通知并重启服务。 - 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。 - File Scan Guard 设置:设置是否为邮件中继、共享文件夹、上传目标启用病毒扫描(§13)及目标目录。可选功能,默认关闭。
- Resource Guard 设置:设置是否启用检测网络公开服务持续 RSS 增长(内存泄漏/DoS)或崩溃循环的资源枯竭防护。
- 常驻核心防护说明:显示无需通过向导、始终生效的核心防护功能列表,如入站默认拒绝、FIM、eBPF 集成等(无需输入)。
- 调查代理协作(investigation)设置:设置是否将 eBPF 重大事件,或关键路径 FIM/依赖锁文件篡改检测(均为仅通知判定时)的初步调查自动委托给外部 AI 代理 CLI(Claude Code / agy / Codex CLI / OpenCode,或自定义命令)(§10.1)。默认关闭。
向导接下来的步骤会在提问之前先检查当前状况,并告知缺少的内容。
- 步骤7(eBPF 严重事件时的动作):未安装 Falco 或 Tetragon 时,不会提问,而是显示安装方法。没有传感器,就收不到 eBPF 的严重事件。
- 步骤9(File Scan Guard):先询问要检查的目录。留空时会显示“不检查任何内容”。不存在的位置和服务无法写入的位置会给出警告。检查的只有指定的目录。
- 步骤11(常驻的核心防护):根据当前设置值,列出默认生效的防护。同时显示
web_rules.conf和web_guard.conf的位置。 - 步骤13(AI 智能体账户):显示诱饵、通信限制和基准线的说明。对管理员账户给出警告。先检查,读过内容之后,再询问是否批准基准线。批准的默认值是
N,不会默默批准(§20)。 - 通知渠道:没有通知渠道,或已启用但 token、收件目标、URL 为空时,会显示警告。对能够送达的渠道,会发送测试通知。
向导的最后会显示用于确认的命令。服务器版不能使用 roamswitch guards,请用下面的命令确认。
sudo roamswitch status --server
sudo roamswitch doctor
sudo roamswitch detection-coverage
sudo roamswitch server config show
-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 配备了多重防护措施。
- 已建立/相关无条件通过:在规则重新加载期间,活动会话永远不会被删除。
- Air-Gap 隔离时保留 SSH:
preserve_ssh_on_isolation = true时,隔离期间维护 SSH 端口和管理来源 IP(whitelist_ips)的管理通道仍然畅通,无需到现场即可恢复。其他已建立的连接(C2、数据外泄、反向 shell)会被切断。若管理来源为空,维护 SSH 端口会接受所有来源的新连接,因此启动时会发出警告。preserve_ssh_on_isolation=false时,SSH 也会被切断。1.10.4 及之前版本的缺陷已在 1.10.5 中修复。 - Atomic nftables 加载并回滚:规则语法错误立即触发零停机回滚到之前已验证的规则集。
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(无需额外的权限设置)。
- 通过软件包自带的
/etc/falco/config.d/99-roamswitch-optimized.yaml,警报不写入磁盘,而是直接流式传给守护进程。由于该配置用socat把 Falco 的输出交给套接字,Server Edition 的 deb / rpm 会把socat作为推荐软件包(Recommends)安装(不使用 Falco 时不需要)。 - 通过按日轮转和压缩保留(
/etc/logrotate.d/roamswitch-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)监控基础设施健康状况和状态。
诊断结果中如果有外部人员可以改写的字符串(日志文本等),会附上“不可信的外部数据”的提示。若有类似对 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)的预设,或任意命令。再次运行时,会选中已保存的设置。
因此不能以 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 种。
- syslog(
forward_syslog_url:udp://host:514/tcp://host:port/tls://host:port):RFC 5424 或 CEF(forward_syslog_format)。TCP/TLS 的分隔方式为octet(RFC 6587,默认)或lf。CA 可用forward_tls_ca_file指定,TLS 通过openssl s_client发送。 - JSON Lines 文件(
forward_file_path):每行一个事件。按forward_file_max_mb(默认 50)和forward_file_keep(默认 5)轮转。默认权限是只有 root 可读的0600。在server.conf的forward_file_group中写入组名后,权限变为0640(删除后恢复0600),该组即可读取。不要让该组对父目录有写权限。不能通过config.json指定。 - 结构化 Webhook(
forward_webhook_url):以 POST 发送 JSON,并把用密钥(forward_webhook_secret,或指向0600文件的forward_webhook_secret_file)生成的 HMAC-SHA256 签名放在X-RoamSwitch-Signature中。发送使用系统的curl,密钥不会放入参数。
未能发送的事件(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 …命令)。以 root 启动时可以操作,影响较大的操作会先显示内容,最危险的操作要求输入yes。它不会启动守护进程,自身也不会打开网络套接字。 - 界面(用数字键切换):
1仪表盘 /2防御 /3事件(禁止和解除 SSH 暴力破解等)/4通知与转发 /5Sensor /6设置 /7服务 /8工具 /9日志审计 /0信息与帮助。?显示按键列表,L切换 10 种语言,r重新加载,q退出(有未保存的更改时会确认)。 - 设置编辑器:由 schema 生成的编辑器,可在校验类型、范围和枚举值的同时,编辑
server.conf与guard.yaml的全部 168 个键(§18)。保存前可查看差异(密钥会隐藏),保存时先创建带时间戳的备份,再原子写入。需要重启的键,以及设错会失去管理路径或削弱防御的键,会显示相应提示。调查代理集成(§10.1)的设置也可以在选择预设并预览后写入。
启动:
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 个键)
| 键 | 类型 / 可取值 | 默认 | 重启 |
|---|---|---|---|
language | system | ja | en | zh-hans | zh-hant | ko | de | fr | es | it | pt | ja | 需要 |
ssh_ports | port list | 22 | 需要 |
allowed_ports | port list | 80,443 | 需要 |
allowed_udp_ports | port list | — | 需要 |
whitelist_ips | list | — | 需要 |
preserve_ssh_on_isolation | bool | true | 需要 |
telegram_enabled | bool | false | 需要 |
telegram_bot_token | string | — | 需要 |
telegram_chat_id | string | — | 需要 |
line_enabled | bool | false | 需要 |
line_channel_access_token | string | — | 需要 |
line_user_id | string | — | 需要 |
webhook_enabled | bool | false | 需要 |
webhook_url | URL | — | 需要 |
webhook_block_private_addresses | bool | false | 需要 |
webhook_allow_addresses | CIDR list | — | 需要 |
action_on_critical | isolate | freeze | alert_only | isolate | 需要 |
ebpf_socket_path | abs path | /run/roamswitch/events.sock | 需要 |
ebpf_heartbeat_interval_secs | 0 (off) | int 60–86400 | 600 | 需要 |
isolation_hard_cap_secs | int ≥ 0 | 3600 | 需要 |
protected_processes | list | — | 需要 |
fim_check_interval_secs | int ≥ 10 | 300 | 需要 |
fim_intrusion_context_enabled | bool | true | 需要 |
protect_docker_ports | bool | true | 需要 |
dns_sinkhole_enabled | bool | false | 需要 |
dns_sinkhole_provider | quad9 | cloudflare | adguard | cleanbrowsing | quad9 | 需要 |
egress_ip_blocklist_enabled | bool | true | 需要 |
metadata_watch_enabled | bool | true | 需要 |
metadata_watch_allow_users | list | — | 需要 |
cve_kernel_map_updates_enabled | bool | true | 需要 |
clamav_enabled | bool | false | 需要 |
clamav_scan_dirs | abs path list | — | 需要 |
clamav_scan_interval_secs | int ≥ 3600 | 86400 | 需要 |
clamav_freshclam_interval_secs | int ≥ 1800 | 7200 | 需要 |
lockfile_watch_dirs | abs path list | — | 需要 |
domain_check_domains | domain list (max 5) | — | 需要 |
npm_audit_signatures_enabled | bool | false | 需要 |
log_audit_enabled | bool | true | 需要 |
log_audit_interval_secs | int ≥ 300 | 1800 | 需要 |
resource_guard_enabled | bool | true | 需要 |
resource_guard_rss_sample_interval_secs | int ≥ 10 | 60 | 需要 |
resource_guard_rss_window_secs | int ≥ 300 | 1800 | 需要 |
resource_guard_rss_min_samples | int ≥ 3 | 10 | 需要 |
resource_guard_rss_min_growth_pct | int ≥ 10 | 50 | 需要 |
resource_guard_rss_recovery_drop_pct | int ≥ 1 | 10 | 需要 |
resource_guard_rss_min_kb | int ≥ 0 | 20000 | 需要 |
resource_guard_crash_loop_window_secs | int ≥ 60 | 300 | 需要 |
resource_guard_crash_loop_min_restarts | int ≥ 2 | 3 | 需要 |
resource_guard_correlation_window_secs | int ≥ 60 | 600 | 需要 |
resource_guard_zombie_min_count | int ≥ 0 | 20 | 需要 |
resource_guard_load_min_normalized | float ≥ 0.0 | 0.5 | 需要 |
resource_guard_load_enabled | bool | true | 需要 |
resource_guard_cpu_enabled | bool | true | 需要 |
resource_guard_cpu_sample_interval_secs | int ≥ 0 | 60 | 需要 |
resource_guard_cpu_window_secs | int ≥ 0 | 600 | 需要 |
resource_guard_cpu_min_samples | int ≥ 0 | 8 | 需要 |
resource_guard_cpu_pct_threshold | float 0.0–1000.0 | 80.0 | 需要 |
container_exec_guard_enabled | bool | true | 需要 |
port_scan_detect_enabled | bool | true | 需要 |
port_scan_detect_min_distinct_ports | int ≥ 0 | 15 | 需要 |
port_scan_detect_window_secs | int ≥ 0 | 300 | 需要 |
port_scan_block_enabled | bool | true | 需要 |
port_scan_block_duration_secs | int ≥ 0 | 600 | 需要 |
ssh_guard_enabled | bool | true | 需要 |
ssh_guard_block_enabled | bool | true | 需要 |
ssh_guard_max_failures | int 2–1000 | 6 | 需要 |
ssh_guard_window_secs | int 10–86400 | 600 | 需要 |
ssh_guard_ban_secs | int 60–2592000 | 3600 | 需要 |
ssh_guard_ban_max_secs | int 60–31536000 | 604800 | 需要 |
ssh_guard_allow | IP/CIDR list | — | 需要 |
ssh_guard_log_source | auto | journal | abs path | auto | 需要 |
ssh_guard_yield_to_fail2ban | bool | true | 需要 |
ssh_guard_trust_key_days | int 0–3650 | 30 | 需要 |
ssh_allow_only_enabled | bool | false | 不需要(约 30 秒) |
ssh_allow_only_sources | IP/CIDR list | — | 不需要(约 30 秒) |
agent_users | name list | — | 需要 |
agent_egress_allow | addr[:port] list | — | 需要 |
agent_setup_watch_secs | int 0, 30–86400 | 300 | 需要 |
prn_record | bool | false | 需要 |
prn_retention_hours | int 1–168 | 24 | 需要 |
prn_max_mib | int 16–4096 | 256 | 需要 |
dns_tunnel_detect_enabled | bool | true | 需要 |
reverse_shell_watch_enabled | bool | true | 需要 |
reverse_shell_watch_include_private | bool | false | 需要 |
reverse_shell_watch_notify_only | bool | false | 需要 |
suid_watch_enabled | bool | true | 需要 |
suid_watch_interval_secs | 60 – 86400 | 600 | 需要 |
log_tamper_watch_enabled | bool | true | 需要 |
sensor_pairing_enabled | bool | false | 需要 |
sensor_colocated | bool | false | 需要 |
forward_enabled | bool | false | 需要 |
forward_syslog_url | URL | — | 需要 |
forward_syslog_format | rfc5424 | cef | rfc5424 | 需要 |
forward_syslog_framing | octet | lf | octet | 需要 |
forward_tls_ca_file | abs path | — | 需要 |
forward_file_path | abs path | — | 需要 |
forward_file_max_mb | int 1–10000 | 50 | 需要 |
forward_file_keep | int 1–100 | 5 | 需要 |
forward_file_group | 组名 | gid | — | 需要 |
forward_webhook_url | URL | — | 需要 |
forward_webhook_secret | string | — | 需要 |
forward_webhook_secret_file | abs path | — | 需要 |
forward_webhook_block_private_addresses | bool | false | 需要 |
forward_webhook_allow_addresses | CIDR list | — | 需要 |
forward_min_severity | info | low | medium | high | critical | low | 需要 |
forward_queue_max_mb | int 1–10000 | 20 | 需要 |
forward_queue_max_age_hours | int 1–8760 | 72 | 需要 |
exec_recorder_enabled | bool | true | 需要 |
exec_recorder_retention_mb | int 1–100000 | 200 | 需要 |
exec_recorder_retention_days | int 1–3650 | 14 | 需要 |
exec_recorder_hash_chain | bool | true | 需要 |
exec_recorder_hash_exe | bool | true | 需要 |
exec_recorder_cpu_budget_pct | int 1–50 | 3 | 需要 |
exec_rules_enabled | bool | true | 需要 |
exec_rules_disabled | string | — | 需要 |
exec_rule_service_users | string | — | 需要 |
exec_rule_window_secs | int 5–3600 | 120 | 需要 |
exec_rules_isolation_optin | bool | false | 需要 |
config_regression_notice_enabled | bool | true | 需要 |
honeytokens_enabled | bool | true | 需要 |
honeytokens_home | abs path | /root | 需要 |
harden_userns_enabled | bool | true | 需要 |
dns_tunnel_entropy_allowlist | list | — | 需要 |
fleet_forwarding_allowed_hosts | list | — | 需要 |
fleet_forwarding_allow_plaintext | bool | false | 需要 |
entropy_watch_enabled | bool | true | 需要 |
entropy_watch_dirs | list (max 32) | — | 需要 |
entropy_watch_freeze | bool | false | 需要 |
entropy_docroot_action | notify | freeze_writer | notify | 需要 |
entropy_watch_max_files_per_sec | int 5–2000 | 50 | 需要 |
package_cve_map_languages_enabled | bool | false | 需要 |
18.2 guard.yaml(37 个键)
| 键 | 类型 / 可取值 | 默认 | 重启 |
|---|---|---|---|
sensor.type | falco | tetragon | falco | 需要 |
sensor.transport | string | unix_socket | 需要 |
sensor.socket_path | abs path | /run/roamswitch/events.sock | 需要 |
sensor.reconnect_interval_ms | int 100–3600000 | 1000 | 需要 |
policies.on_warning.action | log_and_notify | isolate_process | isolate_host_all | log_and_notify | 需要 |
policies.on_warning.server_action | log_and_notify | isolate_process | isolate_host_all | — | 需要 |
policies.on_warning.kill_process | bool | false | 需要 |
policies.on_warning.freeze_process | bool | false | 需要 |
policies.on_warning.fallback_to_host_isolation_after_retries | int 0–1000 | — | 需要 |
policies.on_error.action | log_and_notify | isolate_process | isolate_host_all | isolate_process | 需要 |
policies.on_error.server_action | log_and_notify | isolate_process | isolate_host_all | — | 需要 |
policies.on_error.kill_process | bool | false | 需要 |
policies.on_error.freeze_process | bool | false | 需要 |
policies.on_error.fallback_to_host_isolation_after_retries | int 0–1000 | — | 需要 |
policies.on_critical.action | log_and_notify | isolate_process | isolate_host_all | isolate_process | 需要 |
policies.on_critical.server_action | log_and_notify | isolate_process | isolate_host_all | — | 需要 |
policies.on_critical.kill_process | bool | true | 需要 |
policies.on_critical.freeze_process | bool | false | 需要 |
policies.on_critical.fallback_to_host_isolation_after_retries | int 0–1000 | 3 | 需要 |
policies.on_emergency.action | log_and_notify | isolate_process | isolate_host_all | isolate_host_all | 需要 |
policies.on_emergency.server_action | log_and_notify | isolate_process | isolate_host_all | — | 需要 |
policies.on_emergency.kill_process | bool | true | 需要 |
policies.on_emergency.freeze_process | bool | false | 需要 |
policies.on_emergency.fallback_to_host_isolation_after_retries | int 0–1000 | — | 需要 |
server_safeguards.allow_established_connections | bool | true | 需要 |
server_safeguards.maintenance_ssh_ports | port list | 22 | 需要 |
server_safeguards.whitelist_cidrs | list | — | 需要 |
server_safeguards.whitelist_dns_servers | list | — | 需要 |
server_safeguards.safety_timer_secs | int ≥ 0 | 300 | 需要 |
adaptive_security.enabled | bool | true | 需要 |
adaptive_security.untrusted_network_actions.elevate_falco_profile | string | — | 需要 |
adaptive_security.untrusted_network_actions.auto_enable_userns_restriction | bool | false | 需要 |
investigation.enabled | bool | false | 需要 |
investigation.command | abs path | — | 需要 |
investigation.args | list | — | 需要 |
investigation.run_as | string | — | 需要 |
investigation.timeout_secs | int 1–86400 | 180 | 需要 |
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_uid | account_min_uid:账户处置可作用的最小 UID(默认 1000,不能低于 100)。 |
scan_dirs, auto_docroots, watch, scan_interval_secs | scan_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_allow | agent_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 秒内生效。
| 键 | 含义(默认值) |
|---|---|
mode | mode: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_private | ban_secs(默认 3600)、window_secs(默认 600)、not_found_limit(默认 5)、distinct_limit(默认 20)、ban_private(默认 no)。 |
canary | canary:写明不会发放的编号范围及其位置(可写任意多行)。例如: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_hour | recon_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_record | prn_record: 记录随机数(默认 false)。关闭后,守护进程启动时会删除已记录的内容。 |
prn_retention_hours | prn_retention_hours: 记录保留的时长(1 到 168 小时,默认 24)。 |
prn_max_mib | prn_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)只包含在客户端版安装包中。