Proteggere l'accesso all'API XML di Sophos Firewall

L’API XML di Sophos Firewall è utile per automazione, monitoraggio, backup, analisi e integrazioni. Consente inoltre di applicare in modo riproducibile la stessa configurazione a più firewall quando il processo è strettamente delimitato e testato. Proprio per questo fa parte della superficie di attacco di gestione. Consentire l’accesso all’API significa dare a un sistema la possibilità di leggere dati di configurazione o, a seconda delle autorizzazioni, apportare modifiche.

L’accesso all’API non dovrebbe quindi essere ampiamente consentito da reti interne o fonti arbitrarie. È meglio avere un piccolo set documentato di reti di gestione, host di automazione o accessi partner fissi.

Dalla versione SFOS 22, Sophos ha ampliato il controllo dell’accesso all’API. Le impostazioni di accesso all’API si trovano in Administration > API access, e le fonti consentite possono essere definite come host IP. In questo modo è possibile modellare correttamente non solo singoli indirizzi IP, ma anche intervalli IP e reti.

Nelle versioni SFOS precedenti, la configurazione API si trovava in Backup and firmware > API. Questa modifica del percorso di menu va considerata quando si confrontano istruzioni meno recenti.

Quando l’accesso all’API XML è utile

L’API XML non è un accesso standard per il lavoro amministrativo normale. È utile quando c’è un processo tecnico concreto dietro.

Casi d’uso tipici:

• Monitoraggio o inventario.
• Controlli di configurazione automatizzati.
• Processi di backup o documentazione.
• Piattaforme MSP o di integrazione.
• Script per compiti amministrativi ricorrenti.
• Modifiche preparate da strumenti come Sophos Firewall Config Studio.

Se un processo può funzionare anche senza API, l’accesso all’API non dovrebbe rimanere attivato preventivamente. Ogni interfaccia aggiuntiva necessita di un proprietario, una fonte, un concetto di accesso e un controllo.

Cosa è cambiato con SFOS 22

Con SFOS 22, il controllo dell’accesso all’API XML è diventato molto più gestibile:

• Le impostazioni di accesso all’API sono state spostate nel menu Administration > API access.
• L’accesso all’API è disattivato per impostazione predefinita e deve essere abilitato consapevolmente.
• L’accesso all’API può essere limitato agli host IP.
• Come fonti sono possibili indirizzi IP, intervalli IP e reti.
• Possono essere consentiti fino a 64 host IP.
• Durante l’aggiornamento, gli indirizzi IP precedentemente consentiti vengono automaticamente convertiti in oggetti host IP.
• Gli oggetti migrati ricevono il prefisso apiconfig.

Questo è utile per l’operatività, poiché le fonti API non devono più essere gestite solo come singoli indirizzi sciolti. È possibile nominare correttamente una rete di gestione, un host di automazione o un gruppo di host dedicato e riconoscerli successivamente nelle revisioni.

Regola di base: consentire l’API solo da sorgenti definite

L’accesso API deve essere trattato come WebAdmin o SSH: il più ristretto possibile, ampio solo quanto necessario.

Sorgenti sensate sono ad esempio:

• un server di automazione dedicato,
• un sistema di monitoraggio,
• un host di configuration management,
• una rete interna di management,
• una rete VPN o amministrativa,
• un indirizzo sorgente partner o MSP chiaramente definito.

Non sono sensate:

• intere reti client,
• reti guest o IoT,
• Any,
• autorizzazioni vaghe del tipo “tutta la rete server”,
• indirizzi IP di test temporanei che poi vengono dimenticati.

Se fornitori esterni hanno bisogno di accesso API, la sorgente deve essere definita nel modo più specifico possibile. Inoltre deve essere documentato a cosa serve l’accesso e quando verrà rimosso.

Procedura consigliata

Il percorso esatto nell’interfaccia può variare leggermente in base alla versione SFOS. In SFOS 22 la configurazione API si trova in Administration > API access.

Procedura pratica:

