Przejdz do tresci
Avanet

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. Sprawdź źródła apiconfig 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 pobierz OpenAPI.yaml tej zapory i zaimportuj do Postman lub Swagger. W REST API guide sprawdź bazowy URL, uwierzytelnianie, odwołania do obiektów i schemat wybranego endpointu. Nazwy przypominają interfejs, ale nie zawsze są identyczne.

Dokumentacja referencyjna podaje tę bazę i nagłówek; ścieżkę, metodę oraz parametry właściwego żądania pobierz z odpowiedniego schematu:

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

Zastąp nazwę hosta i port HTTPS administratora; klucz wstaw przez funkcję sekretów klienta. Weryfikuj certyfikat TLS i nazwę hosta, bez omijania kontroli przez -k. Wprowadzenie zawiera też przykłady ze ścieżką XML APIController; nie kopiuj ich bez sprawdzenia jako instrukcji REST. Jeśli schemat zapory nie ma endpointu, nie zgaduj ścieżki.

Test odczytu i kontrola działania

Wyślij z właściwego hosta nieszkodliwy odczyt zgodny ze schematem. Sprawdź odpowiedź i oczekiwane dane, nie tylko sukces HTTP. Powtórz z kontrolowanego niedozwolonego źródła: konfiguracja nie może zostać zwrócona. Nie usuwaj produkcyjnych zezwoleń na potrzeby testu.

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.