Zabezpieczanie dostępu do XML API w Sophos Firewall

XML API w Sophos Firewall jest przydatne do automatyzacji, monitorowania, tworzenia kopii zapasowych, analiz i integracji. Pozwala również w powtarzalny sposób zastosować tę samą konfigurację na wielu firewallach, jeśli proces jest ściśle ograniczony i przetestowany. Z tego powodu stanowi również część powierzchni ataku zarządzania. Pozwalając na dostęp do API, umożliwiasz systemowi odczyt danych konfiguracyjnych lub, w zależności od uprawnień, wprowadzanie zmian.

Dostęp do API nie powinien być szeroko dozwolony z sieci wewnętrznych lub dowolnych źródeł. Lepszym rozwiązaniem jest mały, udokumentowany zestaw sieci zarządzania, hostów automatyzacji lub stałych dostępów partnerskich.

Od wersji SFOS 22 Sophos rozszerzył kontrolę dostępu do API. Ustawienia dostępu do API znajdują się w sekcji Administration > API access, a dozwolone źródła mogą być definiowane jako hosty IP. Dzięki temu można dokładnie modelować nie tylko pojedyncze adresy IP, ale także zakresy IP i sieci.

W starszych wersjach SFOS konfiguracja API znajdowała się w Backup and firmware > API. Przy porównywaniu ze starszymi instrukcjami należy uwzględnić tę zmianę ścieżki menu.

Kiedy dostęp do XML API jest sensowny

XML API nie jest standardowym dostępem do codziennej pracy administratora. Jest przydatne, gdy za nim stoi konkretny proces techniczny.

Typowe przypadki użycia:

• Monitorowanie lub inwentaryzacja.
• Zautomatyzowane kontrole konfiguracji.
• Procesy tworzenia kopii zapasowych lub dokumentacji.
• Platformy MSP lub integracyjne.
• Skrypty do powtarzających się zadań administracyjnych.
• Przygotowane zmiany z narzędzi takich jak Sophos Firewall Config Studio.

Jeśli proces może obyć się bez API, dostęp do API nie powinien być pozostawiony aktywny na wszelki wypadek. Każdy dodatkowy interfejs wymaga właściciela, źródła, koncepcji dostępu i kontroli.

Co zmieniło się w SFOS 22

W SFOS 22 kontrola dostępu do XML API stała się znacznie łatwiejsza w obsłudze:

• Ustawienia dostępu do API zostały przeniesione do menu Administration > API access.
• Dostęp API jest domyślnie wyłączony i musi zostać świadomie włączony.
• Dostęp do API można ograniczyć do hostów IP.
• Jako źródła mogą być używane adresy IP, zakresy IP i sieci.
• Można zezwolić na maksymalnie 64 hosty IP.
• Podczas aktualizacji dotychczas dozwolone adresy IP są automatycznie przekształcane w obiekty hostów IP.
• Migrowane obiekty otrzymują prefiks apiconfig.

Jest to pomocne w działaniu, ponieważ źródła API nie muszą być już utrzymywane jako luźne pojedyncze adresy. Można dokładnie nazwać sieć zarządzania, host automatyzacji lub dedykowaną grupę hostów i później rozpoznać je w przeglądach.

Zasada podstawowa: API tylko z określonych źródeł

API access należy traktować tak samo jak WebAdmin lub SSH: możliwie wąsko, tylko tak szeroko, jak to konieczne.

Sensowne źródła to na przykład:

• dedykowany serwer automatyzacji,
• system monitoringu,
• host zarządzania konfiguracją,
• wewnętrzna sieć zarządzająca,
• sieć VPN lub administracyjna,
• jasno zdefiniowany adres źródłowy partnera lub MSP.

Niesensowne są:

• całe sieci klienckie,
• sieci gościnne lub IoT,
• Any,
• niejasne zwolnienia typu „cała sieć serwerowa”,
• tymczasowe adresy IP testowe, o których później się zapomina.

Jeśli zewnętrzni dostawcy usług potrzebują dostępu API, źródło powinno być zdefiniowane możliwie dokładnie. Dodatkowo należy udokumentować, do czego służy dostęp i kiedy zostanie usunięty.

Zalecany przebieg

Dokładna ścieżka w interfejsie może się nieznacznie różnić zależnie od wersji SFOS. W SFOS 22 konfiguracja API znajduje się w Administration > API access.

Praktyczny przebieg:

1. Sprawdzić, który system potrzebuje dostępu API.
2. W Hosts and services > IP host utworzyć jednoznaczny obiekt IP Host dla tego systemu.
3. Jeśli potrzebnych jest kilka źródeł, czytelnie nazwać IP Hosts, IP ranges lub sieci.
4. W Administration > API access włączyć API access.
5. W Allowed IP hosts dopuścić tylko te obiekty.
6. Kliknąć Apply.
7. Nie dodawać szerokich sieci klienckich ani serwerowych.
8. Przetestować dostęp z rzeczywistego hosta automatyzacji lub monitoringu, nie z laptopa administratora.
9. Usunąć źródła, które nie są już potrzebne.
10. Udokumentować zmianę w procesie change.

W istniejących instalacjach po aktualizacji do SFOS 22 należy dodatkowo wyszukać obiekty z prefiksem apiconfig. Obiekty te zostały utworzone ze starszych wpisów API allow i należy je sprawdzić, nazwać lub uporządkować.

Celowo przetestować dostęp

Endpoint API zwykle znajduje się pod adresem:

https://<IP-lub-nazwa-firewalla>:<Port>/webconsole/APIController

Port jest portem HTTPS WebAdmin Console. Jeśli port administracyjny został zmieniony w Administration > Admin settings, narzędzie API musi używać tego samego portu. API pracuje z payloadami XML przez HTTP POST, a nie jak klasyczne REST API z oddzielnymi endpointami GET, POST, PUT i DELETE.