1. Verificare quale sistema necessita dell’accesso API.
2. In Hosts and services > IP host, creare un oggetto IP Host chiaro per questo sistema.
3. Se servono più sorgenti, nominare in modo pulito IP Hosts, IP ranges o reti.
4. In Administration > API access, abilitare API access.
5. In Allowed IP hosts, consentire solo questi oggetti.
6. Fare clic su Apply.
7. Non inserire reti client o server ampie.
8. Testare l’accesso dal vero host di automazione o monitoraggio, non dal notebook admin.
9. Rimuovere le sorgenti non più necessarie.
10. Documentare la modifica nel processo di change.

Nelle installazioni esistenti, dopo un upgrade a SFOS 22, è opportuno cercare anche oggetti con il prefisso apiconfig. Questi oggetti sono stati creati da vecchie autorizzazioni API e devono essere verificati, rinominati o ripuliti.

Testare l’accesso in modo mirato

L’endpoint API si trova di solito qui:

https://<IP-o-hostname-firewall>:<Port>/webconsole/APIController

La porta è la porta HTTPS della WebAdmin Console. Se la porta admin è stata modificata in Administration > Admin settings, lo strumento API deve usare la stessa porta. L’API lavora con payload XML tramite HTTP POST, non come una classica API REST con endpoint GET, POST, PUT e DELETE separati.

HTTPS protegge in modo affidabile le credenziali da intercettazioni e manomissioni solo se il client convalida il certificato del firewall. Il sistema di automazione deve quindi usare il nome presente nel certificato, considerare attendibile la CA emittente e interrompersi in caso di errori del certificato o del nome host. Opzioni come curl -k eludono questo controllo e non devono essere usate nei job di produzione.

Un test sensato non deve solo verificare se il login è possibile. Deve mostrare se la sorgente corretta è autorizzata, se l’account può eseguire l’operazione richiesta e se il risultato resta tracciabile nel processo di audit o change.

Per l’accettazione, verificare separatamente questi punti:

• Sorgente: Il test viene eseguito dal vero host di automazione, monitoraggio o integrazione, non dal notebook admin.
• Accesso: Il firewall accetta l’IP sorgente solo se l’oggetto IP Host corrispondente è autorizzato in API access.
• Test negativo: Da un host di test controllato, volutamente assente da Allowed IP hosts, inviare la stessa richiesta di lettura innocua e verificare che l’API la rifiuti senza restituire dati di configurazione. Non allentare né rimuovere un’autorizzazione di produzione soltanto per creare questo caso di test.
• Account: L’account API o di servizio usato ha solo i diritti necessari.
• Secret: Nome utente, password o token non finiscono nella shell history, nei ticket, nelle chat o negli screenshot.
• Audit: L’accesso o la modifica è tracciabile nel processo di audit o change.
• Rollback: Prima delle operazioni di scrittura esistono un backup, un punto di rollback e un test di lettura innocuo.

Gli esempi curl con nome utente e password nell’URL vengono copiati rapidamente e poi sono difficili da rimuovere dai log. È meglio eseguire un breve test con un account di servizio dedicato, un secret temporaneo, archiviazione sicura e successiva rotazione se un secret è stato usato in un contesto non sicuro.

Per test strutturati, una collection Postman è spesso più pulita di un comando shell copiato al volo. Anche lì indirizzo del firewall, porta, nome utente, password e valori degli oggetti devono essere gestiti come variabili o secret, non inseriti direttamente in request, screenshot o ticket. La collection non è un concetto di sicurezza, ma aiuta a testare operazioni di lettura e scrittura in modo più riproducibile.

Un’API raggiungibile non dimostra ancora che la modifica pianificata sia tecnicamente sicura. Prima di operazioni di scrittura in produzione deve quindi funzionare prima una query di lettura innocua, seguita da una piccola modifica controllata.

Costruire e valutare consapevolmente le richieste XML

Limite di versione: Le istruzioni SFOS 22 includono i browser come client XML. Da SFOS 23.0, la procedura specifica per inviare richieste XML esclude espressamente i browser; usare Postman o una riga di comando Linux controllata per questi POST. Il riepilogo generale XML cita ancora i browser, senza autorizzare POST da browser in SFOS 23.0. La REST API locale con chiavi amministratore è un’interfaccia separata, non un nuovo metodo di autenticazione per questi payload XML.

