Sophos Firewall REST API: toegang en API-sleutels veilig beheren

De lokale REST API in SFOS 23.0 laat automatisering configuratie rechtstreeks op de firewall lezen en wijzigen. Begin met een aparte beheerder met beperkte rechten, sta alleen de automatiseringshost toe, genereer als dat account een sleutel en controleer eerst een leesverzoek. Beschikbare documentatie bewijst geen GA-datum of ondersteuning op oudere firmware.

Drie interfaces, drie identiteiten

Lokale REST API: de API-sleutel van een firewallbeheerder is het Bearer-token; rechten komen uit het beheerdersprofiel.
Lokale XML API: XML-payloads en beheerdersgegevens, doorgaans via HTTP POST naar APIController. XML <Get> is geen REST-verzoek.
Sophos Central-configuratie-API: cloud-serviceprincipal, kortlevend toegangstoken, tenant en regionale API-host. Een lokale sleutel vervangt deze gegevens niet.

Toegang en beheerder voorbereiden

Maak onder Profiles > Device access een profiel met alleen benodigde functierechten; inventarisatie heeft passende leesrechten nodig. Maak onder Authentication > Users een aparte beheerder met dit profiel. Beheerders en profielen plannen legt de rollen uit. Gebruik geen persoonlijk account of de standaard-admin met volledige rechten voor taken.
Definieer onder Hosts and services > IP host de echte host, bijvoorbeeld api-inventory met 192.0.2.20. Vervang naam en documentatieadres. Eén vaste bron is beperkter dan een heel beheernetwerk; bij NAT telt de bron die de firewall ziet.
Schakel onder Administration > API access het standaard uitgeschakelde API access in, selecteer uitsluitend benodigde bronnen bij Allowed IP hosts en klik op Apply. Adressen, bereiken en netwerken zijn mogelijk, maximaal 64 items. Controleer apiconfig-bronnen die bij een upgrade naar SFOS 22.0 of later zijn gemigreerd.
Controleer onder Administration > Device access WebAdmin vanuit de betreffende zone. Device Access en de API-bronnenlijst zijn aparte controles; open WAN-toegang niet breed.

Sleutel genereren en eenmalig opslaan

Meld aan als de aparte beheerder. Klik onder Administration > API access > REST API keys op Add API key, voer een herkenbare naam zoals inventory-prod-2026-10 in en genereer met Add API key.

Vóór Close: kopieer de sleutel naar de beveiligde secret store van de taak. Na sluiten van het venster wordt hij nooit opnieuw getoond. Plaats hem niet in screenshots, tickets, repositorybestanden of onbeveiligde collectie-exports.

Een sleutel is één jaar geldig en erft de rechten van de maker. Beheerders maken en verwijderen hun eigen sleutels; alle beheerders zien de lijst, maar kunnen het geheim niet opnieuw ophalen. De standaard-admin kan ook sleutels van anderen verwijderen. Limieten: 10 sleutels per beheerder, 1024 totaal. Deel sleutels niet tussen beheerders.

Verzoek vanuit het firewallschema opbouwen

Download onder REST API help de OpenAPI.yaml van deze firewall en importeer die in Postman of Swagger. Controleer onder REST API guide authenticatie, objectverwijzingen en het schema van het gekozen endpoint. Namen lijken op de UI, maar zijn niet altijd gelijk.

Documentatiestand 29 oktober 2026, SFOS 23.0: De gegenereerde API-referentie noemt de basis https://<firewall-host>:<port>/api/firewall-config/v1. De algemene introductie noemt daarentegen een pad zonder /api en toont bij de eerste aanroep zelfs APIController. Dat is geen betrouwbare instructie om verschillende paden uit te proberen. Voor de eigen firewall geldt de volledige server-URL uit het gedownloade schema; zonder passende lokale operatie wordt de onderstaande pilot niet uitgevoerd.

Eerste leesaanroep: toegepaste hotfixes opvragen

De officiële operatie GET /system/security-updates leest de toegepaste hotfix-beveiligingsupdates. Ze start geen update of configuratiewijziging. Controleer vóór de aanroep in het lokale schema of precies dat pad met methode GET bestaat en neem de volledige basis-URL over.

Controleer vóór de aanvraag de lokale OpenAPI-operation, de toegangsrechten en de geldigheid van de API-sleutel.

Het voorbeeld draait met Python 3 op de goedgekeurde beheer- of automatiseringshost, niet in de Device Console. firewall.example.com, poort 4444 en het CA-bestandspad zijn vervangwaarden. De hostnaam moet bij het certificaat passen; 4444 is alleen de hier gekozen HTTPS-beheerpoort. Het PEM-bestand bevat de vertrouwde uitgevende CA, geen privésleutelmateriaal. Bij een certificaatketen die al in de Python-truststore wordt vertrouwd, kan ca_file = None worden gebruikt. Vertrouw niet op een willekeurig gedownloade CA.

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

De sleutel wordt verborgen opgevraagd, niet als opdrachtargument of letterlijk in het script opgeslagen. De client accepteert alleen HTTPS en volgt geen omleidingen: bij een onverwacht 3xx-antwoord stopt hij in plaats van de Bearer-header naar een ander doel te sturen. Schakel tijdens de pilot geen shell-/clientdebuglogging in; ook de weergegeven apparaatgegevens horen niet ongecontroleerd in tickets. Voor een onbeheerde job wordt later de bedoelde secretstore gebruikt.

Antwoord en typische fouten beoordelen

Bij een geslaagde aanvraag wordt HTTP 200 verwacht. De gegevens moeten de toegepaste hotfix-beveiligingsupdates beschrijven. Vergelijk aantal en inhoud met de bekende apparaatstand en het antwoordschema van deze firmware; een geldige JSON-body alleen bewijst geen volledigheid of bepaalde patchstand.

