Bezpieczna automatyzacja Sophos Central Endpoint API

Sophos Central API nadaje się do cyklicznej inwentaryzacji, kontrolowanych zmian masowych i integracji z własnymi procesami operacyjnymi. Nie jest jednak drugim, pozbawionym konsekwencji interfejsem Reporting. Zależnie od roli aplikacja może skanować Endpointy, zmieniać grupy, modyfikować Policies, przypisywać oprogramowanie, migrować urządzenia albo uruchamiać zapytania Live Discover.

Bezpieczna automatyzacja zaczyna się więc od trzech pytań: którego tenantu dotyczy, jakie najmniejsze uprawnienie jest potrzebne i jak udokumentować oraz wycofać każdą zmianę?

API Credentials jako osobna tożsamość

W Global Settings > Access Control > API Credentials Super Admin tworzy Service Principal. Nazwa i opis wskazują aplikację, osobę odpowiedzialną, cel i datę wygaśnięcia. Osobiste dane administratora ani konto Super Admin nie należą do skryptów.

Sophos udostępnia kilka ról. Dla zadań Endpoint szczególnie istotne są:

Client Secret jest wyświetlany tylko raz i od razu zapisywany w Secret Store. Sophos nie wysyła ostrzeżenia przed wygaśnięciem API Credential. Po wygaśnięciu wpis zostaje automatycznie usunięty, a aplikacja może zalogować się ponownie dopiero przy użyciu nowo utworzonych Credentials. Monitorowanie wygaśnięcia i Rotation muszą więc odbywać się poza Central.

Legacy API Tokens dla SIEM Integration API są zastępowane. Istniejące Tokens działają tylko do daty wygaśnięcia; nowe integracje używają API Credentials.

Uwierzytelnianie i właściwy API Host

Sophos używa OAuth2 z Client Credentials Flow. Aplikacja wysyła Client ID i Client Secret do Sophos ID Endpoint i otrzymuje ograniczony czasowo Bearer Token. Tokenu, Secret ani pełnych Request Headers nie zapisuje się w ticketach ani niezabezpieczonych logach.

Po zalogowaniu najpierw wywołuje się globalny interfejs Who Am I. Odpowiedź podaje Tenant ID i API Host regionu danych. Dopiero potem aplikacja wywołuje regionalny Endpoint, taki jak api-eu01.central.sophos.com lub api-eu02.central.sophos.com. Regionalny Request wymaga, oprócz Bearer Token, nagłówka X-Tenant-ID.

Do ręcznej kontroli Central pokazuje region także w Profile > Support settings. Można go również rozpoznać w hostname linku pobierania instalatora. Automatyzacje nadal korzystają z Who Am I, ponieważ region odczytany z interfejsu nie jest wiarygodnym mechanizmem multi-tenant.

Ważne: Regionu nie określa się na podstawie lokalizacji firmy ani języka. Host wpisany na stałe w skrypcie może być nieprawidłowy dla kolejnego tenantu. Who Am I albo Tenant List jest źródłem wiążącym.

Automatyzacje Partner i Enterprise pracują z wieloma tenantami. Najpierw ustalają Partner lub Organization ID, odczytują wszystkie tenanty wraz z regionem danych, a następnie wykonują właściwy Request dla każdego tenantu, używając jego regionalnego Host i Tenant ID.

Zakres Endpoint APIs

Oficjalne interfejsy umożliwiają między innymi:

• inwentaryzację urządzeń i uruchamianie akcji, takich jak Scan,
• tworzenie i modyfikowanie Endpoint Groups oraz przypisywanie urządzeń,
• tworzenie, klonowanie i ustalanie priorytetu dodatkowych Policies oraz zmianę ich ustawień,
• przypisywanie Protection, Device Encryption lub ZTNA jako oprogramowania urządzenia,
• odczytywanie dostępnych Recommended, Fixed, LTS i Support Packages,
• organizowanie urządzeń za pomocą Key-Value Tags,
• sterowanie migracją Endpointów między tenantami,
• odczytywanie wyników Account Health i uruchamianie wspieranych poprawek,
• analizowanie Audit Events, Alerts, XDR Cases i Detections,
• uruchamianie zapisanych lub własnych Live Discover Queries.

Nie każda licencja i rola może wykonać każdą operację. Przed automatyzacją zapisującą dane należy za pomocą wywołania Read-Only sprawdzić, czy tenant, Object IDs, licencja i oczekiwany stan bieżący są zgodne.