Le query e le modifiche mostrate qui usano HTTP POST verso lo stesso APIController. Lettura, creazione, aggiornamento o eliminazione sono definiti nel payload XML, non nel metodo HTTP. XML <Get> indica lettura, non automaticamente HTTP GET; anche la query Object Usage chiamata «API GET request» viene inviata via HTTP POST. L’esportazione dei certificati sotto è un’eccezione HTTP GET documentata separatamente. La struttura esterna comprende <Request>, <Login> ed esattamente l’operazione necessaria:

• <Set operation="add"> crea oggetti, regole o policy supportati.
• <Set operation="update"> modifica impostazioni che non possono essere create come nuovi oggetti.
• <Get> legge configurazioni o dati di stato.
• <Remove> elimina gli oggetti supportati. Le impostazioni fisse, come la configurazione SSL/TLS Inspection, non possono essere eliminate, ma solo aggiornate.
• <Filter> limita una query di lettura. I criteri generali sono =, != e like; alcune query statistiche supportano criteri aggiuntivi.

Se operation viene omesso da <Set>, SFOS tratta la richiesta come add. Non è un valore predefinito innocuo: una richiesta concepita come aggiornamento può non riuscire o agire sull’oggetto sbagliato. APIXMLTags documenta l’attributo alfanumerico facoltativo transactionid su <Set>; facilita la correlazione tra richiesta e risposta. Per le operazioni specializzate, occorre seguire l’esempio dell’oggetto in API help del build SFOS installato. L’esempio del certificato colloca transactionid su <Certificate>; questa eccezione non costituisce una regola generale per il suo posizionamento sui tag delle entità all’interno di <Set>.

L’attributo facoltativo APIVersion in <Request> utilizza una sintassi specifica della versione. I tag degli oggetti, gli attributi, i codici di stato e le configurazioni di esempio esatti devono quindi provenire dall’API help del build SFOS installato; i payload non vanno trasferiti tra versioni senza verificarli.

Una piccola query di lettura ha questa struttura:

<Request>
  <Login>
    <Username>api-reader</Username>
    <Password>SECRET</Password>
  </Login>
  <Get>
    <IPHost></IPHost>
  </Get>
</Request>

api-reader e SECRET sono segnaposto. Il secret reale deve essere conservato nel secret store protetto dello strumento, non in un file XML nel repository. Il test è riuscito solo quando la risposta contiene il risultato previsto in <Response> e uno stato appropriato in <Status>. Un successo HTTP o Send successful in Postman non dimostra da solo che SFOS abbia eseguito l’operazione desiderata. Per le operazioni di scrittura, controllare anche l’oggetto di destinazione in WebAdmin e la modifica nell’Audit Trail.

Usare in modo sicuro la collection Postman ufficiale

Scaricare e importare la collection Postman attuale. La collection copre solo una parte delle richieste supportate; l’API help locale del firewall mostra l’insieme completo delle operazioni e le configurazioni di esempio e definizioni delle entità specifiche del build. Prima della prima richiesta, sostituire nelle Collection Variables tutti e quattro i valori di esempio inclusi apiadmin, Admin@12345, 172.16.16.16 e 4444 con i valori username, password, firewall-ip e firewall-port dell’ambiente. Anche i valori degli oggetti inclusi sono esempi e non devono essere inviati senza verifica.

Per una richiesta personalizzata, usare il metodo POST, l’endpoint mostrato sopra e la chiave reqxml in Body > form-data. Testare prima Authenticate > Sign in e poi una query <Get> innocua. Solo quando sorgente, account, risposta e audit sono corretti deve seguire una piccola operazione di scrittura con rollback preparato.

Importazioni XML sensibili: Prima di importare password o altri valori sensibili, verificare in API help del build installato se la specifica operazione richiede SecureStorageMasterKey e l’attributo Token su <Request> e quali dati sono validi. Nell’esempio POST di SFOS 23, SecureStorageMasterKey è un dato separato nel corpo; Token si trova su <Request> nell’XML del campo reqxml del corpo. Trasmettere solo i dati confermati per questa operazione nelle posizioni POST/XML approvate. In questo flusso, tenere chiavi, password e token fuori da URL, cronologia della shell e log; ciò non implica che ogni query XML richieda un token.

