Leve os diagnósticos do RoamSwitch diretamente para a sua própria app Mac ou Linux
O RoamSwitchKit (macOS) e o roamswitch-linux-kit (Linux) são clientes gratuitos e de código aberto que permitem que o seu código Swift ou Rust consulte diretamente os mesmos diagnósticos de segurança que o RoamSwitch calcula. Integre «esta rede é segura agora?» na sua própria app sem reimplementar a monitorização de ARP ou a verificação de portas.
🔒 Porque é seguro
- Apenas leitura: não existe nenhuma API para ativar o bloqueio, isolar uma porta ou ejetar um dispositivo. Uma app que ligue este pacote não pode alterar as definições do RoamSwitch sem o consentimento do utilizador.
- Totalmente local: lança o binário incluído com o RoamSwitch (macOS: RoamSwitchMCPServer / Linux: roamswitch-mcp) como subprocesso e comunica apenas via stdio. Nunca é enviado nada para um servidor externo.
- Gratuito e open source: publicado sob a licença MIT — qualquer pessoa pode inspecionar o código-fonte e integrá-lo livremente.
Uma linha no seu gestor de pacotes
Basta adicioná-lo às dependências do seu Package.swift. Requer macOS 12+, Swift 5.9+ e o RoamSwitch 1.3.0 ou posterior instalado.
dependencies: [
.package(url: "https://github.com/lafine1211/RoamSwitchKit.git", from: "1.0.0")
]
Basta adicioná-lo às dependências do seu Cargo.toml. Requer uma toolchain Rust estável (edição 2021, runtime assíncrono tokio) e o RoamSwitch for Linux instalado (que inclui o binário roamswitch-mcp).
[dependencies]
roamswitch-linux-kit = { git = "https://github.com/lafine1211/roamswitch-linux-kit", tag = "v0.1.0" }
Obtenha diagnósticos com alguns métodos simples
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"
Métodos apenas de leitura
securityReport()
Devolve uma auditoria completa e pontuada em 18 verificações — FileVault, SIP, Gatekeeper, firewall, robustez da encriptação Wi-Fi, ARP spoofing, portas expostas e mais — com recomendações para tudo o que falhar.
exposedPorts(includeLocalOnly:)
Lista todas as portas atualmente em escuta e, para as expostas além do localhost, devolve uma auditoria detalhada que inclui a deteção de serviços conhecidos como perigosos (Redis, MongoDB, etc.).
guardStatus()
Obtém o status das proteções de portas, ARP, USB, Bluetooth, downloads Web/Mail, DNS e nível de segurança.
auditURLSafety(url:)
Inspeciona links suspeitos ou URLs encurtadas localmente para detectar phishing e ataques homógrafos (Zero Telemetry).
Outros métodos apenas de leitura
| Método | Descrição |
|---|---|
auditSecurityLogs(hours:) | Agrega os registos de segurança recentes (Mac: falhas de autenticação sudo, tentativas de força bruta SSH, bloqueios do Gatekeeper, deteções do XProtect, etc. / Linux: falhas de autenticação sudo, força bruta SSH, bloqueios da firewall, recusas do AppArmor, deteções do ClamAV, etc.), mascara automaticamente informação sensível como chaves de API e tokens, e devolve também os resultados da deteção de novos padrões (através de modelos de registo) e de anomalias de frequência (picos estatísticos). |
activeVulnScan() | Verificação ativa de vulnerabilidades, não destrutiva e limitada a 127.0.0.1. A única ferramenta que usa a rede: desativada por predefinição, exige ativação nas definições. |
packageCveScan() | Compara os pacotes instalados (Mac: Homebrew / Linux: dpkg, dnf, zypper, pacman) com um mapa de CVE local. Não ocorre qualquer comunicação de rede. |
packageCveScanLanguages(watchedFolders:) | Compara os ficheiros de bloqueio de dependências do npm, PyPI, crates.io, RubyGems, Packagist, Go e Maven com o mesmo mapa de CVE local. Não ocorre qualquer comunicação de rede. |
canaryStatus() | Devolve o estado dos ficheiros-isco anti-ransomware (canary) e até aos 50 incidentes detetados mais recentes. |
portAnomalyIncidents() | Devolve o estado da linha de base da proteção contra portas anómalas, as portas atualmente bloqueadas automaticamente e até aos 50 incidentes mais recentes. A resposta indica explicitamente que as portas atualmente bloqueadas são uma captura do estado atual, sem marca temporal, distinta do histórico de incidentes, que tem marca temporal. |
runtimeThreatStatus() | Indica se este Mac está isolado (Air-Gap) devido a uma deteção de malware do XProtect e qual o incidente que a desencadeou. É o primeiro a consultar durante um Air-Gap ativo. |
notificationHistory() | Devolve o histórico das notificações enviadas pelo RoamSwitch (anomalias de auditoria de registos de segurança, deteções de ClickFix e outras) dos últimos 7 dias, mais recentes primeiro. |
Os campos de cada tipo devolvido estão documentados como declarações Swift no README no GitHub e em AGENTS.md.
security_report()
Obtém uma pontuação e recomendações a partir de uma auditoria de 24 itens que cobre a encriptação de disco LUKS/dm-crypt, o UEFI Secure Boot, o AppArmor/SELinux, a configuração de sudo/SSH, o spoofing de ARP e as portas expostas.
exposed_ports(include_local_only)
Lista todas as portas atualmente em escuta e, para as expostas além do localhost, devolve uma auditoria detalhada que inclui a deteção de serviços conhecidos como perigosos (Redis, MongoDB, etc.).
guard_status()
Obtém o status das proteções de portas, ARP, USB, Bluetooth, downloads Web/Mail, DNS e nível de segurança.
audit_url_safety(url)
Inspeciona links suspeitos ou URLs encurtadas localmente para detectar phishing e ataques homógrafos (Zero Telemetry).
Outros métodos apenas de leitura
| Método | Descrição |
|---|---|
server_security_report() | Executa o perfil de 30 itens da Server Edition (endurecimento do kernel, isolamento de contentores, exposição a CVE do kernel, eBPF LSM) em vez da auditoria do cliente. |
run_active_vuln_scan() | Verificação ativa de vulnerabilidades, não destrutiva e limitada a 127.0.0.1. A única ferramenta que usa a rede: desativada por predefinição, exige ativação nas definições. |
audit_secrets(text) | Deteta chaves de API e chaves privadas expostas em texto, num ficheiro ou numa árvore de diretórios (os resultados são mascarados na saída). |
audit_security_logs(hours) | Agrega os registos de segurança recentes (Mac: falhas de autenticação sudo, tentativas de força bruta SSH, bloqueios do Gatekeeper, deteções do XProtect, etc. / Linux: falhas de autenticação sudo, força bruta SSH, bloqueios da firewall, recusas do AppArmor, deteções do ClamAV, etc.), mascara automaticamente informação sensível como chaves de API e tokens, e devolve também os resultados da deteção de novos padrões (através de modelos de registo) e de anomalias de frequência (picos estatísticos). |
get_app_help(query, topic) | Pesquisa na base de conhecimento oficial do RoamSwitch abrangendo todas as funcionalidades, alertas, configurações e resolução de problemas no dispositivo para fornecer explicações e conselhos precisos. |
quarantine_status() | Devolve o conteúdo do cofre de quarentena: caminho original, nome da ameaça detetada, data de quarentena e tamanho. |
canary_status() | Devolve o estado dos ficheiros-isco anti-ransomware (canary) e até aos 50 incidentes detetados mais recentes. |
package_cve_scan() | Compara os pacotes instalados (Mac: Homebrew / Linux: dpkg, dnf, zypper, pacman) com um mapa de CVE local. Não ocorre qualquer comunicação de rede. |
package_cve_scan_languages(watched_folders) | Compara os ficheiros de bloqueio de dependências do npm, PyPI, crates.io, RubyGems, Packagist, Go e Maven com o mesmo mapa de CVE local. Não ocorre qualquer comunicação de rede. |
verify_fim() | Volta a calcular o hash de cerca de 150 ficheiros críticos do sistema e compara-o com a linha de base guardada para verificar a integridade. |
get_port_anomaly_incidents() | Devolve o estado da linha de base da proteção contra portas anómalas, as portas atualmente bloqueadas automaticamente e até aos 50 incidentes mais recentes. A resposta indica explicitamente que as portas atualmente bloqueadas são uma captura do estado atual, sem marca temporal, distinta do histórico de incidentes, que tem marca temporal. |
get_ebpf_incidents() | Devolve o estado de isolamento atual da guarda de execução eBPF e o historial de incidentes que lhe deu origem. |
Os campos de cada tipo devolvido estão documentados como declarações Rust no README no GitHub.
O que pode construir com ele
Os exemplos abaixo usam Swift (macOS). O roamswitch-linux-kit (Linux) oferece os mesmos métodos (em snake_case) para o mesmo resultado.
Apps de sincronização e backup
Pausa automaticamente a sincronização em segundo plano ao ligar-se a uma rede não fiável.
let status = try await client.guardStatus()
if !status.isCurrentNetworkTrusted {
syncEngine.pauseBackgroundSync()
}
Gestores de palavras-passe
Reduz o tempo de bloqueio automático em redes não fiáveis, adaptando o comportamento ao nível de proteção ativo.
let status = try await client.guardStatus() let lockTimeout: TimeInterval = status.isCurrentNetworkTrusted ? 300 : 30 vault.setAutoLockTimeout(lockTimeout)
Ferramentas para programadores e automação
Avisa quando um servidor de desenvolvimento começa a escutar em 0.0.0.0, ou cria fluxos de trabalho estilo Shortcuts que reagem à confiança da rede.
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)")
}
Verificação prévia de links em apps de e-mail e chat
Analisa automaticamente os links nas mensagens recebidas antes de serem exibidos, alertando apenas sobre os perigosos.
let result = try await client.auditURLSafety(url: link)
if result.riskLevel == "dangerous" || result.riskLevel == "suspicious" {
showWarningBanner(for: link, score: result.score)
}
Verificação de segurança pelo menu de contexto ou Atalhos
Integre ao menu Serviços do Finder ou aos Atalhos do macOS para verificar um URL copiado com uma única ação.
// Chamado a partir de um manipulador do macOS Shortcuts (App Intent) ou do menu Serviços
let report = try await client.auditURLSafety(url: pasteboardURL)
return "\(report.riskLevel.uppercased()) (\(report.score)/100)"
Gestão de ativos de TI e painéis MDM
Coleta pontuações de vários Macs da organização e as exibe como uma lista com alertas em um painel de administrador.
let report = try await client.securityReport() try await mdmAPI.reportScore(deviceID: deviceID, score: report.score, grade: report.grade)
Sobre os SDKs
Q. É gratuito de usar?
A. Sim. Tanto o RoamSwitchKit (macOS) como o roamswitch-linux-kit (Linux) são publicados gratuitamente sob a licença MIT. Ambos requerem que o próprio RoamSwitch (o motor de diagnóstico) esteja instalado, mas os SDKs em si não custam nada.
Q. Pode alterar as definições de um utilizador?
A. Não. É apenas leitura — não há nenhuma API implementada para ativar o bloqueio, isolar portas ou algo semelhante. Uma app que incorpore este pacote não pode alterar as definições de proteção do RoamSwitch sem o consentimento do utilizador.
Q. O que acontece se o RoamSwitch não estiver instalado?
A. É devolvido o erro correspondente (macOS: RoamSwitchClientError.appNotInstalled / Linux: RoamSwitchClientError::AppNotInstalled). Recomendamos tratar isto com elegância — por exemplo, ocultando a funcionalidade — em vez de o tratar como um erro fatal.
Q. E se eu quiser empacotar e redistribuir o próprio RoamSwitch com o meu produto?
A. A integração do SDK (conteúdo desta página) continua livre para usar. Empacotar e redistribuir o próprio RoamSwitch requer uma licença OEM — fale connosco aqui sobre parceria OEM.