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. Negli ambienti con versioni SFOS diverse, verificare quindi la versione prima di riutilizzare senza modifiche una guida o uno script.

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. Il riferimento XML generale documenta solo il nome dell’oggetto Name, con i criteri =, != e like e la sintassi <key name="Name" ...>. Le statistiche Object Usage, documentate separatamente, supportano altre chiavi e altri criteri; non estenderli alle normali query sugli oggetti.

Per le operazioni di scrittura, non fare affidamento sull’omissione di operation in <Set>. La documentazione descrive il valore omesso in modo contraddittorio: il riepilogo XML indica add, mentre il riferimento XML completo per SFOS 22 e 23 indica Add seguito da Update. Da queste descrizioni non si può dedurre né un comportamento predefinito di sola aggiunta verificato, né un comportamento di upsert o sovrascrittura valido in generale. Usare solo un’operazione esplicita confermata da API help per l’oggetto interessato e la build installata; se questo punto resta irrisolto, non eseguire la richiesta di scrittura e chiedere chiarimenti al Support. APIXMLTags documenta l’attributo alfanumerico facoltativo transactionid su <Set>; facilita la correlazione tra richiesta e risposta. Per le operazioni specializzate, fa fede l’esempio dell’oggetto in API help della build SFOS installata. L’esempio del certificato colloca transactionid su <Certificate>; questo caso particolare non costituisce una regola generale per il suo posizionamento sui tag degli oggetti all’interno di <Set>.

APIVersion in <Request> è specifico della versione: il riferimento XML per SFOS 22 mostra 2200.1, quello per SFOS 23 mostra 2300.1. Sono esempi della documentazione, non una raccomandazione a usare quel valore su qualsiasi build. Secondo il riferimento, APIVersion in <Response> contiene il valore indicato nella richiesta; se la richiesta lo omette, viene considerata la versione API del firmware attivo. Al tempo stesso, la sezione relativa alla richiesta definisce necessaria l’indicazione della versione, mentre gli esempi successivi la omettono. Questa incoerenza interna non dimostra né un obbligo universale né un’assenza universale di obbligo nel comportamento in esecuzione. I tag degli oggetti, gli attributi, i codici di stato e le configurazioni di esempio esatti devono quindi provenire da API help della build SFOS installata; confermare la versione e la compatibilità degli oggetti prima dell’uso e non trasferire payload 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.

I valori seguenti sono codici di stato XML documentati nell’attributo code di <Status>, non codici di stato HTTP. Il messaggio e la sezione Status Message Information dell’oggetto interessato nella build installata ne determinano l’interpretazione esatta:

• 200: configurazione applicata correttamente; 201: successo solo parziale. Con 203, l’operazione è riuscita, ma alcune configurazioni non sono state applicate; il riferimento invita a contattare il Support. 204–210 indicano un fallimento parziale, non un successo completo.
• 211–215: avvisi; 216: successo con spiegazione specifica per l’oggetto. Per entrambi, leggere la relativa sezione Status Message Information, anziché considerare tutti i valori XML 2xx come conferma della completa applicazione della configurazione.
• 500: operazione non eseguibile sull’oggetto; 501: convalida dei parametri non riuscita; 502: nome già presente; 503: stessi parametri già presenti. Con 504–510, un riferimento da un altro oggetto impedisce l’eliminazione; controllare prima le dipendenze. Per 511–520, il riferimento richiede di chiedere chiarimenti al Support.
• 521: richiesta incompatibile con la versione API attuale; 522–525: limite degli oggetti raggiunto; 526: record assente; 528: oggetto predefinito non modificabile; 529: XML non valido per l’oggetto; 530: versione API non supportata per questo oggetto. 541–590 sono errori specifici dell’oggetto, con ulteriori informazioni in Status Message Information; 599 indica l’assenza dell’autorizzazione a creare o modificare.

In caso di successo parziale o avvisi, confrontare la risposta con lo stato effettivo dell’oggetto prima di un nuovo tentativo di scrittura; non presumere che la configurazione sia stata applicata integralmente o che riprovare sia innocuo. Condividere con il Support solo risposte e log ripuliti dai dati sensibili.

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.

Quanto alla provenienza, il riferimento XML descrive SecureStorageMasterKey come la chiave principale del firewall di origine da cui è stata esportata la configurazione. Secondo il riferimento, senza questa chiave non vengono importate le informazioni sensibili, come le password, né le impostazioni che ne dipendono; se la chiave non è disponibile, indica di rivolgersi all’amministratore predefinito con nome utente admin. Token e i valori delle password cifrate provengono dal risultato Get/esportazione documentato. La dicitura hashform="mode1", ad esempio su <Password>, identifica in quel contesto un valore di password cifrato; il riferimento indica come alternativa una password non cifrata. Si tratta di informazioni sulla provenienza e sull’interpretazione, non di un’autorizzazione a copiare testo cifrato, token o marcatori tra oggetti e build arbitrari. XML <Get> non autorizza automaticamente l’uso del metodo HTTP GET. Qui non viene introdotto alcun nuovo comando di importazione o esportazione; restano vincolanti la conferma specifica per oggetto e build e l’obbligo, indicato di seguito, di interrompersi se i dati da fornire non sono stati chiariti.

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.

In WebAdmin, Usage è disponibile per interfacce, zone, gateway, profili SD-WAN, host e servizi. Il contatore viene aggiornato una volta al giorno; prima di una modifica, aggiornarlo con il comando accanto a Usage. Fare clic sul contatore dell’oggetto, espandere la categoria interessata e aprire la regola o policy indicata per sostituire o rimuovere lì l’oggetto. Questa operazione elimina il riferimento, non automaticamente l’oggetto stesso. Alcune configurazioni di gateway WAN e CLI non sono modificabili dalla finestra Object Usage; usare la relativa pagina di configurazione o la CLI.

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

