Przejdz do tresci
Avanet
Zaloguj sie

Sophos Firewall REST API: bezpieczny dostęp i cykl życia kluczy

Sophos Firewall

Lokalne REST API w SFOS 23.0 umożliwia odczyt i zmianę konfiguracji bezpośrednio na zaporze. Zacznij od dedykowanego administratora z ograniczonymi prawami, zezwól tylko hostowi automatyzacji, wygeneruj klucz z tego konta i najpierw sprawdź odczyt. Dostępność dokumentacji nie potwierdza daty GA ani obsługi w starszym firmware.

Trzy interfejsy, trzy tożsamości

  • Lokalne REST API: klucz administratora zapory jest tokenem Bearer; uprawnienia pochodzą z profilu administratora.
  • Lokalne XML API: dane XML i poświadczenia administratora, zwykle przez HTTP POST do APIController. XML <Get> nie jest żądaniem REST.
  • API konfiguracji Sophos Central: chmurowy service principal, krótkotrwały token, tenant i regionalny host API. Lokalny klucz nie zastępuje tych poświadczeń.

Przygotowanie dostępu i administratora

  1. W Profiles > Device access utwórz profil tylko z wymaganymi prawami; inwentaryzacja wymaga odpowiednich praw odczytu. W Authentication > Users utwórz dedykowanego administratora z tym profilem. Planowanie administratorów i profili wyjaśnia role. Nie używaj konta osobistego ani domyślnego admin z pełnymi prawami do zadań.
  2. W Hosts and services > IP host określ rzeczywisty host, np. api-inventory z 192.0.2.20. Zastąp nazwę i adres dokumentacyjny własnymi wartościami. Jedno stałe źródło jest węższe niż cała sieć zarządzania; przy NAT liczy się źródło widziane przez zaporę.
  3. W Administration > API access włącz domyślnie wyłączone API access, wybierz tylko potrzebne źródła w Allowed IP hosts i kliknij Apply. Obsługiwane są adresy, zakresy i sieci, maksymalnie 64 wpisy. Za pomocą apiconfig sprawdź źródła przeniesione podczas aktualizacji do SFOS 22.0 lub nowszego.
  4. W Administration > Device access sprawdź dostęp WebAdmin z właściwej strefy. Device Access i lista API to osobne zabezpieczenia; nie otwieraj szeroko dostępu WAN.

Wygenerowanie i jednorazowe zapisanie klucza

Zaloguj się jako dedykowany administrator. W Administration > API access > REST API keys kliknij Add API key, podaj czytelną nazwę, np. inventory-prod-2026-10, i wygeneruj przez Add API key.

Przed Close: skopiuj klucz do chronionego magazynu sekretów zadania. Po zamknięciu okna nie zostanie ponownie wyświetlony. Nie umieszczaj go na zrzutach, w zgłoszeniach, repozytorium ani niechronionych eksportach kolekcji.

Klucz jest ważny rok i dziedziczy prawa twórcy. Administratorzy tworzą i usuwają własne klucze; wszyscy widzą listę, ale nie mogą ponownie odzyskać sekretu. Domyślny admin może też usuwać klucze innych. Limity: 10 kluczy na administratora, 1024 łącznie. Nie współdziel kluczy między administratorami.

Budowanie żądania ze schematu zapory

W REST API help pobrać OpenAPI.yaml tej zapory i zaimportować do Postman lub Swagger. W REST API guide sprawdzić uwierzytelnianie, odwołania do obiektów i schemat wybranego endpointu. Nazwy endpointów przypominają interfejs, ale nie zawsze są identyczne.

Stan dokumentacji 29 października 2026 r., SFOS 23.0: Wygenerowana referencja API podaje bazę https://<firewall-host>:<port>/api/firewall-config/v1. Ogólne wprowadzenie podaje natomiast ścieżkę bez /api, a dla pierwszego wywołania pokazuje nawet APIController. Nie jest to wiarygodna instrukcja próbowania różnych ścieżek. Dla własnej zapory obowiązuje pełny URL serwera z jej pobranego schematu; bez zgodnej operacji lokalnej poniższego pilotażu się nie wykonuje.