HTTPS niezawodnie chroni dane logowania przed przechwyceniem i manipulacją tylko wtedy, gdy klient weryfikuje certyfikat firewalla. System automatyzacji powinien zatem używać nazwy zapisanej w certyfikacie, ufać wystawiającemu CA i przerywać pracę przy błędzie certyfikatu lub nazwy hosta. Opcje takie jak curl -k omijają tę kontrolę i nie powinny być używane w zadaniach produkcyjnych.

Sensowny test nie odpowiada tylko na pytanie, czy logowanie jest możliwe. Powinien pokazać, czy właściwe źródło jest dozwolone, czy konto może wykonać potrzebną operację i czy wynik pozostaje śledzalny w procesie audytu lub change.

W ramach odbioru należy oddzielnie sprawdzić:

• Źródło: Test działa z rzeczywistego hosta automatyzacji, monitoringu lub integracji, nie z laptopa administratora.
• Dostęp: Firewall akceptuje źródłowy IP tylko wtedy, gdy odpowiedni obiekt IP Host jest dozwolony w API access.
• Test negatywny: Z kontrolowanego hosta testowego, którego celowo nie ma na liście Allowed IP hosts, wysłać to samo nieszkodliwe żądanie odczytu i sprawdzić, czy API odrzuca je bez zwracania danych konfiguracji. Nie rozszerzać ani nie usuwać zezwolenia produkcyjnego tylko po to, by utworzyć ten przypadek testowy.
• Konto: Używane konto API lub serwisowe ma tylko wymagane uprawnienia.
• Secret: Nazwy użytkowników, hasła lub tokeny nie trafiają do historii powłoki, ticketów, czatów ani zrzutów ekranu.
• Audyt: Dostęp lub zmiana są śledzalne w procesie audytu lub change.
• Rollback: Przed operacjami zapisu istnieje backup, punkt wycofania i nieszkodliwy test odczytu.

Przykłady curl z nazwą użytkownika i hasłem w URL szybko się kopiuje, a później trudno usunąć je z logów. Lepszy jest krótki test z dedykowanym kontem serwisowym, tymczasowym secretem testowym, bezpiecznym przechowywaniem i późniejszą rotacją, jeśli secret został użyty w niebezpiecznym kontekście.

Do testów strukturalnych kolekcja Postman jest często czystsza niż szybko skopiowane polecenie shell. Również tam adres firewalla, port, nazwa użytkownika, hasło i wartości obiektów powinny być przechowywane jako zmienne lub secrety, a nie na stałe w requestach, screenshotach lub ticketach. Kolekcja nie jest koncepcją bezpieczeństwa, ale pomaga bardziej powtarzalnie testować operacje odczytu i zapisu.

Dostępne API nie dowodzi jeszcze, że planowana zmiana jest technicznie bezpieczna. Przed operacjami zapisu w produkcji powinna najpierw działać nieszkodliwa kwerenda odczytu, a następnie mała, kontrolowana zmiana.

Świadome tworzenie i ocena żądań XML

Granica wersji: Instrukcje SFOS 22 wymieniają przeglądarki jako klienty XML. Od SFOS 23.0 konkretna instrukcja wysyłania żądań XML wyraźnie wyklucza przeglądarki; do tych POST użyj Postman lub kontrolowanego wiersza poleceń Linux. Ogólny opis XML nadal wymienia przeglądarki, ale nie zezwala to na POST z przeglądarki w SFOS 23.0. Lokalne REST API z kluczami administratora to oddzielny interfejs, nie nowy sposób uwierzytelniania tych payloadów XML.

Pokazane tu zapytania i zmiany używają HTTP POST do tego samego APIController. Odczyt, tworzenie, aktualizację lub usunięcie określa payload XML, nie metoda HTTP. XML <Get> oznacza odczyt, nie automatycznie HTTP GET; również zapytanie Object Usage nazwane „API GET request” jest wysyłane przez HTTP POST. Eksport certyfikatów poniżej to oddzielnie udokumentowany wyjątek HTTP GET. Zewnętrzna struktura składa się z <Request>, <Login> i dokładnie potrzebnej operacji:

• <Set operation="add"> tworzy obsługiwane obiekty, reguły lub polityki.
• <Set operation="update"> zmienia ustawienia, których nie można utworzyć jako nowych obiektów.
• <Get> odczytuje konfiguracje lub dane stanu.
• <Remove> usuwa obsługiwane obiekty. Stałych ustawień, takich jak konfiguracja SSL/TLS Inspection, nie można usunąć, a jedynie zaktualizować.
• <Filter> ogranicza zapytanie odczytu. Ogólna dokumentacja XML opisuje przy tym tylko nazwę obiektu Name, kryteria =, != i like oraz zapis <key name="Name" ...>. Oddzielnie udokumentowane statystyki Object Usage obsługują dodatkowe klucze i kryteria; nie należy przenosić ich na zwykłe zapytania o obiekty.

Przy operacjach zapisu nie należy polegać na pominięciu atrybutu operation w <Set>. Dokumentacja podaje sprzeczne opisy pominiętej wartości: ogólny opis XML wskazuje add, natomiast pełna dokumentacja XML dla SFOS 22 i 23 — Add, a następnie Update. Nie dowodzi to ani przetestowanego domyślnego działania ograniczonego do dodawania, ani ogólnie obowiązującego działania typu upsert lub nadpisywania. Należy używać wyłącznie jawnie określonej operacji, którą API help potwierdza dla danego obiektu i zainstalowanego buildu; jeśli nie zostało to wyjaśnione, nie wykonywać żądania zapisu i zwrócić się do Support. APIXMLTags dokumentuje opcjonalny atrybut alfanumeryczny transactionid w <Set>; ułatwia on powiązanie żądania z odpowiedzią. W przypadku operacji specjalistycznych należy kierować się przykładem obiektu w API help dla używanego buildu SFOS. Przykład certyfikatu umieszcza transactionid w <Certificate>; ten szczególny przypadek nie stanowi ogólnej zasady umieszczania atrybutu w tagach obiektów wewnątrz <Set>.

