Sophos Firewall REST API: säker åtkomst och API-nycklarnas livscykel

Det lokala REST API:t i SFOS 23.0 låter automatisering läsa och ändra konfiguration direkt på brandväggen. Börja med en separat administratör med begränsade rättigheter, tillåt bara automatiseringsvärden, skapa nyckeln med det kontot och kontrollera först en läsförfrågan. Tillgänglig dokumentation bekräftar inte ett GA-datum eller stöd i äldre firmware.

Tre gränssnitt, tre identiteter

Lokalt REST API: en brandväggsadministratörs API-nyckel fungerar som Bearer-token; rättigheterna kommer från administratörsprofilen.
Lokalt XML API: XML-payload och administratörsuppgifter, normalt via HTTP POST till APIController. XML <Get> är inte en REST-förfrågan.
Sophos Central-konfigurations-API: service principal i molnet, kortlivad åtkomsttoken, tenant och regional API-värd. En lokal nyckel ersätter inte dessa uppgifter.

Förbered åtkomst och administratör

Skapa under Profiles > Device access en profil med endast nödvändiga funktionsrättigheter; inventering behöver lämpliga läsrättigheter. Skapa under Authentication > Users en separat administratör med profilen. Planering av administratörer och profiler förklarar rollerna. Använd inte ett personligt konto eller standardkontot admin med fulla rättigheter för jobb.
Definiera under Hosts and services > IP host den verkliga värden, exempelvis api-inventory med 192.0.2.20. Ersätt namn och dokumentationsadress. En fast källa är snävare än ett helt administrationsnät; vid NAT gäller den källa brandväggen ser.
Aktivera under Administration > API access det normalt avstängda API access, välj bara nödvändiga källor under Allowed IP hosts och klicka på Apply. Adresser, intervall och nät stöds, högst 64 poster. Använd apiconfig för att granska källor som migrerats vid uppgradering till SFOS 22.0 eller senare.
Kontrollera under Administration > Device access WebAdmin från rätt zon. Device Access och API-källistan är separata kontroller; öppna inte WAN-åtkomst brett.

Skapa och spara nyckeln vid engångsvisningen

Logga in som den separata administratören. Klicka under Administration > API access > REST API keys på Add API key, ange ett tydligt namn som inventory-prod-2026-10 och skapa med Add API key.

Före Close: kopiera nyckeln till jobbets skyddade hemlighetslagring. När fönstret stängts visas den aldrig igen. Ta inte med den i skärmbilder, ärenden, repositoryfiler eller oskyddade samlingsexporter.

Nyckeln gäller ett år och ärver skaparens rättigheter. Administratörer skapar och tar bort egna nycklar; alla ser listan, men kan inte hämta hemligheten igen. Standardkontot admin kan också ta bort andras nycklar. Gränser: 10 nycklar per administratör, 1024 totalt. Dela inte nycklar mellan administratörer.

Bygg förfrågan från brandväggens schema

Hämta under REST API help brandväggens OpenAPI.yaml och importera den i Postman eller Swagger. Kontrollera autentisering, objektreferenser och valt endpointschema under REST API guide. Namnen liknar gränssnittet men är inte alltid identiska.

Dokumentationsläge den 29 oktober 2026, SFOS 23.0: Den genererade API-referensen anger basen https://<firewall-host>:<port>/api/firewall-config/v1. Den allmänna introduktionssidan anger däremot en sökväg utan /api och visar till och med APIController i det första anropet. Detta är ingen tillförlitlig anvisning för att prova olika sökvägar. För den egna brandväggen gäller den fullständiga server-URL:en i det hämtade schemat; utan motsvarande lokal operation körs inte piloten nedan.

Första läsanropet: hämta tillämpade hotfixar

Den officiella operationen GET /system/security-updates läser tillämpade hotfix-säkerhetsuppdateringar. Den startar varken en uppdatering eller en konfigurationsändring. Kontrollera före anropet i det lokala schemat att exakt denna sökväg finns med metoden GET, och använd den fullständiga bas-URL:en.

Exemplet körs med Python 3 på den godkända administrations- eller automationsvärden, inte i Device Console. firewall.example.com, port 4444 och CA-filsökvägen är värden som ska ersättas. Värdnamnet måste matcha certifikatet; 4444 är bara den HTTPS-administrationsport som valts här. PEM-filen innehåller den betrodda utfärdande CA:n, inget privat nyckelmaterial. Om certifikatkedjan redan är betrodd i Pythons Truststore kan ca_file = None användas. Lita inte på en godtyckligt hämtad 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

Nyckeln efterfrågas dolt och lagras varken som kommandoargument eller literal i skriptet. Klienten accepterar bara HTTPS och följer inga omdirigeringar: vid ett oväntat 3xx-svar stannar den i stället för att skicka Bearer-headern till ett annat mål. Aktivera inte felsökningsloggning i skal eller klient under piloten; enhetsdata som skrivs ut ska inte heller kopieras okontrollerat till ärenden. För ett obevakat jobb används senare avsedd Secret Store.

Tolka svaret och vanliga fel

Vid en lyckad begäran förväntas HTTP 200. Uppgifterna ska beskriva tillämpade hotfix-säkerhetsuppdateringar. Antal och innehåll jämförs med känt enhetsläge och svarsschemat för denna firmware; giltig JSON bevisar varken fullständighet eller en viss patchnivå.

