Porta le diagnosi di RoamSwitch direttamente nella tua app Mac o Linux
RoamSwitchKit (macOS) e roamswitch-linux-kit (Linux) sono client gratuiti e open source che consentono al tuo codice Swift o Rust di interrogare direttamente le stesse diagnosi di sicurezza calcolate da RoamSwitch. Integra la domanda 'questa rete è sicura adesso' nella tua app senza reimplementare il monitoraggio ARP o la scansione delle porte.
🔒 Perché è sicuro
- Sola lettura: non esiste alcuna API per attivare il blocco, isolare una porta o espellere un dispositivo. Un'app che collega questo pacchetto non può modificare le impostazioni di RoamSwitch senza il consenso dell'utente.
- Completamente locale: avvia il binario incluso con RoamSwitch (macOS: RoamSwitchMCPServer / Linux: roamswitch-mcp) come sottoprocesso e comunica solo tramite stdio. Non viene mai inviato nulla a un server esterno.
- Gratuito e open source: pubblicato con licenza MIT — chiunque può ispezionare il codice sorgente e integrarlo liberamente.
Una riga nel tuo gestore di pacchetti
Basta aggiungerlo alle dipendenze del tuo Package.swift. Richiede macOS 12+, Swift 5.9+ e RoamSwitch 1.3.0 o successivo installato.
dependencies: [
.package(url: "https://github.com/lafine1211/RoamSwitchKit.git", from: "1.0.0")
]
Basta aggiungerlo alle dipendenze del tuo Cargo.toml. Richiede una toolchain Rust stabile (edizione 2021, runtime asincrono tokio) e RoamSwitch for Linux installato (che include il binario roamswitch-mcp).
[dependencies]
roamswitch-linux-kit = { git = "https://github.com/lafine1211/roamswitch-linux-kit", tag = "v0.1.0" }
Ottieni diagnosi con pochi semplici metodi
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"
Metodi in sola lettura
securityReport()
Restituisce un audit completo e valutato su 18 controlli — FileVault, SIP, Gatekeeper, firewall, robustezza della crittografia Wi-Fi, ARP spoofing, porte esposte e altro — con consigli per tutto ciò che non supera il controllo.
exposedPorts(includeLocalOnly:)
Elenca tutte le porte attualmente in ascolto e, per quelle esposte oltre localhost, restituisce un audit dettagliato che include il rilevamento di servizi noti come pericolosi (Redis, MongoDB, ecc.).
guardStatus()
Ottiene lo stato delle protezioni per porte, ARP, USB, Bluetooth, download Web/Mail, DNS e livello di sicurezza.
auditURLSafety(url:)
Ispeziona link sospetti o URL brevi localmente per rilevare phishing e attacchi omografi (Zero Telemetry).
Altri metodi di sola lettura
| Metodo | Descrizione |
|---|---|
auditSecurityLogs(hours:) | Aggrega i log di sicurezza recenti (Mac: errori di autenticazione sudo, tentativi di forza bruta SSH, blocchi Gatekeeper, rilevamenti XProtect, ecc. / Linux: errori di autenticazione sudo, forza bruta SSH, blocchi firewall, dinieghi AppArmor, rilevamenti ClamAV, ecc.), maschera automaticamente le informazioni sensibili come chiavi API e token, e restituisce anche i risultati del rilevamento di nuovi pattern (tramite template dei log) e delle anomalie di frequenza (picchi statistici). |
activeVulnScan() | Verifica attiva delle vulnerabilità, non distruttiva e limitata a 127.0.0.1. L'unico strumento che usa la rete: disattivato per impostazione predefinita, richiede l'attivazione nelle impostazioni. |
packageCveScan() | Confronta i pacchetti installati (Mac: Homebrew / Linux: dpkg, dnf, zypper, pacman) con una mappa CVE locale. Non avviene alcuna comunicazione di rete. |
packageCveScanLanguages(watchedFolders:) | Confronta i file di lock delle dipendenze di npm, PyPI, crates.io, RubyGems, Packagist, Go e Maven con la stessa mappa CVE locale. Non avviene alcuna comunicazione di rete. |
canaryStatus() | Restituisce lo stato dei file esca anti-ransomware (canary) e fino ai 50 incidenti rilevati più recenti. |
portAnomalyIncidents() | Restituisce lo stato della baseline della protezione dalle porte anomale, le porte attualmente bloccate in automatico e fino ai 50 incidenti più recenti. La risposta indica esplicitamente che le porte attualmente bloccate sono un'istantanea dello stato attuale, priva di timestamp, distinta dalla cronologia degli incidenti, che invece è dotata di timestamp. |
runtimeThreatStatus() | Indica se questo Mac è isolato (Air-Gap) a causa di un rilevamento malware di XProtect e qual è l'incidente che lo ha attivato. È il primo strumento da consultare durante un Air-Gap attivo. |
notificationHistory() | Restituisce la cronologia delle notifiche inviate da RoamSwitch (anomalie di controllo dei log di sicurezza, rilevamenti ClickFix e altro) degli ultimi 7 giorni, le più recenti per prime. |
I campi di ogni tipo restituito sono documentati come dichiarazioni Swift nel README su GitHub e in AGENTS.md.
security_report()
Ottiene un punteggio e consigli da un controllo di 24 voci che copre la crittografia del disco LUKS/dm-crypt, UEFI Secure Boot, AppArmor/SELinux, la configurazione sudo/SSH, lo spoofing ARP e le porte esposte.
exposed_ports(include_local_only)
Elenca tutte le porte attualmente in ascolto e, per quelle esposte oltre localhost, restituisce un audit dettagliato che include il rilevamento di servizi noti come pericolosi (Redis, MongoDB, ecc.).
guard_status()
Ottiene lo stato delle protezioni per porte, ARP, USB, Bluetooth, download Web/Mail, DNS e livello di sicurezza.
audit_url_safety(url)
Ispeziona link sospetti o URL brevi localmente per rilevare phishing e attacchi omografi (Zero Telemetry).
Altri metodi di sola lettura
| Metodo | Descrizione |
|---|---|
server_security_report() | Esegue il profilo a 30 voci della Server Edition (hardening del kernel, isolamento dei container, esposizione a CVE del kernel, eBPF LSM) invece dell'audit client. |
run_active_vuln_scan() | Verifica attiva delle vulnerabilità, non distruttiva e limitata a 127.0.0.1. L'unico strumento che usa la rete: disattivato per impostazione predefinita, richiede l'attivazione nelle impostazioni. |
audit_secrets(text) | Rileva chiavi API e chiavi private esposte in un testo, un file o un albero di directory (i risultati vengono mascherati nell'output). |
audit_security_logs(hours) | Aggrega i log di sicurezza recenti (Mac: errori di autenticazione sudo, tentativi di forza bruta SSH, blocchi Gatekeeper, rilevamenti XProtect, ecc. / Linux: errori di autenticazione sudo, forza bruta SSH, blocchi firewall, dinieghi AppArmor, rilevamenti ClamAV, ecc.), maschera automaticamente le informazioni sensibili come chiavi API e token, e restituisce anche i risultati del rilevamento di nuovi pattern (tramite template dei log) e delle anomalie di frequenza (picchi statistici). |
get_app_help(query, topic) | Cerca nella base di conoscenza ufficiale di RoamSwitch riguardante tutte le funzioni, avvisi, impostazioni e risoluzione dei problemi in locale per fornire spiegazioni e consigli precisi. |
quarantine_status() | Restituisce il contenuto del vault di quarantena: percorso originale, nome della minaccia rilevata, data e dimensione. |
canary_status() | Restituisce lo stato dei file esca anti-ransomware (canary) e fino ai 50 incidenti rilevati più recenti. |
package_cve_scan() | Confronta i pacchetti installati (Mac: Homebrew / Linux: dpkg, dnf, zypper, pacman) con una mappa CVE locale. Non avviene alcuna comunicazione di rete. |
package_cve_scan_languages(watched_folders) | Confronta i file di lock delle dipendenze di npm, PyPI, crates.io, RubyGems, Packagist, Go e Maven con la stessa mappa CVE locale. Non avviene alcuna comunicazione di rete. |
verify_fim() | Ricalcola l'hash di circa 150 file di sistema critici e lo confronta con la baseline salvata per verificarne l'integrità. |
get_port_anomaly_incidents() | Restituisce lo stato della baseline della protezione dalle porte anomale, le porte attualmente bloccate in automatico e fino ai 50 incidenti più recenti. La risposta indica esplicitamente che le porte attualmente bloccate sono un'istantanea dello stato attuale, priva di timestamp, distinta dalla cronologia degli incidenti, che invece è dotata di timestamp. |
get_ebpf_incidents() | Restituisce lo stato di isolamento attuale della guardia runtime eBPF e la cronologia degli incidenti all'origine. |
I campi di ogni tipo restituito sono documentati come dichiarazioni Rust nel README su GitHub.
Cosa puoi costruirci
Gli esempi seguenti usano Swift (macOS). roamswitch-linux-kit (Linux) offre gli stessi metodi (in snake_case) per lo stesso risultato.
App di sincronizzazione e backup
Mette automaticamente in pausa la sincronizzazione in background quando ci si connette a una rete non attendibile.
let status = try await client.guardStatus()
if !status.isCurrentNetworkTrusted {
syncEngine.pauseBackgroundSync()
}
Gestori di password
Riduce il timeout di blocco automatico sulle reti non attendibili, adattando il comportamento al livello di protezione attivo.
let status = try await client.guardStatus() let lockTimeout: TimeInterval = status.isCurrentNetworkTrusted ? 300 : 30 vault.setAutoLockTimeout(lockTimeout)
Strumenti per sviluppatori e automazione
Avvisa quando un server di sviluppo inizia ad ascoltare su 0.0.0.0, oppure crea flussi di lavoro in stile Shortcuts che reagiscono all'affidabilità della rete.
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)")
}
Controllo preventivo dei link in app di posta e chat
Analizza automaticamente i link nei messaggi in arrivo prima che vengano mostrati, avvisando solo per quelli pericolosi.
let result = try await client.auditURLSafety(url: link)
if result.riskLevel == "dangerous" || result.riskLevel == "suspicious" {
showWarningBanner(for: link, score: result.score)
}
Controllo di sicurezza dal menu contestuale o da Comandi Rapidi
Integralo nel menu Servizi del Finder o in Comandi Rapidi di macOS per verificare un URL copiato con una sola azione.
// Chiamato da un gestore di macOS Shortcuts (App Intent) o del menu Servizi
let report = try await client.auditURLSafety(url: pasteboardURL)
return "\(report.riskLevel.uppercased()) (\(report.score)/100)"
Gestione risorse IT e dashboard MDM
Raccoglie i punteggi da tutti i Mac dell'organizzazione e li mostra come elenco con avvisi in una dashboard amministrativa.
let report = try await client.securityReport() try await mdmAPI.reportScore(deviceID: deviceID, score: report.score, grade: report.grade)
Informazioni sugli SDK
Q. È gratuito da usare?
A. Sì. Sia RoamSwitchKit (macOS) che roamswitch-linux-kit (Linux) sono pubblicati gratuitamente con licenza MIT. Entrambi richiedono che RoamSwitch stesso (il motore diagnostico) sia installato, ma gli SDK in sé non costano nulla.
Q. Può modificare le impostazioni di un utente?
A. No. È di sola lettura: non è implementata alcuna API per attivare il blocco, isolare porte o simili. Un'app che integra questo pacchetto non può modificare le impostazioni di protezione di RoamSwitch senza il consenso dell'utente.
Q. Cosa succede se RoamSwitch non è installato?
A. Viene restituito l'errore corrispondente (macOS: RoamSwitchClientError.appNotInstalled / Linux: RoamSwitchClientError::AppNotInstalled). Consigliamo di gestirlo con eleganza — ad esempio nascondendo la funzionalità — invece di trattarlo come un errore fatale.
Q. E se volessi integrare e ridistribuire RoamSwitch stesso con il mio prodotto?
A. L'integrazione SDK (il contenuto di questa pagina) resta libera da usare. Integrare e ridistribuire RoamSwitch stesso richiede una licenza OEM — contattaci qui per una partnership OEM.