APIVersion w <Request> zależy od wersji: dokumentacja XML dla SFOS 22 pokazuje 2200.1, a dla SFOS 23 — 2300.1. Są to przykłady z dokumentacji, a nie zalecenie stosowania tej wartości w każdym buildzie. Według dokumentacji APIVersion w <Response> zawiera wartość podaną w żądaniu; jeśli nie podano jej w żądaniu, uwzględniana jest wersja API aktywnego firmware. Jednocześnie sekcja dotycząca żądania określa podanie wersji jako konieczne, podczas gdy późniejsze przykłady ją pomijają. Ta wewnętrzna niespójność nie dowodzi, że podczas działania podanie wersji jest zawsze obowiązkowe albo zawsze opcjonalne. Dokładne tagi obiektów, atrybuty, kody statusu i przykładowe konfiguracje muszą zatem pochodzić z API help dla używanego buildu SFOS; przed użyciem należy potwierdzić wersję i zgodność obiektu, a payloadów nie przenosić między wersjami bez sprawdzenia.

Małe zapytanie odczytu ma następującą strukturę:

<Request>
  <Login>
    <Username>api-reader</Username>
    <Password>SECRET</Password>
  </Login>
  <Get>
    <IPHost></IPHost>
  </Get>
</Request>

api-reader i SECRET są symbolami zastępczymi. Rzeczywisty sekret należy przechowywać w chronionym magazynie sekretów narzędzia, a nie w pliku XML w repozytorium. Test jest udany dopiero wtedy, gdy odpowiedź zawiera oczekiwaną treść w <Response> oraz właściwy status w <Status>. Sam sukces HTTP lub komunikat Send successful w Postman nie dowodzi, że SFOS wykonał zamierzoną operację. Przy operacjach zapisu należy dodatkowo sprawdzić obiekt docelowy w WebAdmin i zmianę w Audit Trail.

Poniższe wartości to udokumentowane kody statusu XML w atrybucie code elementu <Status>, a nie kody statusu HTTP. Dokładną interpretację określają komunikat i Status Message Information dla danego obiektu w zainstalowanym buildzie:

• 200: konfiguracja została pomyślnie zastosowana; 201: operacja powiodła się tylko częściowo. Przy 203 operacja powiodła się, ale część konfiguracji nie została zastosowana; dokumentacja odsyła do Support. 204–210 oznaczają częściowe niepowodzenie, a nie pełny sukces.
• 211–215: ostrzeżenia; 216: sukces objaśniony dla konkretnego obiektu. W obu przypadkach należy przeczytać odpowiednią sekcję Status Message Information, zamiast traktować wszystkie wartości XML 2xx jako potwierdzenie pełnego zastosowania konfiguracji.
• 500: nie można wykonać operacji na obiekcie; 501: walidacja parametrów nie powiodła się; 502: nazwa już istnieje; 503: identyczne parametry już istnieją. Przy 504–510 odwołanie z innego obiektu uniemożliwia usunięcie; najpierw należy sprawdzić zależności. Dla 511–520 dokumentacja wymaga wyjaśnienia sprawy z Support.
• 521: żądanie jest niezgodne z bieżącą wersją API; 522–525: osiągnięto limit obiektów; 526: rekord nie istnieje; 528: domyślny obiekt nie podlega edycji; 529: nieprawidłowy XML dla obiektu; 530: wersja API nie jest obsługiwana dla tego obiektu. 541–590 to błędy specyficzne dla obiektu, z dodatkowymi informacjami w Status Message Information; 599 oznacza brak uprawnień do tworzenia lub modyfikacji.

W przypadku częściowego sukcesu lub ostrzeżeń przed kolejną próbą zapisu należy porównać odpowiedź z rzeczywistym stanem obiektu; nie zakładać, że cała konfiguracja została zastosowana ani że ponowienie jest nieszkodliwe. Do Support przekazywać tylko odpowiedzi i logi oczyszczone z danych poufnych.

Bezpieczne korzystanie z oficjalnej kolekcji Postman

Pobierz i zaimportuj aktualną kolekcję Postman. Kolekcja obejmuje tylko część obsługiwanych żądań; lokalna API help firewalla pokazuje pełny zestaw operacji oraz przykładowe konfiguracje i definicje encji właściwe dla buildu. Przed pierwszym żądaniem zastąp w Collection Variables wszystkie cztery dołączone wartości przykładowe apiadmin, Admin@12345, 172.16.16.16 i 4444 wartościami username, password, firewall-ip i firewall-port własnego środowiska. Dołączone wartości obiektów również są przykładami i nie wolno wysyłać ich bez sprawdzenia.

Dla własnego żądania należy użyć metody POST, wskazanego wyżej endpointu oraz klucza reqxml w Body > form-data. Najpierw przetestować Authenticate > Sign in, a następnie nieszkodliwe zapytanie <Get>. Dopiero gdy źródło, konto, odpowiedź i audyt są prawidłowe, można wykonać małą operację zapisu z przygotowanym rollbackiem.

Import XML z danymi wrażliwymi: Przed importem haseł lub innych wartości wrażliwych sprawdzić w API help zainstalowanego buildu, czy konkretna operacja wymaga SecureStorageMasterKey i atrybutu Token w <Request> oraz jakie dane wejściowe są prawidłowe. W przykładzie POST dla SFOS 23 SecureStorageMasterKey jest osobnym parametrem w treści żądania; Token znajduje się w <Request> w XML pola reqxml w treści żądania. Przekazywać tylko dane potwierdzone dla tej operacji, w zatwierdzonych miejscach treści POST/XML. W tym procesie klucze, hasła i tokeny nie mogą trafiać do URL, historii powłoki ani logów; nie oznacza to obowiązku używania tokenu w każdym zapytaniu XML.

