Bring RoamSwitch's diagnostics straight into your own Mac or Linux app
RoamSwitchKit (macOS) and roamswitch-linux-kit (Linux) are free, open-source clients that let your Swift or Rust code directly query the same security diagnostics RoamSwitch itself computes. Build "is this network safe right now" into your own app without reimplementing ARP monitoring or port scanning.
🔒 Why it's safe
- Read-only: there is no API to toggle lockdown, isolate a port, or eject a device. An app linking this package cannot change RoamSwitch's settings without the user's consent.
- Fully local: it launches the binary bundled with RoamSwitch (macOS: RoamSwitchMCPServer / Linux: roamswitch-mcp) as a subprocess and talks over stdio only. Nothing is ever sent to an external server.
- Free and open source: published under the MIT License — anyone can inspect the source and embed it freely.
One line in your package manager
Just add it to your Package.swift dependencies. Requires macOS 12+, Swift 5.9+, and RoamSwitch 1.3.0 or later installed.
dependencies: [
.package(url: "https://github.com/lafine1211/RoamSwitchKit.git", from: "1.0.0")
]
Just add it to your Cargo.toml dependencies. Requires a stable Rust toolchain (2021 edition, tokio async runtime) and RoamSwitch for Linux installed (which bundles the roamswitch-mcp binary).
[dependencies]
roamswitch-linux-kit = { git = "https://github.com/lafine1211/roamswitch-linux-kit", tag = "v0.1.0" }
Get diagnostics with a few simple methods
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"
Read-only methods
securityReport()
Returns a scored, comprehensive audit across 18 checks — FileVault, SIP, Gatekeeper, firewall, Wi-Fi encryption strength, ARP spoofing, exposed ports, and more — with recommendations for anything failing.
exposedPorts(includeLocalOnly:)
Lists every port currently listening, and for anything exposed beyond localhost, returns a detailed audit including known-dangerous-service and local AI server checks (Redis, MongoDB, Ollama, LM Studio, etc.).
guardStatus()
Gets active status of port guard, ARP auto-containment, USB guard, Bluetooth guard, Web/Mail download guard, DNS threat guard, and security level.
auditURLSafety(url:)
Inspects suspicious email links or shortened URLs for phishing, Unicode homographs, deceptive subdomains, and high-risk TLDs locally (Zero Telemetry).
Other read-only methods
| Method | Summary |
|---|---|
auditSecurityLogs(hours:) | Aggregates recent security logs (Mac: sudo auth failures, SSH brute-force attempts, Gatekeeper blocks, XProtect detections, etc. / Linux: sudo auth failures, SSH brute-force, firewall drops, AppArmor denials, ClamAV detections, etc.), automatically masks secrets like API keys and tokens, and also returns new-pattern detection (log templating) and frequency-anomaly (statistical spike) results. |
activeVulnScan() | Non-destructive, 127.0.0.1-only active vulnerability verification. The only tool that uses the network; off by default and requires opting in from Settings. |
packageCveScan() | Checks installed packages (Mac: Homebrew / Linux: dpkg, dnf, zypper, pacman) against a local CVE map. Sends no network traffic at all. |
packageCveScanLanguages(watchedFolders:) | Checks dependency lockfiles for npm, PyPI, crates.io, RubyGems, Packagist, Go, and Maven against the same local CVE map. Sends no network traffic at all. |
canaryStatus() | Returns the ransomware canary's decoy-file state plus up to the 50 most recent detected incidents. |
portAnomalyIncidents() | Returns the Port Anomaly Guard's baseline state, currently auto-blocked ports, and up to the 50 most recent incidents. The response explicitly notes that the currently-blocked ports are a present-tense snapshot with no timestamp, distinct from the timestamped incident history. |
runtimeThreatStatus() | Returns whether an XProtect malware conviction has air-gapped this Mac, and the incident that triggered it. Check this first to explain an active Air-Gap. |
notificationHistory() | Returns the history of notifications RoamSwitch has sent (security log-audit anomalies, ClickFix detections, and the like) from the past 7 days, most recent first. |
Every return type's fields are documented as plain Swift declarations in the README on GitHub and in AGENTS.md.
security_report()
Gets a score and per-item advice from a 24-check audit covering LUKS/dm-crypt disk encryption, UEFI Secure Boot, AppArmor/SELinux, sudo/SSH configuration, ARP spoofing, and exposed ports.
exposed_ports(include_local_only)
Lists every port currently listening, and for anything exposed beyond localhost, returns a detailed audit including known-dangerous-service and local AI server checks (Redis, MongoDB, Ollama, LM Studio, etc.).
guard_status()
Gets active status of port guard, ARP auto-containment, USB guard, Bluetooth guard, Web/Mail download guard, DNS threat guard, and security level.
audit_url_safety(url)
Inspects suspicious email links or shortened URLs for phishing, Unicode homographs, deceptive subdomains, and high-risk TLDs locally (Zero Telemetry).
Other read-only methods
| Method | Summary |
|---|---|
server_security_report() | Runs the Server Edition's 30-item profile (kernel hardening, container isolation, kernel CVE exposure, eBPF LSM) instead of the desktop client's audit. |
run_active_vuln_scan() | Non-destructive, 127.0.0.1-only active vulnerability verification. The only tool that uses the network; off by default and requires opting in from Settings. |
audit_secrets(text) | Detects leaked API keys and private keys in text, a file, or a directory tree (matches are masked in the output). |
audit_security_logs(hours) | Aggregates recent security logs (Mac: sudo auth failures, SSH brute-force attempts, Gatekeeper blocks, XProtect detections, etc. / Linux: sudo auth failures, SSH brute-force, firewall drops, AppArmor denials, ClamAV detections, etc.), automatically masks secrets like API keys and tokens, and also returns new-pattern detection (log templating) and frequency-anomaly (statistical spike) results. |
get_app_help(query, topic) | Searches RoamSwitch's complete authoritative knowledge base covering all feature specifications, alert messages, settings, and troubleshooting on-device to return precise explanations and actionable advice. |
quarantine_status() | Returns the malware quarantine vault's contents: original path, detected threat name, quarantine time and size. |
canary_status() | Returns the ransomware canary's decoy-file state plus up to the 50 most recent detected incidents. |
package_cve_scan() | Checks installed packages (Mac: Homebrew / Linux: dpkg, dnf, zypper, pacman) against a local CVE map. Sends no network traffic at all. |
package_cve_scan_languages(watched_folders) | Checks dependency lockfiles for npm, PyPI, crates.io, RubyGems, Packagist, Go, and Maven against the same local CVE map. Sends no network traffic at all. |
verify_fim() | Re-hashes about 150 critical system files and compares them against the stored baseline to verify integrity. |
get_port_anomaly_incidents() | Returns the Port Anomaly Guard's baseline state, currently auto-blocked ports, and up to the 50 most recent incidents. The response explicitly notes that the currently-blocked ports are a present-tense snapshot with no timestamp, distinct from the timestamped incident history. |
get_ebpf_incidents() | Returns the eBPF Runtime Guard's current containment status and the incident history behind it. |
Every return type's fields are documented as plain Rust declarations in the README on GitHub.
What you can build with it
The examples below use Swift (macOS). roamswitch-linux-kit (Linux) offers the same methods (in snake_case) for the same result.
Sync & backup apps
Pause background sync automatically when connected to an untrusted network.
let status = try await client.guardStatus()
if !status.isCurrentNetworkTrusted {
syncEngine.pauseBackgroundSync()
}
Password managers
Shorten the auto-lock timeout on untrusted networks, adapting behavior to the active protection level.
let status = try await client.guardStatus() let lockTimeout: TimeInterval = status.isCurrentNetworkTrusted ? 300 : 30 vault.setAutoLockTimeout(lockTimeout)
Developer tools & automation
Warn when a dev server starts listening on 0.0.0.0, or build Shortcuts-style workflows that react to network trust.
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)")
}
Pre-checking links in email & chat apps
Automatically scan links in incoming messages before they're displayed, and warn only about the dangerous ones.
let result = try await client.auditURLSafety(url: link)
if result.riskLevel == "dangerous" || result.riskLevel == "suspicious" {
showWarningBanner(for: link, score: result.score)
}
Right-click menu & Shortcuts safety check
Wire it into Finder’s Services menu or macOS Shortcuts so a copied URL can be checked in one action.
// Called from a macOS Shortcuts (App Intent) or Services menu handler
let report = try await client.auditURLSafety(url: pasteboardURL)
return "\(report.riskLevel.uppercased()) (\(report.score)/100)"
IT asset management & MDM dashboards
Collect scores from Macs across your organization and surface them as a list with alerts on an admin dashboard.
let report = try await client.securityReport() try await mdmAPI.reportScore(deviceID: deviceID, score: report.score, grade: report.grade)
About the SDKs
Q. Is it free to use?
A. Yes. Both RoamSwitchKit (macOS) and roamswitch-linux-kit (Linux) are published for free under the MIT License. They require RoamSwitch itself (the diagnostic engine) to be installed, but the SDKs themselves cost nothing.
Q. Can it change a user's settings?
A. No. It's read-only — there is no implemented API for toggling lockdown, isolating ports, or anything similar. An app embedding this package cannot change RoamSwitch's protection settings without the user's consent.
Q. What happens if RoamSwitch isn't installed?
A. The corresponding error is returned (macOS: RoamSwitchClientError.appNotInstalled / Linux: RoamSwitchClientError::AppNotInstalled). We recommend handling this gracefully — e.g. hiding the feature — rather than treating it as a fatal error.
Q. What if I want to bundle and redistribute RoamSwitch itself with my product?
A. SDK integration (what this page covers) stays free to use as you like. Bundling and redistributing RoamSwitch itself requires an OEM license — get in touch about OEM & partner bundling here.