Sì. RoamSwitchKit (Mac) e roamswitch-linux-kit (Linux) sono entrambi pubblicati gratuitamente con licenza MIT. È necessario installare RoamSwitch (il motore di diagnostica), ma l'SDK in sé non ha alcun costo.

Può modificare le impostazioni dell'utente?

No. È di sola lettura e non è implementata alcuna API di controllo, come il passaggio al lockdown o l'isolamento delle porte. Un'app che lo integra non può modificare le impostazioni di protezione di RoamSwitch senza il permesso dell'utente.

SDK per sviluppatori

Porta le diagnosi di RoamSwitch direttamente nella tua app Mac o Linux

Q: Cosa succede se RoamSwitch non è installato?

Viene restituito l'errore corrispondente (Mac: RoamSwitchClientError.appNotInstalled / Linux: RoamSwitchClientError::AppNotInstalled). Si consiglia di gestirlo con discrezione, ad esempio nascondendo la funzione.

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.

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

🔒 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: il binario incluso con RoamSwitch (macOS: RoamSwitchMCPServer / Linux: roamswitch-mcp) viene avviato come sottoprocesso e comunica solo tramite standard I/O. Non viene mai inviata telemetria. Solo run_npm_audit_signatures (registro npm), facoltativo e riservato a Pro su Mac, comunica con un host esterno. run_active_vuln_scan (disattivato per impostazione predefinita) sonda soltanto 127.0.0.1, e su Mac get_exposed_ports si limita a inviare un HTTP GET per ogni porta esposta a 127.0.0.1 per controllare le intestazioni. Per ricavare l'indirizzo MAC del gateway, gli strumenti di diagnostica su Mac possono inviare un ping ICMP, di norma uno (pochi se il MAC non si risolve), al gateway della LAN. Su Linux, get_security_report e verify_security_findings non inviano nulla alla LAN e leggono il gateway solo dalle cache locali (altri strumenti che risolvono di nuovo il MAC del gateway, come get_guard_status, possono inviare un ping).
Gratuito e open source: pubblicato con licenza MIT — chiunque può ispezionare il codice sorgente e integrarlo liberamente.

Installazione

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" }

Utilizzo

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"

Superficie API

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.). Su Mac, invia un HTTP GET per ogni porta esposta a 127.0.0.1 per controllare le intestazioni.

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). Su Linux, se il journal non può essere letto (per esempio per timeout), gli zeri nel conteggio non significano che non sia successo nulla; journalReadComplete diventa false e journalError indica il motivo.
`activeVulnScan()`	Verifica attiva delle vulnerabilità, non distruttiva e limitata a 127.0.0.1. Non contatta altri host, ma invia richieste di rete: per questo è disattivata per impostazione predefinita e richiede l'attivazione esplicita 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. Su Linux, se l'elenco dei pacchetti non può essere letto o scade il tempo, non viene riportato «nessuna corrispondenza»; complete diventa false e incompleteReason indica il motivo (un risultato incompleto non è un risultato pulito). Su Ubuntu (20.04, 22.04, 24.04, 26.04) usa i dati propri di Ubuntu, confronta per nome e versione del pacchetto sorgente e controlla solo le CVE con CVSS 7,0 o superiore per cui Ubuntu ha già pubblicato una correzione, quindi «nessuna corrispondenza» non significa che non esistano CVE note. Il risultato aggiunge ecosystem e release, ogni rilevamento riporta binary (il nome del pacchetto binario installato) e le correzioni disponibili solo con Ubuntu Pro hanno proOnly. Le derivate di Ubuntu (Linux Mint, Pop!_OS e altre) e le versioni non supportate restituiscono complete = false con il motivo in incompleteReason, senza passare ai dati di Debian.
`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 27 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.). Su Mac, invia un HTTP GET per ogni porta esposta a 127.0.0.1 per controllare le intestazioni.

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 34 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. Non contatta altri host, ma invia richieste di rete: per questo è disattivata per impostazione predefinita e richiede l'attivazione esplicita 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). Su Linux, se il journal non può essere letto (per esempio per timeout), gli zeri nel conteggio non significano che non sia successo nulla; journalReadComplete diventa false e journalError indica il motivo.
`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. Su Linux, se l'elenco dei pacchetti non può essere letto o scade il tempo, non viene riportato «nessuna corrispondenza»; complete diventa false e incompleteReason indica il motivo (un risultato incompleto non è un risultato pulito). Su Ubuntu (20.04, 22.04, 24.04, 26.04) usa i dati propri di Ubuntu, confronta per nome e versione del pacchetto sorgente e controlla solo le CVE con CVSS 7,0 o superiore per cui Ubuntu ha già pubblicato una correzione, quindi «nessuna corrispondenza» non significa che non esistano CVE note. Il risultato aggiunge ecosystem e release, ogni rilevamento riporta binary (il nome del pacchetto binario installato) e le correzioni disponibili solo con Ubuntu Pro hanno proOnly. Le derivate di Ubuntu (Linux Mint, Pop!_OS e altre) e le versioni non supportate restituiscono complete = false con il motivo in incompleteReason, senza passare ai dati di Debian.
`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à. Se eseguito come root, il risultato contiene anche un campo aggiunto, `recentIntrusionContext`: per ogni modifica recente, il processo che l'ha fatta (account, eseguibile, comando) e l'accesso SSH a cui appartiene (origine, ora di accesso, metodo di autenticazione), oppure il motivo per cui non è stato possibile scoprirlo.
`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. Nella Server Edition ogni record riporta anche il tempo dal rilevamento alla risposta in millisecondi (`detect_to_receive_ms`, `receive_to_action_ms`, `detect_to_action_ms`), e il risultato include lo stato dell'heartbeat di Falco (`heartbeat`).

get_ssh_guard_incidents(), che restituisce lo stato e la cronologia della guardia contro la forza bruta SSH (la Server Edition e la Client Edition finché sshd è in esecuzione), esiste nel crate interno di RoamSwitch (roamswitchkit) ma non è ancora stato riportato nel roamswitch-linux-kit pubblico.

I campi di ogni tipo restituito sono documentati come dichiarazioni Rust nel README su GitHub.

Casi d'uso

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)

Domande frequenti

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.