In Postman, creare una richiesta con New > HTTP Request, assegnarle un nome con Save e salvarla in una collection. Usare POST e l’endpoint APIController indicato sopra con la porta WebAdmin effettiva. L’app desktop invia per impostazione predefinita da questo computer; autorizzare il suo IP di origine così come viene visto dal firewall. In Body > form-data, creare una voce con nome di tipo File per il certificato e una per la chiave privata, selezionando i file locali; la terza voce, reqxml, è di tipo Text. Conservare i file in un percorso locale con accesso limitato, non in una cartella sincronizzata con il cloud.

L’esempio Postman usa C:/Users/[yourname]/Postman/files come percorso Windows. Sostituire [yourname] e verificare le restrizioni di accesso e l’accesso locale ai file dell’app; questo percorso non è un parametro generale di SFOS.

⚠️ Payload incompleto: non eseguire. Il seguente payload per un certificato PEM nel campo reqxml omette operation su <Set>. A causa delle descrizioni contraddittorie del comportamento predefinito, non inviarlo, nemmeno per creare un nuovo certificato. Chiarire prima l’operazione esplicita e il payload completo del certificato per l’oggetto e la build installata tramite API help o con il Support. Tutti i nomi di account, secret, oggetti e file sono valori di esempio:

<Request><Login><Username>api-certificates</Username><Password>SECRET</Password></Login><Set><Certificate transactionid="10"><Name>TestCertificate</Name><Action>UploadCertificate</Action><CertificateFormat>pem</CertificateFormat><CertificateFile>TestCertificate.pem</CertificateFile><PrivateKeyFile>TestCertificate.key</PrivateKeyFile></Certificate></Set></Request>

CertificateFile e PrivateKeyFile identificano i file selezionati per il caricamento. L’attributo facoltativo transactionid consente qui di correlare richiesta e risposta. L’assenza di operation non dimostra né la creazione né l’aggiornamento; l’esempio del produttore, conservato senza modifiche, resta bloccato finché non vengono chiariti i requisiti specifici dell’oggetto e della build. In particolare, per un certificato esistente, verificare il payload di aggiornamento esatto in API help, senza reinviarlo alla cieca. Inviare un payload confermato solo dopo questi chiarimenti; esaminare poi la risposta in Body e quindi controllare il certificato di destinazione in WebAdmin.

I certificati sono un caso particolare perché oltre all’XML vengono trasferiti anche file. Per un payload di creazione o aggiornamento confermato, usare nell’app desktop Postman una richiesta form-data con tre parti: file del certificato, file della chiave privata e reqxml con l’operazione esplicita confermata su <Set> e i relativi campi <Certificate>. La struttura abbreviata dell’esempio bloccato non è un modello eseguibile. 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 account 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.

Per un’esportazione CLI autorizzata, definire un percorso locale di output esplicito per filename.tar. Prima dell’estrazione, controllare le voci con tar -tf filename.tar; non accettare percorsi o collegamenti inattesi. Estrarre con tar -xvf filename.tar solo all’interno di una directory di destinazione vuota e con accesso limitato. filename.tar è un segnaposto. L’output di questi comandi può rivelare nomi di file sensibili e non deve finire in log pubblici.

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 account con pieni privilegi amministrativi creato frettolosamente. 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. Per l’accesso temporaneo all’API, assegnare un responsabile e pianificare la rimozione manuale dell’account API dedicato e/o dell’autorizzazione della sorgente dedicata all’API al termine della finestra approvata; verificare poi che tale accesso all’API sia stato revocato senza disabilitare gli accessi condivisi legittimi. Access Time per gli utenti ordinari controlla l’accesso a internet; Schedule for device access per gli amministratori controlla gli accessi a WebAdmin. Nessuna delle due impostazioni è documentata qui come meccanismo di scadenza automatica dell’accesso all’API XML: non fare affidamento su di esse per terminare l’accesso all’API. Se è necessario applicare una pianificazione, ottenere prima una conferma nella documentazione primaria della build installata o tramite una verifica autorizzata.
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.

I diritti del profilo non autorizzano l’origine: I profili in Profiles > Device access si applicano a WebAdmin e API; l’ACL dei servizi locali in Administration > Device access è un controllo distinto. I profili predefiniti non sono modificabili. Usare Edit per consultarne i diritti; creare e modificare un profilo personalizzato per adattarli. Prima di eliminare un profilo, rimuoverne l’assegnazione da tutti gli amministratori. Ogni area supporta None, Read-only e Read-write. Con None, la configurazione non è visibile in WebAdmin né recuperabile tramite API: l’assenza di dati API non indica necessariamente un errore di rete.

I profili predefiniti hanno ambiti diversi: Administrator, incluso l’account predefinito admin, ha accesso completo a WebAdmin e CLI, tutti i tipi di richiesta API e può creare amministratori. Audit admin ha Read-write per log e report; Crypto admin, per i certificati di sicurezza. HAProfile ha accesso Read-only al dispositivo Auxiliary se HA è configurata. Security admin ha Read-write per tutte le funzionalità tranne profili, log e report. Non presumere che uno di questi sia un profilo API con privilegi minimi; controllare i diritti effettivi sull’oggetto necessario.

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 al 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 inviato senza operazione: Non fare affidamento su un comportamento predefinito e non ripetere l’invio alla cieca. Le descrizioni documentate si contraddicono; prima di qualsiasi scrittura, confermare l’operazione esplicita per l’oggetto e la build, altrimenti interrompersi.
• 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 hardening?
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 > Tools > 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