Opisując pochodzenie klucza, dokumentacja XML określa SecureStorageMasterKey jako klucz główny firewalla źródłowego, z którego wyeksportowano konfigurację. Według dokumentacji bez tego klucza nie są importowane informacje wrażliwe, takie jak hasła, ani zależne od nich ustawienia; w przypadku braku klucza wskazuje ona domyślnego administratora o nazwie użytkownika admin jako osobę, do której należy się zwrócić. Token i zaszyfrowane wartości haseł pochodzą z udokumentowanego wyniku operacji Get lub eksportu. Oznaczenie hashform="mode1", na przykład w <Password>, opisuje tam zaszyfrowaną wartość hasła; dokumentacja wskazuje też możliwość podania hasła niezaszyfrowanego. Są to informacje o pochodzeniu i interpretacji, a nie zezwolenie na kopiowanie szyfrogramów, tokenów lub znaczników między dowolnymi obiektami i buildami. XML <Get> nie zezwala automatycznie na użycie metody HTTP GET. Nie wprowadza to nowego polecenia importu ani eksportu; nadal obowiązują potwierdzenie dla konkretnego obiektu i buildu oraz opisany poniżej nakaz wstrzymania operacji przy niewyjaśnionych danych wejściowych.

Dokumentacja nadal zawiera też sprzeczny przykład URL z kluczem głównym. Dopóki konflikt źródeł, wymagane dane wejściowe lub ich interpretacja dla zainstalowanego buildu pozostają nierozstrzygnięte, nie wykonywać importu danych wrażliwych i zwrócić się do Support o wyjaśnienie. Opisany poniżej eksport certyfikatów przez HTTP GET, z odrębnymi zabezpieczeniami, pozostaje osobnym wyjątkiem.

Wyeksportowana kolekcja może zawierać dane uwierzytelniające lub wartości środowiskowe. Przed udostępnieniem należy ją oczyścić, nie przechowywać sekretów w jawnym tekście jako Initial Values oraz rotować hasła testowe po wycieku.

Sprawdzanie Object Usage przed zmianami

API może zwrócić nazwy i Usage Count dla obsługiwanych obiektów. W tym celu używa się tagów statystycznych, takich jak <IPHostStatistics>, zamiast zwykłego tagu obiektu. Filtr nazw IP Host wygląda przykładowo tak:

<Request>
  <Login>
    <Username>api-reader</Username>
    <Password>SECRET</Password>
  </Login>
  <Get>
    <IPHostStatistics>
      <Filter>
        <key name="Name" criteria="like">branch</key>
      </Filter>
    </IPHostStatistics>
  </Get>
</Request>

SFOS 22 obsługuje to zapytanie o użycie dla IP Hosts, IP Host Groups, MAC Hosts, FQDN Hosts i ich grup, Country Groups, Services i Service Groups, a także Interfaces, Zones, Gateways i SD-WAN Profiles. Filtry nazwy obejmują między innymi like, not like, startswith, in, = i !=; Usage Count obsługuje dodatkowo >, >= oraz listy liczb z in.

Odpowiedź zawiera obecnie tylko nazwę obiektu i liczbę użyć, bez konfiguracji zależnych. Usage Count równy 3 nie wskazuje więc trzech konkretnych reguł lub profili. Przed operacją update lub remove należy dodatkowo sprawdzić Object usage w WebAdmin albo Config Studio. Wartość 0 także nie zezwala na niekontrolowane usunięcie: backup, kontrola zależności i ograniczony test pozostają obowiązkowe.

W WebAdmin kolumna Usage jest dostępna dla interfejsów, stref, bram, profili SD-WAN oraz hostów i usług. Licznik odświeża się raz dziennie; przed zmianą odśwież go przyciskiem obok Usage. Kliknij licznik użycia obiektu, rozwiń odpowiednią kategorię i otwórz wskazaną regułę lub politykę, aby zastąpić lub usunąć w niej obiekt. Usuwasz w ten sposób odwołanie, a nie automatycznie sam obiekt. Niektórych konfiguracji bram WAN i CLI nie można edytować w oknie Object Usage; użyj właściwej strony konfiguracji lub CLI.

Logowanie i wylogowywanie Live Users przez API

SFOS może przez API zalogować lub wylogować użytkownika jako Live User. Jest to przydatne w jasno przypisanej integracji z zewnętrznym systemem uwierzytelniania, ale nie stanowi ogólnego skrótu omijającego zwykłe logowanie użytkownika. Błędne zalogowanie przypisuje ruch do określonej tożsamości i może przez to wpływać na reguły firewalla lub reguły web oparte na użytkownikach.

Dla administratora wykonującego operację uprawnienie Manage live users pod Profiles > Device access > Identity musi mieć wartość Read-write. Przeznaczony do tego endpoint to:

https://<Firewall-IP-lub-FQDN>:<Port>/xmlapi/v1/authentication/networkuser

Ten endpoint przetwarza logowania i wylogowania równolegle. Ogólny APIController może przetwarzać te same operacje szeregowo. Nie należy więc migrować istniejącej integracji bez testu wyłącznie z powodu tej różnicy działania.

Payload logowania może wyglądać następująco:

<Request>
  <LiveUserLogin>
    <Admin>
      <UserName>api-liveusers</UserName>
      <Password>ADMIN_SECRET</Password>
    </Admin>
    <UserName>testuser</UserName>
    <IPAddress>192.0.2.25</IPAddress>
    <MacAddress>AA-BB-CC-DD-EE-FF</MacAddress>
  </LiveUserLogin>
</Request>

Aby wylogować użytkownika, wysyła się tego samego użytkownika logicznego z LiveUserLogout:

<Request>
  <LiveUserLogout>
    <Admin>
      <UserName>api-liveusers</UserName>
      <Password>ADMIN_SECRET</Password>
    </Admin>
    <UserName>testuser</UserName>
    <IPAddress>192.0.2.25</IPAddress>
    <MacAddress>AA-BB-CC-DD-EE-FF</MacAddress>
  </LiveUserLogout>
</Request>

api-liveusers, ADMIN_SECRET, testuser, 192.0.2.25 i adres MAC są wartościami przykładowymi. Nazwa użytkownika, adres IP i adres MAC muszą odpowiadać rzeczywistej sesji. Sekret administratora należy przechowywać w chronionym magazynie sekretów narzędzia i wysyłać w treści HTTP POST, a nie w URL, historii powłoki, pliku logu ani udostępnionej kolekcji.