Niektóre APIs mają bardziej rygorystyczne limity, niż sugeruje ich nazwa. Cases API może obecnie tworzyć i zmieniać wyłącznie cases self-managed. Sophos podaje ponadto miękki limit 100 requests na tenant w ciągu 24 godzin oraz 10 requests na użytkownika na minutę. Przy pobieraniu case detections page size większy niż 50 zwraca 400 Bad Request. Endpoint Software API może wyświetlać packages wyłącznie dla komputerów i serwerów Windows i obecnie wymaga roli Service Principal Super Admin. Takie wymagania właściwe dla konkretnego API należy przed implementacją sprawdzić w odpowiedniej reference, a nie wyprowadzać z ogólnych ról lub limitów.

Groups, Tags i przypisywanie oprogramowania

Groups pozostają mechanizmem przypisywania Policies. Tags uzupełniają je na potrzeby Inventory, Search i zewnętrznych Workflows. Tag składa się z Key i opcjonalnej wartości. Key i wartość mogą mieć maksymalnie po 40 znaków i nie mogą zawierać dwukropka. Na Endpoint przypada maksymalnie 15 Tags, a ten sam Key może mieć na urządzeniu tylko jedną wartość.

Tag lub Software Request może zawierać do 1'000 Endpoint UUIDs. Odpowiedź HTTP 200 przy Bulk Operations nie musi oznaczać, że każdy obiekt został zmieniony. Aplikacja musi więc analizować również błędy częściowe dla poszczególnych urządzeń i nie powtarzać bezwarunkowo całego zadania.

W Device Software API Protection, Encryption i ZTNA są osobnymi kategoriami. All przypisuje najwyższą licencjonowaną wersję wyłącznie w podanej kategorii, a None usuwa tylko tę kategorię. Dostępne Software IDs odczytuje się na konkretnym Endpoint; są case-sensitive i zależą od licencji oraz Device Catalog.

Policies nie są plikami tekstowymi

Endpoint Policy API może odczytywać Base Policies i dodatkowe Policies. Dodatkowe Policies można tworzyć, klonować, aktualizować i usuwać. W Base Policy można zmieniać tylko ustawienia, a nie nazwę, priorytet ani Activation Status.

Przed Update należy zabezpieczyć Policy Type, aktualny priorytet, przypisania i istniejące ustawienia. PATCH zawiera tylko świadomie zmieniane Keys. Automatyzacja nie może nadpisywać nieznanych albo nowo dodanych przez Sophos ustawień starym pełnym obiektem.

Zapisujące Policy Requests mają dodatkowe Rate Limits na tenant. Poprawna składnia nie dowodzi też, że zmiana jest akceptowalna operacyjnie. Tak samo jak w GUI wymagane są Pilot Group, Change Window, Audit Log i Rollback.

Pagination, Rate Limits i ponowienia

Listy trzeba odczytywać w całości ze wszystkich stron. Zależnie od interfejsu Sophos APIs używają Pagination opartej na Offset albo Key. Skrypt przetwarzający tylko pierwszą stronę odpowiedzi może błędnie zgłosić niepełny Inventory jako kompletny.

Sophos podaje dla korzystania z API wartości orientacyjne lub limity: 10 Requests na sekundę, 100 na minutę, 1'000 na godzinę i 200'000 na dzień. Poszczególne APIs mogą mieć surowsze limity. Przy 429 Too Many Requests i przejściowych błędach 5xx ponowienie następuje z Exponential Backoff i losowym Jitter. Przy błędach uwierzytelniania, uprawnień lub walidacji niezmieniona pętla bez końca jest błędna.

Każde uruchomienie zapisuje co najmniej Tenant ID, Operation, liczbę obiektów, pomyślne i błędne IDs, czas Request oraz własny Correlation ID. Secrets, Bearer Tokens i wrażliwe treści Response są usuwane z logów.

Bezpieczny proces wdrożenia

Nowa automatyzacja rozpoczyna się w tenancie testowym albo małej Pilot Group. Najpierw ten sam Workflow działa wyłącznie w trybie odczytu i tworzy zrozumiały plan. Następnie wykonuje się dokładnie jedną kontrolowaną zmianę i weryfikuje ją zarówno przez API, jak i w Central na urządzeniu, w efektywnej Policy oraz w Audit Log.

Zakres rozszerza się dopiero po przetestowaniu błędów częściowych, Pagination, Rate Limits, wygaśnięcia Credentials i Rollback. W jednorazowych projektach API Credentials usuwa się po zakończeniu; stałe integracje otrzymują Owner, Rotation, Monitoring i udokumentowaną metodę wyłączenia.

Powiązane artykuły

Konkretna migracja Endpointów między tenantami Central używa osobnego Receiving i Sending Workflow. Dla grup Endpoint i Inventory urządzeń, kolejności Policies i Live Discover obowiązują te same reguły merytoryczne niezależnie od tego, czy zmiana jest wykonywana przez GUI, czy API.

Często zadawane pytania