Pierwszy odczyt: zapytanie o zastosowane hotfixy

Oficjalna operacja GET /system/security-updates odczytuje zastosowane aktualizacje bezpieczeństwa typu hotfix. Nie uruchamia aktualizacji ani zmiany konfiguracji. Przed wywołaniem sprawdzić w lokalnym schemacie, czy istnieje dokładnie ta ścieżka z metodą GET, i przejąć pełny bazowy URL.

Po odczycie sprawdź rzeczywistą odpowiedź HTTP i dane hotfixów dla właściwego firewalla.

Przykład działa w Python 3 na zatwierdzonym hoście administracyjnym lub automatyzacji, nie w Device Console. firewall.example.com, port 4444 i ścieżka pliku CA są wartościami do zastąpienia. Nazwa hosta musi pasować do certyfikatu; 4444 jest tylko wybranym tu portem administracyjnym HTTPS. Plik PEM zawiera zaufany wystawiający CA, nie prywatny materiał klucza. Jeśli łańcuch certyfikatów jest już zaufany w magazynie Python, można użyć ca_file = None. Nie ufać dowolnemu pobranemu 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

Klucz jest pobierany z ukrytym echem, nie jest zapisywany jako argument polecenia ani literał w skrypcie. Klient akceptuje wyłącznie HTTPS i nie podąża za przekierowaniami: przy nieoczekiwanej odpowiedzi 3xx zatrzymuje się, zamiast wysłać nagłówek Bearer do innego celu. Podczas pilotażu nie włączać logowania debug powłoki ani klienta; wyświetlane dane urządzenia także nie powinny bez kontroli trafiać do zgłoszeń. Dla zadania bez nadzoru używa się później przewidzianego magazynu sekretów.

Interpretacja odpowiedzi i typowych błędów

Po pomyślnym żądaniu oczekiwany jest status HTTP 200. Dane powinny opisywać zastosowane aktualizacje bezpieczeństwa typu hotfix. Liczbę i treść porównuje się ze znanym stanem urządzenia oraz schematem odpowiedzi tej wersji firmware; samo poprawne JSON body nie dowodzi kompletności ani określonego stanu poprawek. Nazwy pól i ich znaczenie należy porównać ze schematem odpowiedzi dla zainstalowanej wersji.

  • 401: Referencja wymaga uwierzytelnienia. Sprawdzić nagłówek Bearer, właściwy klucz, wygaśnięcie i usunięcie, nie zapisując sekretu w logach.
  • 403: Referencja wymaga uprawnienia. Sprawdzić konto twórcy i jego uprawnienia do operacji, zamiast ogólnie nadawać pełne prawa administratora.
  • 3xx: Nie przekierowywać. Sprawdzić potwierdzony URL serwera, ewentualny proxy i jego reguły przekierowań; nie przekazywać klucza do celu przekierowania.
  • 404: Dla tej operacji 404 nie jest udokumentowane jako odpowiedź merytoryczna. Sprawdzić port administratora, pełną bazę schematu, ścieżkę, firmware i ewentualny proxy. Nie przełączać automatycznie na endpoint XML ani drugi prefiks REST.
  • 400 lub 500: Referencja rozróżnia nieprawidłowe żądanie i wewnętrzny błąd serwera. Sprawdzić metodę i schemat albo stan urządzenia i zanonimizowaną diagnostykę.
  • Brak statusu HTTP: Sprawdzić DNS, trasę, połączenie, timeout i łańcuch certyfikatów TLS. Przy błędach certyfikatu poprawić nazwę hosta, łańcuch zaufania i ważność; nie wyłączać weryfikacji przez -k ani niesprawdzony kontekst SSL.

Test odczytu i kontrola działania

Najpierw odebrać dozwoloną ścieżkę z właściwego hosta automatyzacji. Dla negatywnego testu źródła wykonać to samo żądanie tylko do odczytu wyłącznie z dodatkowo zatwierdzonego hosta testowego, który już znajduje się poza listą źródeł API. Nie może otrzymać konfiguracji ani danych hotfixów. Konkretny status odmowy nie jest gwarantowany; odpowiedź z danymi oznaczałaby niezaliczony test negatywny. Nie usuwać produkcyjnych zezwoleń ani nie używać obcej sieci do testu.