Po zalogowaniu użytkownik musi pojawić się pod Current activities > Live users z Client type API client. Kontrolowany test sprawdza następnie oczekiwaną decyzję reguły opartej na użytkowniku. Po wylogowaniu sesja nie może być już widoczna jako aktywny klient API. Jeśli użytkownik nadal jest widoczny, najpierw należy sprawdzić payload, nazwę użytkownika, adres IP, adres MAC i odpowiedź API; nie należy na próbę wylogowywać obcej sesji Live User.

Przesyłanie lub eksportowanie certyfikatów przez API

W Postman utwórz żądanie przez New > HTTP Request, nadaj mu nazwę przez Save i zapisz je w kolekcji. Użyj POST i podanego wyżej endpointu APIController z rzeczywistym portem WebAdmin. Aplikacja desktopowa domyślnie wysyła z tego komputera; zezwól na jego źródłowy adres IP widoczny dla firewalla. W Body > form-data utwórz nazwany wpis typu File dla certyfikatu i drugi dla klucza prywatnego, wybierając lokalne pliki; trzeci wpis, reqxml, ma typ Text. Pliki przechowuj lokalnie z ograniczonym dostępem, nie w folderze synchronizowanym z chmurą.

Przykład Postman używa C:/Users/[yourname]/Postman/files jako lokalizacji w Windows. Zastąp [yourname] i sprawdź ograniczenia dostępu oraz lokalny dostęp aplikacji do plików; ta ścieżka nie jest ogólnym parametrem SFOS.

⚠️ Przykład producenta wyłącznie do celów dokumentacyjnych — nie wolno go wykonywać: Poniższy payload certyfikatu PEM dla reqxml pomija operation w <Set>. Ze względu na sprzeczne opisy działania domyślnego nie należy go wysyłać, nawet w celu dodania nowego certyfikatu. Najpierw należy wyjaśnić jawną operację i pełny payload certyfikatu dla danego obiektu i zainstalowanego buildu w API help lub z Support. Wszystkie nazwy kont, sekretów, obiektów i plików są wartościami przykładowymi:

<Request><Login><Username>api-certificates</Username><Password>SECRET</Password></Login><Set><Certificate transactionid="10"><Name>TestCertificate</Name><Action>UploadCertificate</Action><CertificateFormat>pem</CertificateFormat><CertificateFile>TestCertificate.pem</CertificateFile><PrivateKeyFile>TestCertificate.key</PrivateKeyFile></Certificate></Set></Request>

CertificateFile i PrivateKeyFile oznaczają wybrane pliki do przesłania. Opcjonalny transactionid służy tutaj do powiązania żądania z odpowiedzią. Brak operation nie dowodzi ani dodawania, ani aktualizacji; zachowany bez zmian przykład producenta pozostaje zablokowany do czasu wyjaśnienia dla konkretnego obiektu i buildu. Zwłaszcza w przypadku istniejącego certyfikatu należy sprawdzić konkretny payload aktualizacji w API help, zamiast ponownie wysyłać go bez sprawdzenia. Dopiero po tym wyjaśnieniu można wysłać potwierdzony payload; następnie sprawdzić odpowiedź w Body, a potem certyfikat docelowy w WebAdmin.

Certyfikaty są przypadkiem szczególnym, ponieważ oprócz XML przesyłane są również pliki. Dla potwierdzonego payloadu dodawania lub aktualizacji w aplikacji desktopowej Postman używa się żądania form-data z trzema częściami: plikiem certyfikatu, plikiem klucza prywatnego oraz reqxml z potwierdzoną jawną operacją w <Set> i odpowiednimi polami <Certificate>. Skrócona struktura zablokowanego przykładu nie jest szablonem do wykonania. Nazwy plików, format, działanie i nazwa certyfikatu w XML muszą odpowiadać przesłanym plikom.

Private Keys mogą znajdować się wyłącznie na chronionym stanowisku administratora i nie mogą trafić do kolekcji cloud, ticketu ani repozytorium. Po Send należy najpierw ocenić <Response> i <Status>, a następnie pod Certificates > Certificates sprawdzić, czy widoczny jest dokładnie oczekiwany certyfikat, pasujący klucz i prawidłowy łańcuch. Przypisanie i test usługi opisuje procedura Importowanie i przypisywanie certyfikatów w Sophos Firewall. Pełny proces automatyzacji — od publicznego CA przez upload właściwy dla danej kompilacji po przypisanie do usługi i zewnętrzną weryfikację — opisuje Odnawianie certyfikatu Sophos Firewall przez XML API i weryfikacja usług.

Żądanie <Get><Certificate/></Get> zwraca archiwum .tar z certyfikatami, Private Keys i Entities.xml, a nie zwykły wynik XML. Nie działa więc jak normalna odpowiedź Postman. Osobna instrukcja dokumentuje HTTP GET z Linux lub przeglądarki; oba warianty zawierają dane logowania w reqxml adresu URL.

SFOS 23.0: Ta instrukcja GET nadal wymienia przeglądarki, a instrukcja POST je wyklucza. Nie dowodzi to zakazu wszystkich HTTP GET ani przetestowanego eksportu przez przeglądarkę w tym firmware. Nie przenoś starych instrukcji przeglądarkowych ani nie zakładaj, że POST daje ten sam plik. Przed eksportem zweryfikuj z Support lub w autoryzowanym systemie testowym ścieżkę CLI GET i bezpieczną obsługę danych logowania dla zainstalowanej kompilacji; bez weryfikacji nie wykonuj eksportu.

Do zweryfikowanego eksportu użyj tylko tymczasowego konta z ograniczonymi prawami na chronionym hoście, nie rejestruj URL ani polecenia i potem zmień sekret. Weryfikuj certyfikat TLS i nazwę hosta; nie przenoś -k z przykładów producenta do produkcji. Archiwum jest bardzo poufne: przechowuj zaszyfrowane z ograniczonym dostępem, rozpakowuj w kontrolowany sposób i bezpiecznie usuwaj zbędne kopie.