La documentazione conserva anche un esempio URL contraddittorio per la chiave principale. Finché un conflitto tra fonti, un dato richiesto o la sua interpretazione rimane irrisolto per il build installato, non eseguire l’importazione sensibile e chiedere chiarimenti al Support. L’esportazione dei certificati tramite HTTP GET descritta sotto, con le sue precauzioni specifiche, resta un’eccezione distinta.

Una collection esportata può contenere credenziali o valori dell’ambiente. Ripulire le collection prima di condividerle, non memorizzare secret in chiaro come Initial Values e ruotare le password di test dopo una perdita.

Interrogare Object Usage prima delle modifiche

L’API può restituire i nomi e lo Usage Count degli oggetti supportati. A questo scopo si utilizzano tag statistici come <IPHostStatistics> al posto del normale tag dell’oggetto. Un filtro sui nomi degli IP Host ha questo aspetto:

<Request>
  <Login>
    <Username>api-reader</Username>
    <Password>SECRET</Password>
  </Login>
  <Get>
    <IPHostStatistics>
      <Filter>
        <key name="Name" criteria="like">branch</key>
      </Filter>
    </IPHostStatistics>
  </Get>
</Request>

SFOS 22 supporta questa query di utilizzo per IP Hosts, IP Host Groups, MAC Hosts, FQDN Hosts e relativi gruppi, Country Groups, Services e Service Groups, oltre a Interfaces, Zones, Gateways e SD-WAN Profiles. I filtri sul nome includono like, not like, startswith, in, = e !=; lo Usage Count supporta inoltre >, >= ed elenchi di numeri con in.

Attualmente la risposta contiene solo il nome dell’oggetto e il numero di utilizzi, non le configurazioni dipendenti. Uno Usage Count di 3 non identifica quindi le tre regole o i tre profili coinvolti. Prima di un’operazione update o remove, controllare anche Object usage in WebAdmin o Config Studio. Anche un valore di 0 non autorizza un’eliminazione incontrollata: backup, verifica delle dipendenze e test limitato restano obbligatori.

Eseguire login e logout dei Live Users tramite API

SFOS può eseguire il login o il logout di un utente come Live User tramite API. La funzione è adatta a un’integrazione con un sistema di autenticazione esterno che abbia una responsabilità chiaramente definita, ma non è una scorciatoia generale per aggirare il normale login. Un accesso errato associa il traffico a un’identità e può quindi influenzare le regole firewall o web basate sugli utenti.

Per l’amministratore che esegue l’operazione, Manage live users deve essere impostato su Read-write in Profiles > Device access > Identity. L’endpoint previsto è:

https://<Firewall-IP-o-FQDN>:<Port>/xmlapi/v1/authentication/networkuser

Questo endpoint elabora login e logout in parallelo. L’APIController generale può elaborare le stesse operazioni in modo seriale. Un’integrazione esistente non deve quindi essere migrata senza test solo per questa differenza di comportamento.

Un payload di login può essere strutturato così:

<Request>
  <LiveUserLogin>
    <Admin>
      <UserName>api-liveusers</UserName>
      <Password>ADMIN_SECRET</Password>
    </Admin>
    <UserName>testuser</UserName>
    <IPAddress>192.0.2.25</IPAddress>
    <MacAddress>AA-BB-CC-DD-EE-FF</MacAddress>
  </LiveUserLogin>
</Request>

Per il logout si invia lo stesso utente logico con LiveUserLogout:

<Request>
  <LiveUserLogout>
    <Admin>
      <UserName>api-liveusers</UserName>
      <Password>ADMIN_SECRET</Password>
    </Admin>
    <UserName>testuser</UserName>
    <IPAddress>192.0.2.25</IPAddress>
    <MacAddress>AA-BB-CC-DD-EE-FF</MacAddress>
  </LiveUserLogout>
</Request>

