Sophos Firewall REST API: accesso sicuro e ciclo di vita delle chiavi

La REST API locale di SFOS 23.0 consente di leggere e modificare la configurazione direttamente sul firewall. Iniziare con un amministratore dedicato con permessi limitati, autorizzare solo l’host di automazione, generare la chiave con quel conto e verificare prima una lettura. La disponibilità della documentazione non conferma una data GA o il supporto su firmware precedenti.

Tre interfacce, tre identità

• REST API locale: la chiave dell’amministratore del firewall funge da token Bearer; i permessi derivano dal profilo amministratore.
• XML API locale: payload XML e credenziali amministratore, normalmente via HTTP POST a APIController. XML <Get> non è una richiesta REST.
• API di configurazione Sophos Central: service principal cloud, token temporaneo, tenant e host API regionale. Una chiave locale non sostituisce queste credenziali.

Preparare accesso e amministratore

1. In Profiles > Device access, creare un profilo con i soli permessi necessari; per l’inventario bastano i permessi di lettura appropriati. In Authentication > Users, creare un amministratore dedicato con questo profilo. La pianificazione di amministratori e profili spiega i ruoli. Non usare il conto personale o il admin predefinito con pieni privilegi per i processi.
2. In Hosts and services > IP host, definire l’host effettivo, ad esempio api-inventory con 192.0.2.20. Sostituire nome e indirizzo di documentazione. Una singola origine fissa è più restrittiva di un’intera rete di gestione; con NAT conta l’origine vista dal firewall.
3. In Administration > API access, attivare API access, disattivato per impostazione predefinita, selezionare solo le origini necessarie in Allowed IP hosts e fare clic su Apply. Sono supportati indirizzi, intervalli e reti, fino a 64 voci. Controllare le origini apiconfig migrate durante l’aggiornamento a SFOS 22.0 o successivo.
4. In Administration > Device access, verificare WebAdmin dalla zona interessata. Device Access e l’elenco API sono controlli distinti; non aprire genericamente l’accesso WAN.

Generare e acquisire la chiave una sola volta

Accedere come amministratore dedicato. In Administration > API access > REST API keys, scegliere Add API key, inserire un nome riconoscibile come inventory-prod-2026-10 e generare con Add API key.

Prima di Close: copiare la chiave nell’archivio protetto dei segreti del processo. Dopo la chiusura della finestra non sarà più visualizzata. Non includerla in screenshot, ticket, file del repository o esportazioni di collection non protette.

La chiave vale un anno ed eredita i permessi del creatore. Gli amministratori creano ed eliminano le proprie chiavi; tutti vedono l’elenco, ma non recuperano il segreto. Il admin predefinito può eliminare anche le chiavi altrui. Limiti: 10 chiavi per amministratore, 1024 complessive. Non condividere chiavi tra amministratori.

Costruire la richiesta dallo schema del firewall

In REST API help, scaricare OpenAPI.yaml da questo firewall e importarlo in Postman o Swagger. In REST API guide, verificare URL base, autenticazione, riferimenti agli oggetti e schema dell’endpoint scelto. I nomi somigliano all’interfaccia, ma non sono sempre identici.

La documentazione di riferimento indica questa base e questo header; percorso, metodo e parametri della richiesta provengono dallo schema corrispondente:

https://<firewall-host>:<port>/firewall-config/v1
Authorization: Bearer <API_KEY>

Sostituire hostname e porta HTTPS amministrativa; inserire la chiave tramite la gestione dei segreti del client. Validare certificato TLS e hostname, senza aggirare i controlli con -k. L’introduzione contiene anche esempi sul percorso XML APIController: non copiarli senza verifica come istruzioni REST. Senza un endpoint corrispondente nello schema del firewall, non inventare percorsi.

Test di lettura e controllo operativo

Inviare una lettura innocua conforme allo schema dall’host reale. Controllare risposta e dati attesi, non solo il successo HTTP. Ripetere da un’origine controllata non autorizzata: non deve restituire configurazione. Non rimuovere autorizzazioni di produzione per preparare il test.

Prima delle scritture, predisporre backup e ripristino, provare una piccola modifica approvata e controllare l’oggetto in WebAdmin e nell’Audit Trail. Dopo un timeout di scrittura, leggere lo stato effettivo prima di riprovare. Letture lente, come le firme IPS, possono richiedere timeout client maggiori.

Scadenza, sostituzione ed eliminazione

Documentare conto, processo, origine autorizzata, creazione, scadenza e team responsabile, mai la chiave. Pianificare promemoria e sostituzione prima della scadenza; non presumere un rinnovo automatico. Riservare uno slot libero per la rotazione con sovrapposizione. Con 10 chiavi proprie o 1024 complessive, identificare prima quelle inutili con il responsabile, senza revocare indiscriminatamente processi attivi.

Per la sostituzione pianificata, generare e acquisire una nuova chiave con lo stesso conto, aggiornare il processo e verificare una lettura. Solo dopo eliminare la vecchia chiave di proprietà e controllare che la nuova funzioni e la vecchia non consenta più l’accesso. Non considerare recuperabili le chiavi eliminate. Sostituire anche una chiave il cui unico momento di visualizzazione è stato perso. In caso di possibile fuga, revocare subito, anche interrompendo il servizio. Per eliminare chiavi altrui coinvolgere il responsabile del admin predefinito. Alla dismissione eliminare chiavi e origini inutili, verificando prima quelle condivise.

Limiti in SFOS 23.0

L’attuale copertura esclude da questa REST API:

• Web: Captive portal, Direct proxy authentication, Web filter notification settings, Advanced settings.
• Tutte le funzioni Email, Wireless e RED.
• Network: DDNS e IP tunnels; SD-WAN profiles.
• VPN: IPsec routes, GRE routes, L2TP, PPTP, client e server SSL VPN site-to-site.
• Authentication: Guest users e clientless users; Firewall rule groups.
• Let’s Encrypt certificates; High availability e TAP mode; System time.
• Informazioni di stato, ad esempio lease DHCP, stato HA e archiviazione dati.

L’elenco non è completo né una promessa per versioni future. Verificare ogni operazione nello schema attuale; la presenza di un menu non prova il supporto API. XML o cloud non sono sostituti automaticamente equivalenti.

Quando il processo fallisce

Per la connessione controllare origine dopo NAT, routing, porta amministrativa, TLS, accesso API e Device Access. Per autenticazione o permessi controllare chiave, scadenza, eliminazione, creatore e profilo, invece di assegnare pieni diritti. Per lo schema confrontare metodo, percorso, campi obbligatori e riferimenti dipendenti. Una chiave persa va sostituita, non cercata in una nuova visualizzazione.

Per l’escalation conservare firmware, versione dello schema, ora, endpoint, stato HTTP e risposta ripulita, senza segreti. Sophos supporta l’API ufficiale e gli script non modificati, non consulenza o troubleshooting delle integrazioni personalizzate. Queste richiedono un responsabile interno; coinvolgere un partner o Sophos Professional Services se necessario.