Dla zatwierdzonego eksportu CLI ustal jednoznaczną lokalną ścieżkę wyjściową pliku filename.tar. Przed rozpakowaniem sprawdź wpisy poleceniem tar -tf filename.tar; nie akceptuj nieoczekiwanych ścieżek ani dowiązań. Użyj tar -xvf filename.tar wyłącznie w pustym katalogu docelowym z ograniczonym dostępem. filename.tar jest nazwą przykładową. Wynik tych poleceń może ujawnić poufne nazwy plików i nie powinien trafić do publicznych logów.

Dostęp do API i uprawnienia użytkowników

Sam źródłowy adres IP nie stanowi pełnej koncepcji bezpieczeństwa. Ograniczenie to jedynie zmniejsza liczbę miejsc, z których API jest dostępne. Dodatkowo musi być jasne, z jakiego konta odbywa się dostęp do API i jakie uprawnienia ma to konto.

Dla środowisk produkcyjnych należy sprawdzić:

• Czy używane jest osobne konto API lub serwisowe?
• Czy konto ma tylko potrzebne uprawnienia?
• Czy jest jasno udokumentowane, która osoba lub zespół jest odpowiedzialny za konto?
• Czy hasło lub sekret są bezpiecznie przechowywane?
• Czy dostęp jest usuwany, gdy integracja nie jest już używana?
• Czy zmiany są śledzone w dziennikach audytu?

Wspólne konta administratorów są problematyczne dla procesów API. Jeśli wiele systemów lub osób używa tego samego konta, śledzenie staje się trudniejsze. Dla analiz zmian istotne jest sprawdzenie dzienników śladu audytu Sophos Firewall.

Dla dedykowanego konta API lepszy jest wąski proces niż szybko skopiowany pełny administrator. Ogólne planowanie osobistych kont i ograniczonych profili opisuje artykuł Bezpieczna konfiguracja administratorów i profili Sophos Firewall; dla automatyzacji nadal obowiązuje opisane tutaj oddzielne konto serwisowe. W dokumentacji Sophos ten element występuje jako Allow API access to administrators: zezwala się nie tylko na źródło, ale również administrator lub profil musi mieć odpowiedni dostęp.

1. Utwórz profil administratora z wymaganymi uprawnieniami w Profiles > Device access.
2. Utwórz użytkownika administracyjnego dla procesu API w Authentication > Users.
3. Przypisz odpowiedni profil administratora.
4. W przypadku tymczasowego dostępu do API wyznacz osobę odpowiedzialną i zaplanuj ręczne usunięcie dedykowanego konta API i/lub dedykowanego zezwolenia na źródło dostępu do API po zakończeniu zatwierdzonego okresu; następnie sprawdź, czy ten dostęp do API został rzeczywiście cofnięty, bez wyłączania uprawnionego dostępu współdzielonego. Access Time dla zwykłych użytkowników steruje dostępem do internetu; Schedule for device access dla administratorów steruje logowaniem do WebAdmin. Żadne z tych ustawień nie jest tutaj udokumentowane jako mechanizm automatycznego wygasania dostępu do API XML: nie polegaj na nich przy kończeniu dostępu do API. Jeśli wymagane jest egzekwowanie harmonogramu, przed użyciem uzyskaj potwierdzenie w dokumentacji pierwotnej zainstalowanej kompilacji lub poprzez autoryzowaną weryfikację.
5. Jeśli to możliwe, ogranicz Login restriction for device access do przewidzianych źródeł.
6. Następnie zezwól na API access i Device Access dla odpowiedniego źródła.

W oficjalnym przykładzie profil otrzymuje Read-write dla Objects i Network. Nie jest to ogólne zalecenie: w integracjach tylko do odczytu i innych zadaniach API niepotrzebne obszary pozostają ustawione na None lub Read-only; uprawnienia do zapisu przyznaje się dopiero po kontrolowanym teście odczytu.

Sophos wspiera oficjalne API i niezmienione skrypty przykładowe. Pomoc techniczna Sophos nie zapewnia konsultacji ani rozwiązywania problemów z niestandardowymi integracjami; Sophos kieruje takie prace do odpowiedniego Sophos Partnera lub Sophos Professional Services. Własne integracje, wrappery i automatyzacje potrzebują zatem wewnętrznego właściciela, testów i koncepcji rollbacku. „Działa w labie” nie wystarcza dla produkcyjnych operacji zapisu.

Uprawnienia profilu nie są zezwoleniem na źródło: Profile w Profiles > Device access dotyczą WebAdmin i API; lokalna lista ACL usług w Administration > Device access jest osobnym mechanizmem. Profili domyślnych nie można edytować. Użyj Edit, aby sprawdzić uprawnienia; utwórz i edytuj własny profil, jeśli wymagają dostosowania. Przed usunięciem profilu odłącz go od wszystkich administratorów. Dla każdego obszaru dostępne są None, Read-only i Read-write. Przy None konfiguracja nie jest widoczna w WebAdmin ani dostępna przez API; brak danych API nie oznacza więc automatycznie błędu sieci.

Profile domyślne mają różne zakresy: Administrator, w tym domyślne konto admin, ma pełny dostęp do WebAdmin i CLI, wszystkie typy żądań API i może tworzyć administratorów. Audit admin ma Read-write dla logów i raportów; Crypto admin dla certyfikatów bezpieczeństwa. HAProfile ma dostęp Read-only do urządzenia Auxiliary, jeśli skonfigurowano HA. Security admin ma Read-write do wszystkich funkcji poza profilami, logami i raportami. Nie zakładaj, że któryś z tych profili zapewnia minimalne uprawnienia API; sprawdź rzeczywiste prawa do wymaganego obiektu.

MFA i użytkownicy API po SFOS 22

MFA jest ważne dla interaktywnych dostępów administracyjnych. Dla procesów API i automatyzacji trzeba jednak świadomie zaplanować uwierzytelnianie. Skrypt, narzędzie monitorujące lub system integracyjny nie może po prostu wpisać kodu OTP, jeśli używany użytkownik wymusza MFA.

