可以變更使用者的設定嗎？

不行。它是唯讀的，完全沒有實作鎖定切換或連接埠隔離等操作類 API。整合它的 App 無法在未經使用者許可的情況下變更 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），僅透過標準輸入輸出通訊。絕不傳送任何遙測資料。與外部主機通訊的只有需主動啟用（Mac 上僅限 Pro）的 run_npm_audit_signatures（npm 登錄庫）。run_active_vuln_scan（預設關閉）只向 127.0.0.1 傳送探測，Mac 上的 get_exposed_ports 只會對每個暴露的連接埠向 127.0.0.1 傳送 1 次 HTTP GET 以檢查標頭。查詢閘道的 MAC 位址時，Mac 上的診斷類工具可能會向區域網路內的閘道傳送 ICMP ping，通常 1 次（查不到 MAC 時最多數次）。Linux 上的 get_security_report 與 verify_security_findings 不會向區域網路傳送任何內容，只會從本機快取讀取閘道（get_guard_status 等需要重新取得閘道 MAC 的其他工具可能會傳送 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、防火牆、Wi-Fi 加密強度、ARP 欺騙、外部暴露連接埠等 18 項綜合診斷的評分與改進建議。

exposedPorts(includeLocalOnly:)

列出目前監聽的所有連接埠，對外暴露的連接埠會回傳包含已知危險服務（Redis/MongoDB 等）判定在內的詳細稽核結果。在 Mac 上，會對每個暴露的連接埠向 127.0.0.1 傳送 1 次 HTTP GET 以檢查標頭。

guardStatus()

取得連接埠防護、ARP自動遏制、USB防護、藍牙防護、網頁/郵件下載保護、DNS威脅防護狀態及當前安全等級。

auditURLSafety(url:)

於本機分析可疑連結或縮網址，檢測網路釣魚、Unicode同形偽裝及高風險TLD（Zero Telemetry）。

其他唯讀方法

方法	概要
`auditSecurityLogs(hours:)`	彙總近期安全記錄（Mac：Sudo 驗證失敗、SSH 暴力破解嘗試、Gatekeeper 攔截、XProtect 偵測等 / Linux：Sudo 驗證失敗、SSH 暴力破解、防火牆攔截、AppArmor 拒絕、ClamAV 偵測等），自動遮蔽 API 金鑰、權杖等機密資訊，並回傳以記錄範本化的新模式偵測與頻率異常（統計突增）偵測結果。在 Linux 上，如果無法讀取 journal（例如逾時），統計中的 0 筆並不表示什麼都沒發生，此時 journalReadComplete 為 false，並在 journalError 中給出原因。
`activeVulnScan()`	僅限 127.0.0.1 的非破壞性實證型漏洞驗證。不會連線其他主機，但屬於會發送網路請求的工具，因此預設關閉，需在設定中主動啟用。
`packageCveScan()`	將已安裝的套件（Mac：Homebrew / Linux：dpkg・dnf・zypper・pacman）與本機 CVE 對照表比對。完全不產生任何網路通訊。在 Linux 上，如果無法取得套件清單或逾時，不會回報「無符合項目」，而是 complete 為 false，並在 incompleteReason 中給出原因（未完成的結果不等於沒有問題）。在 Ubuntu（20.04、22.04、24.04、26.04）上，使用 Ubuntu 專用資料，依來源套件名稱與來源版本比對，只檢查 Ubuntu 已發布修復、CVSS 7.0 以上的 CVE，因此「無符合項目」不代表沒有已知 CVE。結果中增加 ecosystem 與 release，每筆偵測帶有 binary（已安裝的二進位套件名稱）；只有 Ubuntu Pro 才能修復的漏洞帶有 proOnly。Ubuntu 衍生版（Linux Mint、Pop!_OS 等）與不支援的版本會回傳 complete 為 false，並在 incompleteReason 中給出原因，不會改用 Debian 的資料。
`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 竄改、外部公開連接埠等 27 項綜合診斷得出的評分與改善建議。

exposed_ports(include_local_only)

列出目前監聽的所有連接埠，對外暴露的連接埠會回傳包含已知危險服務（Redis/MongoDB 等）判定在內的詳細稽核結果。在 Mac 上，會對每個暴露的連接埠向 127.0.0.1 傳送 1 次 HTTP GET 以檢查標頭。

guard_status()

取得連接埠防護、ARP自動遏制、USB防護、藍牙防護、網頁/郵件下載保護、DNS威脅防護狀態及當前安全等級。

audit_url_safety(url)

於本機分析可疑連結或縮網址，檢測網路釣魚、Unicode同形偽裝及高風險TLD（Zero Telemetry）。

其他唯讀方法

方法	概要
`server_security_report()`	以伺服器版的 34 項設定檔（核心強化、容器隔離、核心 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 金鑰、權杖等機密資訊，並回傳以記錄範本化的新模式偵測與頻率異常（統計突增）偵測結果。在 Linux 上，如果無法讀取 journal（例如逾時），統計中的 0 筆並不表示什麼都沒發生，此時 journalReadComplete 為 false，並在 journalError 中給出原因。
`get_app_help(query, topic)`	於本機即時檢索涵蓋RoamSwitch所有功能規格、底層機制、警報通知及疑難排解的官方知識庫，提供準確的技術解說與處置建議。
`quarantine_status()`	回傳惡意軟體隔離 Vault 的內容（原始路徑、偵測到的威脅名稱、隔離時間與大小）。
`canary_status()`	回傳勒索軟體誘餌檔案（Canary）的佈署狀態，以及最近 50 筆偵測事件。
`package_cve_scan()`	將已安裝的套件（Mac：Homebrew / Linux：dpkg・dnf・zypper・pacman）與本機 CVE 對照表比對。完全不產生任何網路通訊。在 Linux 上，如果無法取得套件清單或逾時，不會回報「無符合項目」，而是 complete 為 false，並在 incompleteReason 中給出原因（未完成的結果不等於沒有問題）。在 Ubuntu（20.04、22.04、24.04、26.04）上，使用 Ubuntu 專用資料，依來源套件名稱與來源版本比對，只檢查 Ubuntu 已發布修復、CVSS 7.0 以上的 CVE，因此「無符合項目」不代表沒有已知 CVE。結果中增加 ecosystem 與 release，每筆偵測帶有 binary（已安裝的二進位套件名稱）；只有 Ubuntu Pro 才能修復的漏洞帶有 proOnly。Ubuntu 衍生版（Linux Mint、Pop!_OS 等）與不支援的版本會回傳 complete 為 false，並在 incompleteReason 中給出原因，不會改用 Debian 的資料。
`package_cve_scan_languages(watched_folders)`	將 npm / PyPI / crates.io / RubyGems / Packagist / Go / Maven 等相依性鎖定檔與同一本機 CVE 對照表比對。完全不產生任何網路通訊。
`verify_fim()`	對約 150 處關鍵系統檔案重新計算雜湊，並與基準比對以驗證是否遭竄改。以 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)

開發者工具與自動化

在開發伺服器開始監聽 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 與合作夥伴綁定。