401: Referensen kräver autentisering. Kontrollera Bearer-header, rätt nyckel, utgång och borttagning utan att logga hemligheten.
403: Referensen kräver behörighet. Kontrollera skaparkonto och dess rättigheter för operationen i stället för att generellt ge fullständiga administratörsrättigheter.
3xx: Följ inte omdirigeringen. Kontrollera bekräftad server-URL, eventuell framförliggande proxy och dess omdirigeringsregler; skicka inte nyckeln vidare till målet.
404: För denna operation är 404 inte dokumenterat som ett verksamhetsmässigt svar. Kontrollera administrationsport, fullständig schemabas, sökväg, firmware och eventuell framförliggande proxy. Byt inte automatiskt till XML-endpointen eller ett andra REST-prefix.
400 eller 500: Referensen skiljer ogiltig förfrågan från internt serverfel. Kontrollera metod och schema respektive enhetsläge och sanerad diagnostik.
Ingen HTTP-status: Undersök DNS, route, anslutning, timeout och TLS-certifikatkedja. Vid certifikatfel korrigeras värdnamn, betrodd kedja och giltighet; stäng inte av kontrollen med -k eller en okontrollerad SSL-kontext.

Lästest och driftkontroll

Verifiera först den tillåtna vägen från den verkliga automationsvärden. För negativtestet av källåtkomst körs samma rena läsförfrågan bara från en ytterligare godkänd testvärd som redan ligger utanför API-källistan. Den får inte ta emot konfiguration eller hotfixdata. Någon viss avvisningsstatus garanteras inte; ett svar med data innebär ett misslyckat negativtest. Ta inte bort produktionsåtkomst och använd inget främmande nät för testet.

TLS-negativtestet görs också utan sänkta skydd: ett uttryckligen godkänt testvärdnamn som avsiktligt inte matchar certifikatet ska misslyckas vid certifikatkontrollen innan API-data tas emot. Ändra varken produktions-DNS eller skapa extra nätverksåtkomst för detta. Utan lämpligt testnamn förblir denna del öppen. Dokumentera tid, källvärd, firmware, använd schemaversion, HTTP-/TLS-resultat och saklig datakontroll, aldrig nyckeln.

Förbered före skrivning backup och återställning, testa en liten godkänd ändring och kontrollera objektet i WebAdmin och Audit Trail. Läs efter skrivtimeout det verkliga tillståndet innan ett nytt försök. Långsamma frågor, exempelvis IPS-signaturer, kan behöva längre klienttimeout.

Utgång, ersättning och borttagning

Dokumentera konto, jobb, tillåten källa, skapandedatum, utgångsdatum och ansvarigt team, aldrig nyckeln. Planera påminnelser och ersättning före utgång; förutsätt inte automatisk förnyelse. Reservera en ledig nyckelplats för överlappande rotation. Vid 10 egna nycklar eller 1024 totalt, identifiera först onödiga nycklar med ansvarig i stället för att godtyckligt återkalla aktiva jobb.

Skapa och spara en ny nyckel med samma konto vid planerad ersättning, uppdatera jobbet och verifiera läsning. Ta först därefter bort den gamla egna nyckeln och kontrollera att den nya fungerar och den gamla inte längre ger åtkomst. Betrakta inte borttagna nycklar som återställbara. Ersätt också en nyckel vars engångsvisning gått förlorad. Vid misstänkt läcka, återkalla omedelbart även om det orsakar avbrott. Kontakta standardkontots admin-ansvariga för att ta bort andras nycklar. Vid avveckling tas nycklar och onödiga API-källor bort; kontrollera delade källor först.

Begränsningar i SFOS 23.0

Nuvarande omfattning utesluter följande från detta REST API:

Web: Captive portal, Direct proxy authentication, Web filter notification settings, Advanced settings.
Alla Email-, Wireless- och RED-funktioner.
Network: DDNS och IP tunnels; SD-WAN profiles.
VPN: IPsec routes, GRE routes, L2TP, PPTP, SSL VPN site-to-site-klienter och -servrar.
Authentication: Guest users och clientless users; Firewall rule groups.
Let’s Encrypt certificates; High availability och TAP mode; System time.
Statusinformation, exempelvis DHCP-leaser, HA-status och datalagring.

Listan är inte uttömmande och lovar ingen framtida version. Kontrollera varje operation i aktuellt schema; en synlig meny bevisar inte API-stöd. XML eller molnet är inte automatiskt likvärdiga ersättningar.

När jobbet misslyckas

Kontrollera vid anslutningsfel källa efter NAT, routing, administrationsport, TLS, API-åtkomst och Device Access. Kontrollera vid autentiserings- eller rättighetsfel nyckel, utgång, borttagning, skaparkonto och profil i stället för att ge fulla rättigheter. Jämför vid schemafel metod, sökväg, obligatoriska fält och beroende objektreferenser. Ersätt en förlorad nyckel i stället för att leta efter en ny visning.

Spara vid eskalering firmware, schemaversion, tid, endpoint, HTTP-status och ett rensat svar, utan hemligheter. Sophos stöder det officiella REST API:t och oförändrade skript, inte rådgivning eller felsökning av egna integrationer. De kräver en intern ansvarig; anlita vid behov partner eller Sophos Professional Services.