401: De referentie vereist authenticatie. Controleer Bearer-header, juiste sleutel, verloop en verwijdering zonder het geheim te loggen.
403: De referentie vereist toestemming. Controleer makeraccount en diens rechten voor de operatie in plaats van algemeen volledige beheerdersrechten te verlenen.
3xx: Niet doorsturen. Controleer de bevestigde server-URL, een eventuele voorliggende proxy en diens omleidingsregels; neem de sleutel niet over naar het omleidingsdoel.
404: Voor deze operatie is 404 niet als functioneel antwoord gedocumenteerd. Controleer beheerpoort, volledige schemabasis, pad, firmware en een eventuele voorliggende proxy. Schakel niet automatisch naar het XML-endpoint of een tweede REST-prefix.
400 of 500: De referentie onderscheidt een ongeldige aanvraag en een interne serverfout. Controleer methode en schema, respectievelijk apparaatstatus en geschoonde diagnostiek.
Geen HTTP-status: Onderzoek DNS, route, verbinding, timeout en TLS-certificaatketen. Corrigeer bij certificaatfouten hostnaam, vertrouwensketen en geldigheid; schakel de controle niet uit met -k of een ongecontroleerde SSL-context.

Leestest en operationele controle

Controleer eerst het toegestane pad vanaf de echte automatiseringshost. Voer voor de negatieve brontest dezelfde zuivere leesaanvraag alleen uit vanaf een aanvullend goedgekeurde testhost die al buiten de API-bronnenlijst valt. Die mag geen configuratie- of hotfixgegevens ontvangen. De concrete weigeringsstatus is niet gegarandeerd; een antwoord met gegevens zou een mislukte negatieve test zijn. Verwijder geen productietoestemming en gebruik geen vreemd netwerk voor de test.

Ook de negatieve TLS-controle gebeurt zonder bescherming te verlagen: een doelbewust niet bij het certificaat passende, uitdrukkelijk goedgekeurde testhostnaam moet vóór ontvangst van API-gegevens stranden op de certificaatcontrole. Wijzig daarvoor geen productie-DNS en maak geen extra netwerktoestemming aan. Zonder geschikte testnaam blijft dit acceptatieonderdeel open. Documenteer tijdstip, bronhost, firmware, gebruikte schemaversie, HTTP-/TLS-resultaat en inhoudelijke gegevensvergelijking, nooit de sleutel.

Bereid vóór schrijfacties een back-up en herstelpad voor, test één kleine goedgekeurde wijziging en controleer het doel in WebAdmin en de Audit Trail. Lees na een schrijf-timeout eerst de echte objectstatus vóór opnieuw proberen. Trage queries, zoals IPS-signaturen, kunnen langere clienttimeouts vereisen.

Verloop, vervanging en verwijdering

Documenteer per sleutel account, taak, toegestane bron, aanmaakdatum, vervaldatum en verantwoordelijk team, nooit de sleutel. Plan herinneringen en vervanging vóór verlopen; ga niet uit van automatische verlenging. Reserveer een vrije sleutelplaats voor overlappende rotatie. Bij 10 eigen sleutels of 1024 totaal eerst met de eigenaar overbodige sleutels bepalen, niet willekeurig actieve taken intrekken.

Genereer voor geplande vervanging een nieuwe sleutel met hetzelfde account, sla hem veilig op, pas de taak aan en controleer een leesverzoek. Verwijder daarna de oude eigen sleutel en controleer dat de nieuwe werkt en de oude geen toegang meer geeft. Beschouw verwijderde sleutels niet als herstelbaar. Vervang ook een sleutel waarvan de eenmalige weergave verloren ging. Bij vermoedelijke blootstelling direct intrekken, ook als dit onderbreking veroorzaakt. Betrek voor andermans sleutel de eigenaar van de standaard-admin. Verwijder bij buitengebruikstelling sleutels en overbodige API-bronnen; controleer gedeelde bronnen eerst.

Grenzen in SFOS 23.0

De huidige ondersteuning sluit deze functies van deze REST API uit:

Web: Captive portal, Direct proxy authentication, Web filter notification settings, Advanced settings.
Alle Email-, Wireless- en RED-functies.
Network: DDNS en IP tunnels; SD-WAN profiles.
VPN: IPsec routes, GRE routes, L2TP, PPTP, SSL VPN site-to-site-clients en -servers.
Authentication: Guest users en clientless users; Firewall rule groups.
Let’s Encrypt certificates; High availability en TAP mode; System time.
Statusinformatie, zoals DHCP-leases, HA-status en gegevensopslag.

De lijst is niet volledig en belooft geen toekomstige versie. Controleer elke benodigde operatie in het huidige schema; een zichtbaar UI-menu bewijst geen API-ondersteuning. XML of cloud is niet automatisch een gelijkwaardig alternatief.

Als de taak mislukt

Controleer bij verbindingsfouten de bron na NAT, routing, beheerpoort, TLS, API-toegang en Device Access. Controleer bij authenticatie- of rechtenfouten sleutel, vervaldatum, verwijdering, makeraccount en profiel in plaats van volledige rechten toe te kennen. Vergelijk bij schemafouten methode, pad, verplichte velden en afhankelijke objectverwijzingen. Los sleutelverlies op door vervanging, niet door een nieuwe weergave te zoeken.

Bewaar voor escalatie firmware, schemaversie, tijdstip, endpoint, HTTP-status en een opgeschoond antwoord, zonder geheimen. Sophos ondersteunt de officiële REST API en ongewijzigde scripts, niet advies of troubleshooting voor eigen integraties. Die vereisen een interne eigenaar; betrek zo nodig een partner of Sophos Professional Services.