api-liveusers, ADMIN_SECRET, testuser, 192.0.2.25 e l’indirizzo MAC sono valori di esempio. Nome utente, IP e MAC devono corrispondere alla sessione reale. Il segreto amministrativo deve essere conservato nel secret store protetto dello strumento e inviato nel corpo HTTP POST, non in un URL, nella cronologia della shell, in un file di log o in una collection condivisa.

Dopo il login, l’utente deve comparire in Current activities > Live users con Client type API client. Un test controllato verifica poi la decisione prevista della regola basata sugli utenti. Dopo il logout, la sessione non deve più risultare come client API attivo. Se l’utente rimane visibile, controllare prima payload, nome utente, IP, MAC e risposta API; non disconnettere per supposizione una sessione Live User estranea.

Trasferire o esportare certificati tramite API

I certificati sono un caso particolare perché oltre all’XML vengono trasferiti file. Per creare o aggiornare un certificato si utilizza nell’app desktop Postman una richiesta form-data con tre parti: file del certificato, file della Private Key e reqxml contenente un payload <Set><Certificate>...</Certificate></Set>. Nomi dei file, formato, azione e nome del certificato nell’XML devono corrispondere ai file caricati.

Le Private Key devono rimanere esclusivamente sull’endpoint amministrativo protetto e non devono mai finire in una cloud collection, un ticket o un repository. Dopo Send, valutare prima <Response> e <Status>, quindi verificare in Certificates > Certificates che siano presenti esattamente il certificato previsto, la chiave corrispondente e la catena corretta. L’assegnazione e il test del servizio seguono la procedura Importare e assegnare certificati su Sophos Firewall. L’intero percorso di automazione, dalla CA pubblica e dall’upload specifico della build fino all’assegnazione al servizio e alla verifica esterna, è descritto in Rinnovare un certificato Sophos Firewall tramite API XML e verificare i servizi.

Una richiesta <Get><Certificate/></Get> restituisce un archivio .tar con certificati, Private Key ed Entities.xml, non un normale risultato XML. Non funziona quindi come risposta Postman normale. La guida specifica documenta HTTP GET da Linux o browser; entrambe le varianti inseriscono credenziali nel reqxml dell’URL.

SFOS 23.0: Questa guida GET cita ancora i browser, mentre quella POST li esclude. Non dimostra un divieto di tutti gli HTTP GET né un’esportazione browser testata su questo firmware. Non trasferire istruzioni browser da versioni precedenti né presumere che POST produca lo stesso download. Prima dell’esportazione, verificare con Support o in un sistema di test autorizzato il percorso CLI GET e la gestione sicura delle credenziali per la build installata; senza verifica, non eseguire l’esportazione.

Per un’esportazione verificata usare solo un conto temporaneo con privilegi limitati su un host protetto, non registrare URL o comando e ruotare poi il segreto. Validare certificato TLS e hostname; non trasferire -k degli esempi del produttore in produzione. L’archivio è altamente sensibile: conservarlo cifrato con accesso limitato, estrarlo in modo controllato e rimuovere con sicurezza le copie inutili.

Accesso all’API e diritti utente

Un indirizzo IP di origine da solo non è un concetto di sicurezza completo. La restrizione limita solo da dove l’API è raggiungibile. Inoltre, deve essere chiaro con quale account viene effettuato l’accesso all’API e quali diritti ha questo account.

Per ambienti produttivi si dovrebbe verificare:

• Viene utilizzato un account API o di servizio dedicato?
• L’account ha solo le autorizzazioni necessarie?
• È chiaramente documentato quale persona o team è responsabile dell’account?
• La password o il segreto sono conservati in modo sicuro?
• L’accesso viene rimosso quando l’integrazione non è più utilizzata?
• Le modifiche sono tracciabili tramite log di audit?

Gli account amministrativi condivisi sono problematici per i processi API. Se più sistemi o persone utilizzano lo stesso account, la tracciabilità si indebolisce. Per le analisi dei cambiamenti è rilevante verificare i log di audit di Sophos Firewall.

Per un account API dedicato, un processo ristretto è meglio di un full admin copiato rapidamente. Configurare in sicurezza amministratori e profili Sophos Firewall spiega la pianificazione generale degli account personali e dei profili limitati; per le automazioni rimane determinante l’account di servizio separato descritto qui. Nella documentazione Sophos questo blocco compare come Allow API access to administrators: non viene autorizzata solo la sorgente, anche l’amministratore o il profilo deve avere l’accesso corretto.