Aktualna lista Known Issues opisuje NC-177609 dla SFOS 22.0.0 GA Respin Build 411: po aktualizacji zmiany konfiguracji przez API mogą się nie udać dla zmigrowanych użytkowników, jeśli MFA jest aktywne i nie przekazano one-time token. Niezmigrowani użytkownicy zachowują wcześniejsze działanie do czasu onboardingu MFA. Oficjalnym obejściem jest osobne konto API bez MFA albo wyłączenie tego konta z MFA. Nie jest to powód do wyłączania MFA administratorom interaktywnym; dla nowszych buildów należy najpierw sprawdzić Release Notes i Known Issues.

Zalecane podejście:

1. Dla procesów API używać osobnego konta serwisowego.
2. Nadać kontu tylko wymagane uprawnienia.
3. Dodatkowo ograniczyć API access do stałych IP Hosts lub sieci zarządzających.
4. Sprawdzić, czy MFA dla tego konta ma sens technicznie i operacyjnie.
5. Jeśli MFA dla konta API nie jest praktyczne, kontrolować konto szczególnie ściśle przez źródło, uprawnienia, przechowywanie secretów i audit trail.
6. Po aktualizacji do SFOS 22 przetestować wszystkie procesy API operacjami odczytu i zapisu.

⚠️ Użytkownicy API bez MFA nie są przepustką do szerokich uprawnień. Jeśli konto API z powodów technicznych działa bez MFA, źródłowy IP, uprawnienia, przechowywanie hasła, odpowiedzialność i audytowalność muszą być kontrolowane ściślej.

Ten punkt jest szczególnie ważny przy automatyzacjach, które nie tylko czytają, ale także zmieniają konfigurację.

Przed produkcyjnymi zmianami przez API należy sprawdzić co najmniej trzy rzeczy:

• Istnieje aktualny backup Sophos Firewall.
• Planowane konto API może pomyślnie wykonać nieszkodliwą kwerendę odczytu.
• Przy przygotowanych zmianach masowych z Sophos Firewall Config Studio wygenerowane wywołania API lub curl działają z planowanym kontem.

Odróżnienie od Device Access

Kontrola dostępu do API nie jest tym samym co Device Access, ale oba mechanizmy działają razem. Device Access kontroluje lokalne usługi firewall, takie jak WebAdmin, SSH, User Portal, VPN Portal, DNS czy Ping. Ustawienia dostępu do API dodatkowo kontrolują, które hosty IP mogą używać XML API. Ważne: uprawnienia Device Access dla WebAdmin Console obowiązują także dla dostępów API.

W praktyce oznacza to, że API access musi być dozwolony, źródło musi być dopuszczone w ustawieniach dostępu do API, a lokalny dostęp administracyjny do firewall nie może być blokowany przez Device Access. Każda warstwa ogranicza inny fragment powierzchni ataku:

• Prawidłowa konfiguracja Device Access: lokalne usługi firewall, takie jak WebAdmin, SSH, User Portal, VPN Portal, DNS czy Ping
• Kontrola dostępu do API: hosty IP, które mogą dodatkowo używać XML API
• Aktywacja MFA dla Sophos Firewall WebAdmin, VPN Portal i Remote Access: interaktywne loginy dla WebAdmin, VPN Portal i Remote Access
• Nazwani administratorzy i jasne role: Śledzenie i zakres szkód kont administratorów i serwisowych

Jeśli sieć administracyjna może korzystać z WebAdmin, SSH i API, powinna być szczególnie dobrze chroniona. Skompromitowany klient w sieci zarządzania to w przeciwnym razie bezpośredni dostęp do zarządzania firewallem.

W przypadku dostępu z WAN nie należy włączać HTTPS/WebAdmin dla całej strefy WAN. Jeśli zewnętrzny dostęp do API lub panelu administracyjnego jest rzeczywiście potrzebny, należy użyć Local service ACL exception rule z wąsko określoną Source, odpowiednim Service HTTPS, ustaloną pozycją reguły i udokumentowanym okresem obowiązywania.

HA: sprawdzenie dostępu po failoverze

W klastrze HA konfiguracja firewalla jest synchronizowana z Primary do Auxiliary; dedykowany link HA i Administration Ports nie są synchronizowane. Klienci API powinni zatem używać przewidzianej nazwy klastra lub współdzielonego adresu interfejsu, a nie nieświadomie zależeć od adresu administracyjnego konkretnego węzła.

Po skonfigurowaniu HA, zmianie certyfikatu lub failoverze należy powtórzyć test odczytu i test negatywny. Sprawdzić rozwiązywanie DNS, nazwę certyfikatu, źródłowy IP, port administracyjny, API access i Device Access. Zsynchronizowany obiekt hosta sam w sobie nie dowodzi, że pełna ścieżka sieciowa i TLS działa po zmianie ról.

Działanie i przegląd

Dostęp do API powinien być regularnie sprawdzany. Szczególnie po migracjach, zmianach dostawców usług, projektach automatyzacji lub aktualizacjach firewalla często pozostają stare źródła.

Sensowne pytania przeglądowe:

• Które hosty IP mogą obecnie korzystać z dostępu do API?
• Czy istnieją obiekty z prefiksem apiconfig?
• Czy te obiekty są nadal potrzebne?
• Czy nazwy i opisy odpowiadają rzeczywistemu celowi?
• Czy są udokumentowani odpowiedzialni?
• Czy dostępy do API są uwzględniane w procesie zmiany lub audytu?
• Czy przed większymi zmianami opartymi na API istnieje aktualna kopia zapasowa?

Przed zmianami opartymi na API zawsze powinna być dostępna kopia zapasowa. Artykuł Tworzenie lub przywracanie kopii zapasowej Sophos Firewall opisuje, na co należy zwrócić uwagę przy tworzeniu kopii zapasowej, przywracaniu i kompatybilności.

Typowe błędy

