Vai al contenuto
Avanet
Accedi

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

Sophos Firewall

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 autenticazione, riferimenti agli oggetti e schema dell’endpoint scelto. I nomi somigliano all’interfaccia, ma non sono sempre identici.

Stato della documentazione al 29 ottobre 2026, SFOS 23.0: Il riferimento API generato indica la base https://<firewall-host>:<port>/api/firewall-config/v1. La pagina introduttiva generale indica invece un percorso senza /api e mostra persino APIController per il primo richiamo. Non è un’indicazione affidabile per tentare percorsi diversi. Per il proprio firewall vale l’URL server completo dello schema scaricato; senza un’operazione corrispondente nello schema locale, il pilota seguente non viene eseguito.

Primo richiamo in sola lettura: interrogare gli hotfix applicati

L’operazione ufficiale GET /system/security-updates legge gli aggiornamenti di sicurezza hotfix applicati. Non avvia né un aggiornamento né una modifica di configurazione. Prima della richiesta verificare nello schema locale che esista esattamente questo percorso con metodo GET, quindi acquisire l’URL base completo.

Esempio documentato, non provato praticamente su un firewall: Per questo stato di verifica non erano disponibili né un firewall di test autorizzato né una chiave API dedicata. Verificare stato HTTP e contenuto della risposta prima di utilizzarne i dati.

L’esempio viene eseguito con Python 3 sull’host amministrativo o di automazione approvato, non nella Device Console. firewall.example.com, la porta 4444 e il percorso del file CA sono valori da sostituire. L’hostname deve corrispondere al certificato; 4444 è soltanto la porta admin HTTPS scelta in questo esempio. Il file PEM contiene la CA emittente attendibile, non materiale di chiave privata. Con una catena di certificazione già attendibile nel truststore Python si può usare ca_file = None. Non fidarsi di una CA scaricata arbitrariamente.

python3 - <<'PY'
import getpass
import json
import ssl
import urllib.error
import urllib.request

# Vollständige servers-URL des lokalen Schemas übernehmen.
# Dieser Beispielpfad entspricht der generierten Referenz.
api_base = "https://firewall.example.com:4444/api/firewall-config/v1"
ca_file = "/pfad/zur/management-ca.pem"
if not api_base.startswith("https://"):
    raise SystemExit("Nur die bestätigte HTTPS-Server-URL verwenden.")
context = ssl.create_default_context(cafile=ca_file)

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

opener = urllib.request.build_opener(
    NoRedirect(), urllib.request.HTTPSHandler(context=context)
)
api_key = getpass.getpass("Freigegebener REST-API-Schlüssel: ")
request = urllib.request.Request(
    api_base.rstrip("/") + "/system/security-updates",
    method="GET",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer " + api_key,
    },
)
try:
    with opener.open(request, timeout=30) as response:
        status = response.status
        body = response.read()
except urllib.error.HTTPError as error:
    raise SystemExit(f"HTTP {error.code}: Ursache vor erneutem Aufruf prüfen.")
except urllib.error.URLError as error:
    raise SystemExit(f"Verbindungs- oder TLS-Fehler: {error.reason}")

print(f"HTTP {status}")
if status != 200 or not body:
    raise SystemExit("Noch keine Abnahme: Status und Body mit dem Schema abgleichen.")
try:
    data = json.loads(body)
except (json.JSONDecodeError, UnicodeDecodeError):
    raise SystemExit("Kein gültiger JSON-Body; Zielpfad und Antwort prüfen.")
print(json.dumps(data, indent=2, ensure_ascii=False))
PY

La chiave viene richiesta senza mostrarla, non viene memorizzata come argomento del comando o letterale nello script. Il client accetta solo HTTPS e non segue redirect: con una risposta 3xx inattesa si arresta invece di inviare l’header Bearer a un’altra destinazione. Durante il pilota non attivare log di debug della shell o del client; anche i dati del dispositivo stampati non vanno inseriti nei ticket senza verifica. Per un successivo job non interattivo si usa il Secret Store previsto.

Interpretare risposta ed errori tipici

Per una richiesta riuscita è atteso HTTP 200. I dati dovrebbero descrivere gli hotfix di sicurezza applicati. Confrontare numero e contenuto con lo stato noto del dispositivo e lo schema di risposta di quel firmware; un body JSON valido, da solo, non dimostra né completezza né un particolare livello di patch. Utilizzare i nomi dei campi e i tipi definiti nello schema di risposta della build installata.

  • 401: Il riferimento richiede autenticazione. Verificare header Bearer, chiave corretta, scadenza ed eliminazione senza registrare il segreto.
  • 403: Il riferimento richiede un’autorizzazione. Controllare account creatore e suoi diritti per l’operazione, anziché concedere indiscriminatamente pieni diritti amministrativi.
  • 3xx: Non seguire il redirect. Controllare URL server confermato, eventuale proxy e sue regole di redirect; non trasferire la chiave alla destinazione della deviazione.
  • 404: Per questa operazione 404 non è documentato come risposta funzionale. Controllare porta admin, base completa dello schema, percorso, firmware ed eventuale proxy. Non passare automaticamente all’endpoint XML o a un secondo prefisso REST.
  • 400 o 500: Il riferimento distingue richiesta non valida ed errore interno del server. Verificare metodo e schema oppure stato del dispositivo e diagnostica depurata.
  • Nessuno stato HTTP: Esaminare DNS, route, connessione, timeout e catena TLS. Con errori di certificato correggere hostname, catena di fiducia e validità; non disattivare la verifica con -k o un contesto SSL non verificato.

Test di lettura e controllo operativo

Verificare prima il percorso consentito dall’host di automazione reale. Per il test negativo della sorgente, eseguire la stessa richiesta in sola lettura soltanto da un ulteriore host di test approvato già esterno all’elenco delle sorgenti API. Non deve ricevere dati di configurazione o hotfix. Lo specifico stato di rifiuto non è garantito; una risposta con dati indicherebbe il fallimento del test negativo. Non rimuovere autorizzazioni di produzione e non usare reti altrui per la prova.

Anche il test negativo TLS avviene senza ridurre le protezioni: un hostname di test esplicitamente approvato e deliberatamente non corrispondente al certificato deve fallire nella verifica del certificato prima di ricevere dati API. Non modificare il DNS produttivo e non aggiungere autorizzazioni di rete. Senza un nome di test adatto, questa parte dell’accettazione resta aperta. Documentare momento, host sorgente, firmware, versione dello schema, risultato HTTP/TLS e confronto funzionale dei dati, mai la chiave.

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.