1. Creare un profilo amministratore con i diritti necessari in Profiles > Device access.
2. Creare un utente amministratore per il processo API in Authentication > Users.
3. Assegnare il profilo amministratore corretto.
4. Se l’accesso serve solo temporaneamente, limitare Access time.
5. Se possibile, limitare Login restriction for device access alle sorgenti previste.
6. Poi consentire API access e Device Access per la sorgente corretta.

Nell’esempio ufficiale, il profilo riceve Read-write per Objects e Network. Non è una raccomandazione generale: per le integrazioni di sola lettura e le altre attività API, le aree non necessarie restano su None o Read-only; l’accesso in scrittura viene concesso solo dopo un test di lettura controllato.

Sophos supporta le API ufficiali e gli script di esempio non modificati. Il supporto tecnico Sophos non fornisce consulenza né troubleshooting per integrazioni personalizzate; Sophos rimanda questo lavoro al Sophos Partner responsabile o a Sophos Professional Services. Integrazioni, wrapper e automazioni proprie richiedono quindi un responsabile interno, test e un concetto di rollback. “Funziona in laboratorio” non è sufficiente per operazioni di scrittura in produzione.

MFA e utenti API dopo SFOS 22

La MFA è importante per gli accessi amministrativi interattivi. Per processi API e di automazione, però, bisogna pianificare consapevolmente come deve funzionare l’autenticazione. Uno script, uno strumento di monitoraggio o un sistema di integrazione non può semplicemente inserire un codice OTP se l’utente impone la MFA.

L’attuale lista Known Issues documenta NC-177609 per SFOS 22.0.0 GA Respin Build 411: dopo un upgrade, le modifiche di configurazione tramite API possono fallire per gli utenti migrati se la MFA è attiva e non viene fornito un one-time token. Gli utenti non migrati mantengono il comportamento precedente fino all’onboarding MFA. Il workaround ufficiale consiste nell’usare un account API separato senza MFA oppure nell’escluderlo dalla MFA. Ciò non giustifica la disattivazione della MFA per gli amministratori interattivi; per le build successive, controllare prima Release Notes e Known Issues.

Approccio consigliato:

1. Usare un account di servizio dedicato per i processi API.
2. Assegnare all’account solo i diritti necessari.
3. Limitare inoltre API access a IP Hosts fissi o reti di management.
4. Verificare se la MFA è tecnicamente e operativamente sensata per questo account.
5. Se la MFA non è praticabile per l’account API, controllarlo in modo particolarmente stretto tramite sorgente, diritti, archiviazione dei secret e audit trail.
6. Dopo un upgrade a SFOS 22, testare tutti i processi API con operazioni di lettura e scrittura.

⚠️ Gli utenti API senza MFA non sono un lasciapassare per diritti ampi. Se per motivi tecnici un account API deve funzionare senza MFA, IP sorgente, diritti, archiviazione password, responsabilità e auditabilità devono essere controllati più rigorosamente.

Questo punto è particolarmente importante per automazioni che non leggono soltanto, ma modificano anche la configurazione.

Prima di modifiche API in produzione, verificare almeno tre aspetti:

• È disponibile un backup Sophos Firewall aggiornato.
• L’account API previsto può eseguire correttamente una query di lettura innocua.
• Per modifiche massive preparate con Sophos Firewall Config Studio, le chiamate API o curl generate funzionano con l’account previsto.

Distinzione da Device Access

Il controllo dell’accesso all’API non è lo stesso di Device Access, ma i due controlli interagiscono. Device Access controlla i servizi firewall locali come WebAdmin, SSH, User Portal, VPN Portal, DNS o Ping. Le impostazioni di accesso all’API controllano inoltre quali host IP possono usare l’API XML. Importante: le autorizzazioni Device Access per la WebAdmin Console valgono anche per gli accessi API.

In pratica significa che l’accesso all’API deve essere consentito, la fonte deve essere ammessa nelle impostazioni di accesso all’API e l’accesso locale di gestione alla firewall non deve essere bloccato da Device Access. Ogni livello limita una parte diversa della superficie di attacco:

