开发者 SDK

将 RoamSwitch 的诊断能力直接带入你自己的 Mac / Linux 应用

RoamSwitchKit(Mac)和 roamswitch-linux-kit(Linux)是免费的开源客户端,可让 Swift / Rust 代码直接读取 RoamSwitch 本体计算出的安全诊断结果。无需自己编写 ARP 监视或端口扫描,就能把“当前网络是否安全”集成到自己的应用中。

🍎 RoamSwitchKit (macOS) → 🐧 roamswitch-linux-kit (Linux) →

🔒 为什么安全

  • 不更改设置:没有任何更改设置、防御或端口的 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"
提供的 API

方法

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 与合作伙伴集成页面咨询。