wgcert: un tool open source per automatizzare i certificati TLS su WatchGuard Firebox

Questo progetto è nato da un problema molto specifico: i certificati TLS pubblici vengono rinnovati sempre più spesso, ma su alcuni apparati di rete il passaggio dal certificato appena emesso al certificato realmente installato sul dispositivo resta ancora un'operazione manuale. Cercando casi concreti mi sono imbattuto in WatchGuard Firebox, dove diversi amministratori di sistema chiedono da tempo una gestione ACME più automatica.

Nel 2026 WatchGuard ha però messo a disposizione API ufficiali per la gestione dei certificati sui Firebox cloud-managed. Da qui l'idea: invece di costruire un altro client ACME, una dashboard o un SaaS, creare un adattatore molto piccolo che faccia una sola cosa bene: prendere un certificato già rinnovato da Certbot, acme.sh o un'altra CA e distribuirlo al Firebox attraverso l'API ufficiale.

Un problema piccolo, ma molto concreto

La tentazione iniziale, davanti a un problema di automazione, è costruire subito una piattaforma completa: utenti, database, scheduler, dashboard, notifiche e supporto a dieci vendor. Qui ho scelto l'opposto. Il mercato specifico è abbastanza di nicchia e non avrebbe senso investire settimane prima di sapere se qualcuno userà davvero la soluzione.

Il progetto è quindi open source e volutamente timeboxed. Se viene utilizzato da sysadmin o MSP reali, le loro richieste diranno cosa manca. Se invece non genera utilizzo, resta comunque un progetto tecnico riutilizzabile e un esempio concreto di integrazione API e automazione di un processo manuale.

Come funziona wgcert

Il flusso è intenzionalmente lineare: Certbot o acme.sh continuano a occuparsi dell'emissione e del rinnovo. Quando il certificato cambia, un deploy hook può chiamare wgcert. Il CLI autentica l'account WatchGuard via OAuth 2.0, individua il Firebox, controlla il certificato locale, evita di creare duplicati con lo stesso fingerprint, richiede l'installazione e può attendere la conclusione della transazione asincrona.

• `wgcert devices` scopre i Firebox disponibili attraverso la Device Details API.
• `wgcert devices --include-hierarchy` permette anche la discovery degli account Subscriber per gli account WatchGuard Service Provider.
• `wgcert deploy --dry-run` controlla certificato, chiave e stato remoto senza effettuare mutazioni.
• `wgcert deploy --wait 2m` richiede l'installazione e segue la transazione asincrona fino a completamento, errore o timeout.
• Dopo l'installazione il tool rilegge il certificato remoto e confronta il fingerprint SHA-256 con quello locale.
• `wgcert check --verify-host host:443` esegue anche un vero handshake TLS per controllare il certificato servito dall'endpoint.

Il progetto supporta soltanto Firebox cloud-managed, perché è il perimetro coperto dalla Certificate API ufficiale. I dispositivi locally-managed sono esplicitamente esclusi dalla prima versione invece di essere supportati con automazioni fragili via SSH o strumenti tipo Expect.

Perché Go e non una web app

Per questo tipo di strumento Go era una scelta naturale: il risultato è un singolo binario per Linux, macOS e Windows, senza runtime da installare. Per un amministratore di sistema è molto più semplice scaricare `wgcert`, configurare le variabili d'ambiente e richiamarlo da un hook rispetto a dover installare Node, Python, un database o un servizio web.

Anche l'architettura è volutamente piccola. Il client WatchGuard usa un endpoint HTTP iniettabile, così quasi tutto il flusso può essere testato con un server HTTP locale simulato. I test generano inoltre certificati X.509 temporanei, verificano corrispondenza chiave/certificato, fingerprint, autenticazione, payload API, error handling, refresh dei token e comportamento delle transazioni.

Come testare un'integrazione hardware senza avere l'hardware

È anche la parte più interessante del progetto: io non possiedo un WatchGuard Firebox. Per questo ho separato esplicitamente la correttezza del software dalla validazione del dispositivo reale. Al momento il progetto è a livello «mocked API»: i flussi documentati vengono verificati localmente contro un server simulato, ma non dichiaro che l'automazione sia production-ready.

Possiamo testare offline parsing PEM, fingerprint, OAuth, discovery, richieste create/install, risposte asincrone, timeout, idempotenza della creazione, dry-run e TLS verification. Quello che un mock non può dimostrare è la cosa più importante: dopo il rinnovo, il certificato diventa realmente attivo nel servizio Firebox previsto senza richiedere ogni volta un passaggio manuale nella configurazione?

Una piccola correzione che i mock da soli non avrebbero suggerito

Durante il confronto puntuale con la documentazione WatchGuard è emerso, per esempio, che una risposta di installazione può rappresentare `device` come array. Il modello Go iniziale lo trattava come stringa: una risposta reale perfettamente valida avrebbe quindi potuto fallire in deserializzazione proprio dopo che WatchGuard aveva accettato il comando. Ho reso il parsing più tollerante e aggiunto un test specifico sul formato documentato.

Ho aggiunto anche l'attesa esplicita delle transazioni. Un HTTP 200 che accetta un comando asincrono non significa che l'installazione sul dispositivo sia terminata: con `--wait` il CLI distingue ora richiesta accettata, operazione completata, errore e timeout. È una differenza piccola nell'interfaccia, ma fondamentale in un'automazione che dovrà girare senza qualcuno davanti al terminale.

Cosa non sto costruendo

• Nessuna dashboard web, database o sistema utenti.
• Nessuna emissione ACME proprietaria: Certbot e acme.sh fanno già quel lavoro.
• Nessun supporto prematuro per FortiGate, Palo Alto, F5 o altri vendor.
• Nessun workaround SSH per i Firebox locally-managed nella prima versione.
• Nessun SaaS o modello a pagamento finché non emergono esigenze reali da operatori che gestiscono più dispositivi.

Se un MSP dovesse usare il progetto e chiedere gestione multi-account, decine di Firebox, audit o orchestrazione centralizzata, quello sarebbe un segnale molto più utile di centinaia di star GitHub. Fino ad allora il progetto rimane intenzionalmente un adattatore piccolo e verificabile.

Il prossimo passo: trovare un Firebox reale

La repository è già pubblica e contiene CLI, test, documentazione, hook Certbot/acme.sh, binari di prerelease e una piccola landing tecnica. Il prossimo obiettivo è raggiungere uno o più amministratori WatchGuard che possano provare il flusso su un Firebox cloud-managed o ottenere una evaluation FireboxV.

Per il test non mi interessa sapere quante persone mettono una star al progetto: mi interessa sapere se almeno un operatore riesce a completare un vero ciclo di rinnovo, quale configurazione utilizza e quali passaggi manuali rimangono. È quella evidenza che deciderà se fermare il progetto, consolidarlo come semplice utility open source o evolverlo in qualcosa di più ampio.

La pagina tecnica di wgcert contiene anche la guida di installazione e il percorso per partecipare ai test. Il progetto è non ufficiale e non è affiliato, approvato o supportato da WatchGuard Technologies.