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

1. 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.
2. 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.
3. 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.
4. 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; iedereen ziet de lijst, maar kan 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 basis-URL, authenticatie, objectverwijzingen en het schema van het gekozen endpoint. Namen lijken op de UI, maar zijn niet altijd gelijk.

De referentie noemt deze basis en header; haal pad, methode en parameters van het werkelijke verzoek uit het passende schema:

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

Vervang hostnaam en HTTPS-beheerpoort; gebruik de secretfunctie van de client voor de sleutel. Valideer TLS-certificaat en hostnaam, zonder controles met -k te omzeilen. De introductie bevat ook voorbeelden met het XML-pad APIController; neem die niet ongecontroleerd over als REST-recept. Ontbreekt het endpoint in het firewallschema, raad dan geen pad.

Leestest en operationele controle

Stuur vanaf de echte host een onschadelijk leesverzoek volgens het schema. Controleer antwoord en verwachte objectgegevens, niet alleen HTTP-succes. Herhaal vanaf een gecontroleerde, niet toegestane bron: er mag geen configuratie terugkomen. Verwijder hiervoor geen productietoestemmingen.

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 verbindingen 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.