• API access dozwolony dla całej sieci klienckiej: Każdy skompromitowany klient z tej sieci może osiągnąć API.
• Stare obiekty apiconfig niesprawdzone: Zmigrowane stare wyjątki pozostają niezauważenie aktywne.
• Konto serwisowe używa pełnych praw administratora: Skompromitowany secret ma niepotrzebnie duży zasięg szkód.
• Automatyzacja API używa administratora wymagającego MFA: Skrypt lub narzędzie może po aktualizacji SFOS zawieść przy operacjach zapisu.
• Błędny port w narzędziu: Port HTTPS administratora został zmieniony, ale narzędzie nadal używa starego portu.
• Oczekiwana logika REST: Narzędzie wysyła metody REST zamiast payloadu XML przez HTTP POST do APIController.
• Sprawdzono tylko status HTTP: Właściwa operacja API nie powiodła się mimo udanego transportu. Należy ocenić <Response> i <Status>.
• Set wysłano bez operacji: Nie polegać na działaniu domyślnym ani nie ponawiać żądania bez sprawdzenia. Udokumentowane opisy są sprzeczne; przed każdym zapisem potwierdzić jawną operację dla obiektu i buildu, a w przeciwnym razie wstrzymać działanie.
• Nie można zaimportować ustawień ani tokenów MFA: Payload musi zawierać pusty element <tokenid/>.
• Nie można usunąć użytkownika: W payloadzie <Remove> należy podać dokładną nazwę użytkownika jako <Name>username</Name>. Przed wysłaniem żądania sprawdzić konto, zależności, backup i rollback.
• Usage Count potraktowano jako pełną listę zależności: Statystyka zwraca liczbę i nazwę, ale nie wskazuje reguł ani profili.
• Live User zalogowany bez powiązania z sesją: Nazwa użytkownika, adres IP i adres MAC nie odpowiadają rzeczywistej sesji, przez co reguły oparte na użytkowniku mogą podejmować błędne decyzje.
• Archiwum certyfikatów zapisano bez ochrony: Eksport API może zawierać Private Keys i nie powinien trafiać do Pobranych, ticketów ani współdzielonego magazynu.
• Tymczasowy IP dostawcy pozostaje aktywny: Dostęp zewnętrzny jest możliwy dłużej niż planowano.
• Brak dokumentacji celu: Późniejsi administratorzy nie wiedzą, czy zezwolenie jest nadal potrzebne.
• Zmiany API bez backupu: Błędną automatyzację trudniej wycofać.

Rozwiązywanie problemów

Jeśli narzędzie nie może osiągnąć XML API, należy strukturalnie sprawdzić:

1. Czy adres źródłowy IP jest poprawny z punktu widzenia firewalla?
2. Czy źródło jest dozwolone jako host IP, zakres IP lub sieć?
3. Czy po aktualizacji utworzono obiekt apiconfig, ale nie został odpowiednio dostosowany?
4. Czy Device Access zezwala na lokalny dostęp WebAdmin/API z tej strefy?
5. Czy narzędzie używa poprawnego adresu firewalla i właściwego portu admin HTTPS?
6. Czy nazwa użytkownika, hasło lub sekret są poprawne?
7. Czy konto ma potrzebne uprawnienia?
8. Czy konto wymusza MFA, mimo że narzędzie nie może przekazać tokenu jednorazowego?
9. Czy między narzędziem a firewallem występują efekty routingu, NAT lub proxy?
10. Czy dostęp został celowo usunięty przez środek utwardzający?
11. Czy test wykonano z właściwego systemu źródłowego, czy tylko z klienta administratora?

Jeśli zmiana API ma nieoczekiwane skutki, najpierw zabezpiecz ostatnią kopię zapasową, a następnie sprawdź ślad audytu, porównanie Config Studio i dotknięte obiekty firewalla. W przypadku problemów z ruchem na żywo bardziej pomocne są Log Viewer i Packet Capture niż samo API.

Przy odrzuconej lub błędnej operacji XML najpierw zapisać <Response> i <Status>. Następnie sprawdzić apiparser.log, validation.log i validationError.log w Diagnostics > Tools > Troubleshooting logs; Sophos przypisuje te pliki do translacji i walidacji API. Pliki usług i logi Sophos Firewall opisuje filtrowanie i eksport. Przed udostępnieniem fragmentu logu usunąć sekrety.

Lista kontrolna

Przed aktywacją:

• Udokumentuj cel dostępu do API.
• Jednoznacznie określ system źródłowy.
• Utwórz obiekt hosta IP z mówiącą nazwą.
• Sprawdź konto serwisowe i uprawnienia.
• Świadomie ustal zachowanie MFA dla konta API.
• Ustal proces tworzenia kopii zapasowej i przywracania.
• Ustal metodę testowania bez wycieku sekretów.
• Udokumentuj planowaną operację XML i oczekiwany <Status>.

Podczas działania:

• Zezwalaj na dostęp do API tylko dla określonych źródeł.
• Nie udostępniaj szerokich sieci klienckich, gościnnych lub IoT.
• Sprawdź obiekty apiconfig po aktualizacjach.
• Kontroluj dostępy dostawców usług czasowo i fachowo.
• Przechowuj sekrety w sposób chroniony i odnawiaj je przy zmianie personelu lub narzędzi.
• Rotuj sekrety, jeśli trafiły do historii shella, ticketów lub niebezpiecznych lokalizacji.
• Testuj operacje odczytu i zapisu API po aktualizacjach SFOS.
• Przed operacjami update lub remove sprawdź Object Usage i konfiguracje zależne.
• Zweryfikuj logowania Live Users przez API na podstawie API client, decyzji reguły i prawidłowego wylogowania.
• Pliki certyfikatów, Private Keys i eksporty API przetwarzaj wyłącznie w chronionych lokalizacjach.

Podczas przeglądu:

• Regularnie sprawdzaj dozwolone źródła API.
• Usuń niepotrzebne hosty IP.
• Porównaj zmiany z dziennikiem audytu i biletami zmiany.
• Testuj procesy automatyzacji po aktualizacjach oprogramowania.

FAQ