• Configurare correttamente Device Access: servizi firewall locali come WebAdmin, SSH, User Portal, VPN Portal, DNS o Ping
• Controllo dell’accesso all’API: host IP che possono usare anche l’API XML
• Attivare MFA per Sophos Firewall WebAdmin, VPN Portal e Remote Access: accessi interattivi per WebAdmin, VPN Portal e Remote Access
• Amministratori nominati e ruoli chiari: Tracciabilità e raggio di danno di account amministrativi e di servizio

Se una rete amministrativa può utilizzare WebAdmin, SSH e API, questa rete dovrebbe essere particolarmente ben protetta. Un client compromesso nella rete di gestione è altrimenti un ingresso diretto nella gestione del firewall.

Per l’accesso dalla WAN, non si dovrebbe abilitare HTTPS/WebAdmin per l’intera zona WAN. Se l’accesso esterno all’API o all’amministrazione è realmente necessario, va usata una Local service ACL exception rule con Source strettamente limitata, Service HTTPS appropriato, posizione della regola definita e periodo documentato.

HA: verificare l’accesso dopo un failover

In un cluster HA, la configurazione del firewall viene sincronizzata dal Primary all’Auxiliary; il link HA dedicato e le Administration Ports non vengono sincronizzati. I client API devono quindi usare il nome del cluster o l’indirizzo di interfaccia condiviso previsti, senza dipendere inconsapevolmente da un indirizzo di amministrazione specifico di un nodo.

Dopo la configurazione HA, un cambio di certificato o un failover, ripetere un test di lettura e un test negativo. Controllare la risoluzione DNS, il nome del certificato, l’IP sorgente, la porta admin, API access e Device Access. Un oggetto host sincronizzato non dimostra da solo che l’intero percorso di rete e TLS funzioni dopo il cambio di ruolo.

Operatività e revisione

L’accesso all’API dovrebbe essere regolarmente verificato. Soprattutto dopo migrazioni, cambi di fornitori, progetti di automazione o aggiornamenti del firewall, spesso rimangono fonti vecchie.

Domande di revisione sensate:

• Quali host IP possono attualmente utilizzare l’accesso all’API?
• Ci sono oggetti con il prefisso apiconfig?
• Questi oggetti sono ancora necessari?
• I nomi e le descrizioni corrispondono allo scopo effettivo?
• Ci sono responsabili documentati?
• Gli accessi API sono considerati in un processo di cambiamento o audit?
• C’è un backup aggiornato prima di modifiche basate su API più grandi?

Prima delle modifiche basate su API, dovrebbe sempre essere disponibile un backup. L’articolo Creare o ripristinare un backup di Sophos Firewall descrive a cosa prestare attenzione per backup, ripristino e compatibilità.

Errori tipici

• API access consentito per un’intera rete client: Ogni client compromesso in quella rete può raggiungere l’API.
• Vecchi oggetti apiconfig non verificati: Le autorizzazioni legacy migrate restano attive senza essere notate.
• L’account di servizio usa pieni diritti admin: Un secret compromesso ha un raggio d’impatto inutilmente ampio.
• L’automazione API usa un admin con MFA obbligatoria: Script o strumento possono fallire nelle operazioni di scrittura dopo un upgrade SFOS.
• Porta errata nello strumento: La porta HTTPS admin è stata cambiata, ma lo strumento continua a usare la vecchia porta.
• Ci si aspetta logica REST: Lo strumento invia metodi REST invece di payload XML tramite HTTP POST a APIController.
• È stato controllato solo lo stato HTTP: L’operazione API effettiva non è riuscita, anche se il trasporto ha avuto successo. Valutare <Response> e <Status>.
• Set è stato inviato senza operazione: SFOS tratta la richiesta come add anche se era previsto un aggiornamento.
• Non è possibile importare impostazioni o token MFA: Il payload deve contenere l’elemento vuoto <tokenid/>.
• Non è possibile eliminare un utente: Nel payload <Remove>, specificare il nome utente esatto come <Name>username</Name>. Prima di inviare la richiesta, verificare account, dipendenze, backup e rollback.
• Lo Usage Count è stato interpretato come elenco completo delle dipendenze: La statistica restituisce numero e nome, ma non le regole o i profili coinvolti.
• Live User connesso senza correlare la sessione: Nome utente, IP e MAC non corrispondono alla sessione reale e le regole basate sugli utenti possono quindi prendere decisioni errate.
• L’archivio dei certificati è stato salvato senza protezione: L’export API può contenere Private Key e non deve essere archiviato in Download, ticket o percorsi condivisi.
• IP temporaneo del fornitore resta attivo: L’accesso esterno rimane possibile più a lungo del previsto.
• Nessuna documentazione dello scopo: Gli amministratori successivi non sanno se l’autorizzazione serve ancora.
• Modifiche API senza backup: Un’automazione errata è più difficile da annullare.

