将 RoamSwitch 的诊断能力直接带入你自己的 Mac / Linux 应用
RoamSwitchKit(Mac)和 roamswitch-linux-kit(Linux)是免费的开源客户端,可让 Swift / Rust 代码直接读取 RoamSwitch 本体计算出的安全诊断结果。无需自己编写 ARP 监视或端口扫描,就能把“当前网络是否安全”集成到自己的应用中。
🔒 为什么安全
- 不更改设置:没有任何更改设置、防御或端口的 API。只有 auditSecurityLogs 和 activeVulnScan 更新自身记录时才会写入。
- 完全本地:启动随附的二进制文件,仅通过标准输入输出通信。不发送遥测数据。与外部通信的只有默认禁用的 run_npm_audit_signatures(npm 注册表),其余都是 127.0.0.1 和对网关的 ping。
- 免费开源:MIT 许可证。
在套件管理器中添加一行
只需添加到 Package.swift 的 dependencies 中即可。前提条件是 macOS 12+、Swift 5.9+,并已安装 RoamSwitch 1.3.0 或更高版本。
dependencies: [
.package(url: "https://github.com/lafine1211/RoamSwitchKit.git", from: "1.0.0")
]
只需添加到 Cargo.toml 的 dependencies 中即可。前提是已安装稳定版 Rust(2021 edition、tokio 异步运行时),以及包含 roamswitch-mcp 二进制文件的 RoamSwitch for Linux。
[dependencies]
roamswitch-linux-kit = { git = "https://github.com/lafine1211/roamswitch-linux-kit", tag = "v0.1.0" }
通过简单方法获取诊断结果
import RoamSwitchKit
let client = try RoamSwitchClient()
let report = try await client.securityReport()
print(report.score, report.grade)
let ports = try await client.exposedPorts()
for port in ports.ports where port.overallRisk == "high" {
print(port.processName, port.port)
}
let status = try await client.guardStatus()
print(status.activeSecurityLevelLabel, status.isCurrentNetworkTrusted)
let urlReport = try await client.auditURLSafety(url: "https://apple.com.login-verify.xyz")
print(urlReport.score, urlReport.riskLevel) // e.g. 20, "dangerous"
use roamswitch_linux_kit::RoamSwitchClient;
let client = RoamSwitchClient::new(None, None)?;
let report = client.security_report().await?;
println!("{} ({})", report.score, report.grade);
let ports = client.exposed_ports(false).await?;
for port in ports.ports.iter().filter(|p| p.overall_risk.as_deref() == Some("high")) {
println!("{} {}", port.process_name, port.port);
}
let status = client.guard_status().await?;
println!("{} {}", status.active_security_level_label, status.is_current_network_trusted);
let url_report = client.audit_url_safety("https://apple.com.login-verify.xyz").await?;
println!("{} {}", url_report.score, url_report.risk_level); // e.g. 20, "dangerous"
方法
securityReport()
对 FileVault、SIP、Gatekeeper、对外开放的端口等 23 项进行综合诊断,获取评分和改进建议。
exposedPorts(includeLocalOnly:)
列出所有监听中的端口,并获取对外开放端口的审计结果,其中包括是否为已知的危险服务(Redis/MongoDB 等,或 Ollama/LM Studio 等本地 AI 推理服务器)的判定。在 Mac 上,会对每个开放端口向 127.0.0.1 发送 1 次 HTTP GET,并检查响应头。
guardStatus()
获取未知端口自动阻断、ARP 欺骗自动应对、USB 存储守卫等各个守卫的启用状态,以及当前的保护级别。
auditURLSafety(url:)
传入可疑的邮件链接或短网址,即可仅在设备内(Zero Telemetry)分析网络钓鱼诈骗、Unicode 同形字伪装、冒充知名品牌的子域名和高风险 TLD,并给出分数。
其他方法
| 方法 | 概要 |
|---|---|
auditSecurityLogs(hours:) | 汇总最近的安全日志(Sudo 认证失败、SSH 暴力破解、防火墙阻断等;Mac 还包括 Gatekeeper 和 XProtect,Linux 还包括 AppArmor 和 ClamAV),并将 API 密钥、令牌等敏感信息遮蔽后返回。同时附带新模式和频率异常(统计性尖峰)的检测结果。在 Linux 上无法读取 journal 时,不会把 0 条当作“什么都没发生”,而是将 journalReadComplete 设为 false,并在 journalError 中写入原因。 |
activeVulnScan() | 仅以 127.0.0.1 为对象的非破坏性漏洞验证。由于它是会发送网络请求的工具,默认禁用。在 Mac 上还会列出每项检查的副作用(probesRun 中的 sideEffects,如向 1 个端口发送超过 5 个请求等)。发现项会区分已确认的(confirmed)和仅版本落在范围内的(version_range_match)。 |
packageCveScan() | 将已安装的软件包(Homebrew / dpkg、dnf 等)与本地 CVE 映射进行比对。不进行网络通信。如果无法获取列表,则将 complete 设为 false。Ubuntu(20.04~26.04)只比对有修复版本的 CVSS 7.0 及以上的条目,因此“无匹配”并不意味着没有 CVE。Mac 按严重程度和 EPSS(epss)的顺序排列。对于人工接受的检出,返回数量(acceptance),而接受操作无法通过 MCP 进行。 |
packageCveScanLanguages(watchedFolders:) | 将 npm、PyPI、crates.io 等的依赖锁定文件与同一份本地 CVE 映射进行比对。完全不进行网络通信。 |
canaryStatus() | 返回勒索软件诱饵文件(Canary)的部署状态,以及最近 50 条检测事件。 |
portAnomalyIncidents() | 返回端口异常守卫的基线获取情况、正在自动阻断的端口,以及最近最多 50 条事件。正在自动阻断的端口是没有时间的当前状态,与带时间的事件历史是两回事。这一区别写在响应的注释字段中。 |
runtimeThreatStatus() | 返回是否发生了由 XProtect 恶意软件检测触发的 Air-Gap 隔离,以及触发它的事件。调查 Air-Gap 的原因时,首先使用这个工具。 |
notificationHistory() | 返回 RoamSwitch 发送的通知(安全日志审计异常、ClickFix 检测等)历史记录,最近1周、最新在前。 |
各返回类型的字段定义以原始 Swift 类型声明的形式收录于 GitHub 上的 README 与 AGENTS.md。
security_report()
对 LUKS/dm-crypt 磁盘加密、UEFI Secure Boot、对外开放的端口等 31 项进行综合诊断,获取评分和改进建议。
exposed_ports(include_local_only)
列出所有监听中的端口,并获取对外开放端口的审计结果,其中包括是否为已知的危险服务(Redis/MongoDB 等,或 Ollama/LM Studio 等本地 AI 推理服务器)的判定。在 Mac 上,会对每个开放端口向 127.0.0.1 发送 1 次 HTTP GET,并检查响应头。
guard_status()
获取未知端口自动阻断、ARP 欺骗自动应对、USB 存储守卫等各个守卫的启用状态,以及当前的保护级别。
audit_url_safety(url)
传入可疑的邮件链接或短网址,即可仅在设备内(Zero Telemetry)分析网络钓鱼诈骗、Unicode 同形字伪装、冒充知名品牌的子域名和高风险 TLD,并给出分数。
其他方法
| 方法 | 概要 |
|---|---|
server_security_report() | 以服务器版的 42 项配置(内核加固、容器隔离、内核 CVE 暴露、eBPF LSM)执行综合诊断。 |
run_active_vuln_scan() | 仅以 127.0.0.1 为对象的非破坏性漏洞验证。由于它是会发送网络请求的工具,默认禁用。在 Mac 上还会列出每项检查的副作用(probesRun 中的 sideEffects,如向 1 个端口发送超过 5 个请求等)。发现项会区分已确认的(confirmed)和仅版本落在范围内的(version_range_match)。 |
audit_secrets(text) | 从文本、文件或目录中检测泄露的 API Key 与私钥(检出值在输出时已脱敏)。 |
audit_security_logs(hours) | 汇总最近的安全日志(Sudo 认证失败、SSH 暴力破解、防火墙阻断等;Mac 还包括 Gatekeeper 和 XProtect,Linux 还包括 AppArmor 和 ClamAV),并将 API 密钥、令牌等敏感信息遮蔽后返回。同时附带新模式和频率异常(统计性尖峰)的检测结果。在 Linux 上无法读取 journal 时,不会把 0 条当作“什么都没发生”,而是将 journalReadComplete 设为 false,并在 journalError 中写入原因。 |
get_app_help(query, topic) | 在设备内检索汇总了 RoamSwitch 全部功能的规格、内部运作、全部通知消息和故障排查的官方知识库,并返回解说和建议。 |
quarantine_status() | 返回恶意软件隔离 Vault 的内容(原始路径、检出的威胁名称、隔离时间与大小)。 |
canary_status() | 返回勒索软件诱饵文件(Canary)的部署状态,以及最近 50 条检测事件。 |
package_cve_scan() | 将已安装的软件包(Homebrew / dpkg、dnf 等)与本地 CVE 映射进行比对。不进行网络通信。如果无法获取列表,则将 complete 设为 false。Ubuntu(20.04~26.04)只比对有修复版本的 CVSS 7.0 及以上的条目,因此“无匹配”并不意味着没有 CVE。Mac 按严重程度和 EPSS(epss)的顺序排列。对于人工接受的检出,返回数量(acceptance),而接受操作无法通过 MCP 进行。 |
package_cve_scan_languages(watched_folders) | 将 npm、PyPI、crates.io 等的依赖锁定文件与同一份本地 CVE 映射进行比对。完全不进行网络通信。 |
verify_fim() | 对重要系统文件重新计算哈希,并与基线比较以确认是否被篡改。以 root 运行时,结果会增加 recentIntrusionContext。对于最近的每次变更,其中包含进行变更的进程,以及该进程所属的 SSH 登录(或未能查明的原因)。 |
get_port_anomaly_incidents() | 返回端口异常守卫的基线获取情况、正在自动阻断的端口,以及最近最多 50 条事件。正在自动阻断的端口是没有时间的当前状态,与带时间的事件历史是两回事。这一区别写在响应的注释字段中。 |
get_ebpf_incidents() | 返回 eBPF 运行时守卫当前的隔离状态,以及触发原因的事件历史。在 Server Edition 中,每条记录会增加从检测到处置的时间(毫秒,detect_to_receive_ms、receive_to_action_ms、detect_to_action_ms),同时也返回 Falco 心跳的状态(heartbeat)。 |
返回 SSH 暴力破解防护(Server Edition,以及 sshd 正在运行的 Client Edition)的状态和记录的 get_ssh_guard_incidents(),存在于 RoamSwitch 内部的 crate(roamswitchkit)中,但尚未包含在已公开的 roamswitch-linux-kit 中。
各返回类型的字段定义以原始 Rust 类型声明的形式收录于 GitHub 上的 README。
可以这样集成
以下为 Swift(Mac)示例。roamswitch-linux-kit(Linux)也提供同名方法(snake_case 命名)实现相同效果。
同步/备份类应用
连接到不受信任的网络时,自动暂停后台同步。
let status = try await client.guardStatus()
if !status.isCurrentNetworkTrusted {
syncEngine.pauseBackgroundSync()
}
密码管理器
在不受信任的网络下缩短自动锁定时间等,根据保护级别调整行为。
let status = try await client.guardStatus() let lockTimeout: TimeInterval = status.isCurrentNetworkTrusted ? 300 : 30 vault.setAutoLockTimeout(lockTimeout)
开发者工具与自动化
当开发服务器或本地 AI 推理服务器(Ollama/LM Studio 等)开始在 0.0.0.0 上监听时发出警告。可通过 Shortcuts 等,按网络的可信程度构建工作流。
let ports = try await client.exposedPorts(includeLocalOnly: false)
for port in ports.ports where [3000, 5173, 8000, 11434, 1234].contains(port.port) {
print("⚠️ Dev/AI server exposed on port \(port.port)")
}
邮件与聊天应用中的链接预检查
在显示前自动扫描收到消息中的链接,仅对危险链接发出警告。
let result = try await client.auditURLSafety(url: link)
if result.riskLevel == "dangerous" || result.riskLevel == "suspicious" {
showWarningBanner(for: link, score: result.score)
}
右键菜单/快捷指令的安全检查
接入 Finder 的「服务」菜单或 macOS 快捷指令,一键检查复制的 URL。
// 从 macOS 快捷指令 (App Intent) 或「服务」菜单的处理程序中调用
let report = try await client.auditURLSafety(url: pasteboardURL)
return "\(report.riskLevel.uppercased()) (\(report.score)/100)"
IT 资产管理与 MDM 仪表盘
汇集公司内多台 Mac 的评分,在管理员仪表板上列表显示,并发出警报。
let report = try await client.securityReport() try await mdmAPI.reportScore(deviceID: deviceID, score: report.score, grade: report.grade)
关于 SDK
Q. 可以免费使用吗?
A. 是的。RoamSwitchKit(Mac)与 roamswitch-linux-kit(Linux)均基于 MIT 许可证免费发布。它们需要预先安装 RoamSwitch 本体(诊断引擎),但 SDK 本身不收取任何费用。
Q. 能否更改用户的设置?
A. 不会。没有任何一个 API 可以更改设置、防御、端口或设备。会写入的只有 auditSecurityLogs 和 activeVulnScan 这两个,由 RoamSwitch 更新自己的记录文件。嵌入的应用无法在未经用户许可的情况下更改 RoamSwitch 的保护设置。
Q. 如果没有安装 RoamSwitch 会怎样?
A. 会返回相应的错误(Mac:RoamSwitchClientError.appNotInstalled / Linux:RoamSwitchClientError::AppNotInstalled)。此时建议以平缓的方式处理,例如隐藏该功能。
Q. 想将 RoamSwitch 本体随自家产品捆绑发行怎么办?
A. SDK 集成(本页内容)可免费自由使用。捆绑或再分发 RoamSwitch 本体需要 OEM 许可。请通过OEM 与合作伙伴集成页面咨询。