能更改用户的设置吗？

不能。它是只读的，完全没有实现锁定切换或端口隔离等操作类 API。集成了它的应用无法在未经用户许可的情况下更改 RoamSwitch 的防护设置。

开发者 SDK

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

Q: 可以免费使用吗？

可以。RoamSwitchKit（Mac）和 roamswitch-linux-kit（Linux）均以 MIT 许可证免费公开。前提是已安装 RoamSwitch 本体（诊断引擎），但 SDK 本身不收取任何费用。

Q: 如果没有安装 RoamSwitch 会怎样？

会返回相应的错误（Mac：RoamSwitchClientError.appNotInstalled / Linux：RoamSwitchClientError::AppNotInstalled）。建议此时通过隐藏功能等方式平和地处理。

RoamSwitchKit（Mac）与 roamswitch-linux-kit（Linux）是免费开源客户端，可让你的 Swift / Rust 代码直接查询 RoamSwitch 本体计算出的安全诊断结果。无需自行实现 ARP 监控或端口扫描，即可将“当前网络是否安全”整合进自己的应用。

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

🔒 为什么安全

只读：不存在切换锁定、隔离端口、弹出设备等操作类 API。链接此包的应用无法在未经用户同意的情况下更改 RoamSwitch 的设置。
完全本地：以子进程方式启动 RoamSwitch 本体内置的二进制文件（macOS: RoamSwitchMCPServer / Linux: roamswitch-mcp），仅通过标准输入输出通信，绝不向外部服务器发送任何内容。
免费开源：基于 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、防火墙、Wi-Fi 加密强度、ARP 欺骗、外部暴露端口等 18 项综合诊断的评分与改进建议。

exposedPorts(includeLocalOnly:)

列出当前监听的所有端口，对外暴露的端口会返回包含已知危险服务（Redis/MongoDB 等）判定在内的详细审计结果。

guardStatus()

获取端口防护、ARP自动遏制、USB防护、蓝牙防护、网页/邮件下载保护、DNS威胁防护状态及当前安全级别。

auditURLSafety(url:)

在本地分析可疑链接或短网址，检测钓鱼诈骗、Unicode同形伪装及高风险TLD（Zero Telemetry）。

其他只读方法

方法	概要
`auditSecurityLogs(hours:)`	汇总近期安全日志（Mac：Sudo 认证失败、SSH 暴力破解尝试、Gatekeeper 拦截、XProtect 检测等 / Linux：Sudo 认证失败、SSH 暴力破解、防火墙拦截、AppArmor 拒绝、ClamAV 检测等），自动屏蔽 API 密钥、令牌等敏感信息，并返回基于日志模板化的新模式检测与频率异常（统计学突增）检测结果。
`activeVulnScan()`	仅限 `127.0.0.1` 的非破坏性实证漏洞验证。唯一会使用网络的工具，默认关闭，需在设置中主动启用。
`packageCveScan()`	将已安装的软件包（Mac：Homebrew / Linux：dpkg・dnf・zypper・pacman）与本地 CVE 映射进行比对。完全不产生任何网络通信。
`packageCveScanLanguages(watchedFolders:)`	将 npm / PyPI / crates.io / RubyGems / Packagist / Go / Maven 等依赖锁定文件与同一本地 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、AppArmor/SELinux、sudo/SSH 配置、ARP 欺骗、外部公开端口等 24 项综合诊断得出的评分与改进建议。

exposed_ports(include_local_only)

列出当前监听的所有端口，对外暴露的端口会返回包含已知危险服务（Redis/MongoDB 等）判定在内的详细审计结果。

guard_status()

获取端口防护、ARP自动遏制、USB防护、蓝牙防护、网页/邮件下载保护、DNS威胁防护状态及当前安全级别。

audit_url_safety(url)

在本地分析可疑链接或短网址，检测钓鱼诈骗、Unicode同形伪装及高风险TLD（Zero Telemetry）。

其他只读方法

方法	概要
`server_security_report()`	以服务器版的 30 项配置（内核加固、容器隔离、内核 CVE 暴露、eBPF LSM）执行综合诊断。
`run_active_vuln_scan()`	仅限 `127.0.0.1` 的非破坏性实证漏洞验证。唯一会使用网络的工具，默认关闭，需在设置中主动启用。
`audit_secrets(text)`	从文本、文件或目录中检测泄露的 API Key 与私钥（检出值在输出时已脱敏）。
`audit_security_logs(hours)`	汇总近期安全日志（Mac：Sudo 认证失败、SSH 暴力破解尝试、Gatekeeper 拦截、XProtect 检测等 / Linux：Sudo 认证失败、SSH 暴力破解、防火墙拦截、AppArmor 拒绝、ClamAV 检测等），自动屏蔽 API 密钥、令牌等敏感信息，并返回基于日志模板化的新模式检测与频率异常（统计学突增）检测结果。
`get_app_help(query, topic)`	在本地即时检索涵盖RoamSwitch所有功能规范、底层机制、警报通知及故障排除的官方知识库，返回准确的技术说明与处置建议。
`quarantine_status()`	返回恶意软件隔离 Vault 的内容（原始路径、检出的威胁名称、隔离时间与大小）。
`canary_status()`	返回勒索软件诱饵文件（Canary）的部署状态，以及最近 50 条检测事件。
`package_cve_scan()`	将已安装的软件包（Mac：Homebrew / Linux：dpkg・dnf・zypper・pacman）与本地 CVE 映射进行比对。完全不产生任何网络通信。
`package_cve_scan_languages(watched_folders)`	将 npm / PyPI / crates.io / RubyGems / Packagist / Go / Maven 等依赖锁定文件与同一本地 CVE 映射进行比对。完全不产生任何网络通信。
`verify_fim()`	对约 150 处关键系统文件重新计算哈希，并与基线比对以验证是否被篡改。
`get_port_anomaly_incidents()`	返回端口异常防护的基线状态、当前自动阻断的端口，以及最近 50 条事件。响应中明确注明：当前自动阻断的端口是不带时间戳的当前状态快照，与带时间戳的事件历史是两回事。
`get_ebpf_incidents()`	返回 eBPF 运行时防护的当前隔离状态，以及触发隔离的事件历史。

各返回类型的字段定义以原始 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)

开发者工具与自动化

在开发服务器开始监听 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。集成此包的应用无法在未经用户同意的情况下更改 RoamSwitch 的保护设置。

Q. 如果没有安装 RoamSwitch 会怎样？

A. 会返回相应的错误（Mac: RoamSwitchClientError.appNotInstalled / Linux: RoamSwitchClientError::AppNotInstalled）。建议对此进行妥善处理（例如隐藏相关功能），而不是当作致命错误。

Q. 想将 RoamSwitch 本体随自家产品捆绑发行怎么办？

A. SDK 集成（本页内容）可继续免费自由使用，但捆绑发行 RoamSwitch 本体需要 OEM 授权。请点此咨询 OEM 与合作伙伴捆绑。