Negatywna kontrola TLS również odbywa się bez obniżania ochrony: celowo niepasująca do certyfikatu, wyraźnie zatwierdzona testowa nazwa hosta musi spowodować błąd weryfikacji certyfikatu przed otrzymaniem danych API. Nie zmieniać na ten cel produkcyjnego DNS ani nie tworzyć dodatkowego zezwolenia sieciowego. Bez odpowiedniej nazwy testowej ta część odbioru pozostaje otwarta. Udokumentować czas, host źródłowy, firmware, używaną wersję schematu, wynik HTTP/TLS i merytoryczne porównanie danych, nigdy klucz.

Przed zapisem przygotuj kopię i drogę odzyskania, przetestuj małą zatwierdzoną zmianę i sprawdź obiekt w WebAdmin oraz Audit Trail. Po timeout zapisu odczytaj stan rzeczywisty przed ponowieniem. Powolne zapytania, np. sygnatury IPS, mogą wymagać dłuższego timeout klienta.

Wygaśnięcie, wymiana i usuwanie

Zapisz konto, zadanie, dozwolone źródło, datę utworzenia, wygaśnięcia i odpowiedzialny zespół, nigdy sam klucz. Zaplanuj przypomnienia i wymianę przed wygaśnięciem; nie zakładaj automatycznego odnowienia. Zarezerwuj wolne miejsce na klucz do rotacji z nakładaniem. Przy 10 własnych lub 1024 łącznych kluczach ustal najpierw z właścicielem, które są zbędne, zamiast losowo unieważniać aktywne zadania.

Przy planowej wymianie wygeneruj i zapisz nowy klucz na tym samym koncie, zmień zadanie i sprawdź odczyt. Dopiero potem usuń stary własny klucz i sprawdź, czy nowy działa, a stary nie daje dostępu. Nie traktuj usuniętych kluczy jako odzyskiwalnych. Wymień także klucz, którego jednorazowy odczyt utracono. Przy podejrzeniu wycieku natychmiast unieważnij, nawet kosztem przerwy. W sprawie cudzych kluczy skontaktuj się z właścicielem domyślnego admin. Przy wycofaniu integracji usuń klucze i zbędne źródła API, najpierw sprawdzając źródła współdzielone.

Ograniczenia SFOS 23.0

Obecny zakres wyklucza z tego REST API:

  • Web: Captive portal, Direct proxy authentication, Web filter notification settings, Advanced settings.
  • Wszystkie funkcje Email, Wireless i RED.
  • Network: DDNS i IP tunnels; SD-WAN profiles.
  • VPN: IPsec routes, GRE routes, L2TP, PPTP, klienty i serwery SSL VPN site-to-site.
  • Authentication: Guest users i clientless users; Firewall rule groups.
  • Let’s Encrypt certificates; High availability i TAP mode; System time.
  • Informacje o stanie, np. dzierżawy DHCP, stan HA i przechowywanie danych.

Lista nie jest pełna ani nie obiecuje przyszłej wersji. Sprawdź każdą operację w bieżącym schemacie; widoczne menu nie dowodzi obsługi API. XML lub cloud nie są automatycznie równoważnym zamiennikiem.

Gdy zadanie nie działa

Przy problemach z połączeniem sprawdź źródło po NAT, routing, port administratora, TLS, dostęp API i Device Access. Przy uwierzytelnianiu lub uprawnieniach sprawdź klucz, wygaśnięcie, usunięcie, twórcę i profil zamiast nadawać pełne prawa. Przy błędach schematu porównaj metodę, ścieżkę, wymagane pola i zależne odwołania. Utracony klucz zastąp, nie szukaj ponownego wyświetlenia.

Do eskalacji zachowaj firmware, wersję schematu, czas, endpoint, status HTTP i oczyszczoną odpowiedź, bez sekretów. Sophos wspiera oficjalne REST API i niezmienione skrypty, nie doradztwo lub troubleshooting własnych integracji. Te wymagają wewnętrznego właściciela; w razie potrzeby zaangażuj partnera lub Sophos Professional Services.