Risoluzione dei problemi

Se uno strumento non riesce a raggiungere l’API XML, si dovrebbe verificare in modo strutturato:

1. L’indirizzo IP di origine è corretto dal punto di vista del firewall?
2. La fonte è consentita come host IP, intervallo IP o rete?
3. Dopo un aggiornamento è stato creato un oggetto apiconfig, ma non è stato adattato correttamente?
4. Device Access consente l’accesso locale WebAdmin/API da questa zona?
5. Lo strumento usa l’indirizzo firewall corretto e la porta HTTPS di amministrazione corretta?
6. Nome utente, password o segreto sono corretti?
7. L’account ha i diritti necessari?
8. L’account impone MFA, anche se lo strumento non può fornire un token monouso?
9. Ci sono effetti di routing, NAT o proxy tra lo strumento e il firewall?
10. L’accesso è stato rimosso intenzionalmente tramite una misura di indurimento?
11. Il test è stato eseguito dal sistema sorgente corretto o solo dal client admin?

Se una modifica API ha effetti imprevisti, prima di tutto salvare l’ultimo backup e poi controllare il trail di audit, il confronto di Config Studio e gli oggetti del firewall interessati. In caso di problemi di traffico live, Log Viewer e Packet Capture sono più utili dell’API stessa.

In caso di operazione XML rifiutata o errata, salvare prima <Response> e <Status>. Controllare poi apiparser.log, validation.log e validationError.log in Diagnostics > Troubleshooting logs; Sophos associa questi file alla traduzione e alla convalida dell’API. File di servizio e log di Sophos Firewall spiega come filtrarli ed esportarli. Rimuovere i secret prima di condividere un estratto di log.

Lista di controllo

Prima dell’attivazione:

• Documentare lo scopo dell’accesso all’API.
• Determinare chiaramente il sistema di origine.
• Creare un oggetto host IP con un nome significativo.
• Verificare l’account di servizio e le autorizzazioni.
• Stabilire consapevolmente il comportamento MFA dell’account API.
• Stabilire un processo di backup e rollback.
• Definire un metodo di test senza perdita di segreti.
• Documentare l’operazione XML prevista e il <Status> atteso.

Durante l’operatività:

• Consentire l’accesso all’API solo per fonti definite.
• Non consentire reti client, ospiti o IoT ampie.
• Controllare gli oggetti apiconfig dopo gli aggiornamenti.
• Controllare gli accessi dei fornitori nel tempo e nel contesto.
• Conservare i segreti in modo protetto e rinnovarli in caso di cambiamento di personale o strumento.
• Ruotare i segreti se sono finiti nella cronologia della shell, nei ticket o in archivi non sicuri.
• Testare operazioni di lettura e scrittura API dopo aggiornamenti SFOS.
• Controllare Object Usage e le configurazioni dipendenti prima di operazioni update o remove.
• Validare i login Live User via API con API client, la decisione della regola e un logout corretto.
• Gestire file di certificato, Private Key ed export API solo in percorsi protetti.

Durante la revisione:

• Verificare regolarmente le fonti API consentite.
• Rimuovere gli host IP non più necessari.
• Confrontare le modifiche con il trail di audit e i ticket di cambiamento.
• Testare i processi di automazione dopo gli aggiornamenti del firmware.

FAQ