Bezpieczna automatyzacja Sophos Fusion Endpoint API

Sophos Fusion Endpoint API to API tenantu dla zasobów Endpoint i serwerów. Pozwala inwentaryzować urządzenia, a zależnie od endpointu i uprawnień także zarządzać skanami, izolacją, grupami, politykami, wyjątkami, znacznikami i przypisaniami oprogramowania. Zapis wpływa na ochronę; do inwentaryzacji wystarczy tożsamość Read-Only.

Bezpieczna ścieżka skrócona: użyć API Credential z minimalną rolą, uzyskać Token przez OAuth2 Client Credentials Flow, ustalić Tenant ID i host regionalny, najpierw przetestować GET /endpoint/v1/endpoints, a następnie obsłużyć wszystkie strony i błędy.

Granica z Sophos Fusion Admin i innymi interfejsami API

Tworzenie, przechowywanie, rotacja i usuwanie Service Principals to wspólne zadanie Sophos Fusion Admin. Pełna procedura znajduje się w artykule Bezpieczne zarządzanie danymi uwierzytelniającymi API Sophos Fusion i nie jest tutaj powielana.

Listy tenantów Partner i Organization, Alerts, Audit Events, Account Health, Cases oraz Live Discover również nie należą automatycznie do Endpoint API. Sophos Fusion (dawniej Sophos Central) udostępnia osobne APIs z własnymi rolami i limitami. Artykuł obejmuje wyłącznie żądania pod regionalną ścieżką /endpoint/v1.

Uwierzytelnianie i kontekst żądania

Żądanie tokenu, kontrakt odpowiedzi, whoami, listy tenantów Partner/Enterprise, walidację hosta i zasady postępowania z sekretami zdefiniowano wyłącznie w podlinkowanym artykule dotyczącym danych uwierzytelniających API. Należy bez zmian przejąć SOPHOS_ACCESS_TOKEN, SOPHOS_TENANT_ID i SOPHOS_API_HOST. scope=token nie zastępuje autoryzacji: nadal obowiązują rola Service Principal, dostęp do tenantu, licencja i uprawnienie Endpoint; Partner Assistance lub Enterprise Admin Management musi zezwalać na tenant docelowy.

Nieszkodliwe wywołanie odczytu

Przykład nie wymyśla tokenu ani danych tenantu. Oczekuje trzech wartości z własnego procesu uzyskiwania danych uwierzytelniających i ustalania kontekstu tenantu i zapisuje pierwszą stronę lokalnie:

: "${SOPHOS_ACCESS_TOKEN:?Bearer token is missing}"
: "${SOPHOS_TENANT_ID:?Tenant ID is missing}"
: "${SOPHOS_API_HOST:?Regional API host is missing}"
umask 077

curl --fail-with-body --silent --show-error --get \
  "${SOPHOS_API_HOST}/endpoint/v1/endpoints" \
  --header "X-Tenant-ID: ${SOPHOS_TENANT_ID}" \
  --data-urlencode "pageSize=50" \
  --output endpoints-page.json \
  --config - <<EOF
header = "Authorization: Bearer ${SOPHOS_ACCESS_TOKEN}"
EOF

SOPHOS_API_HOST należy przejąć bez zmian z whoami lub listy tenantów. Token powinien trafić do procesu z magazynu sekretów, nie do skryptu, historii powłoki, argumentów wiersza poleceń, zgłoszenia ani dziennika debugowania. Konfiguracja przekazana przez standardowe wejście zapobiega umieszczeniu rozwiniętego nagłówka Bearer na liście argumentów curl; umask 077 ogranicza uprawnienia nowego pliku wyjściowego. --fail-with-body uwidacznia błąd HTTP, ale zapisany plik nadal trzeba chronić jako potencjalnie wrażliwe dane inwentaryzacyjne.

Pomyślny status HTTP potwierdza tylko żądanie. Następnie należy sprawdzić poprawność JSON, oczekiwany tenant i obecność potrzebnych urządzeń. Nie pokazujemy fikcyjnej odpowiedzi, którą można pomylić z zaobserwowanym wynikiem.

Świadomy wybór ścieżek Endpoint

Endpoint v1 obejmuje m.in. następujące ścieżki:

• GET /endpoint/v1/endpoints i GET /endpoint/v1/endpoints/{endpointId} do inwentaryzacji i odczytu szczegółów;
• POST /endpoint/v1/endpoints/{endpointId}/scans do żądania skanu;
• POST /endpoint/v1/endpoints/tamper-protection do selektywnych zmian Tamper Protection na maksymalnie 200 urządzeniach;
• POST /endpoint/v1/endpoints/reset-health do resetowania stanu ochrony i alertów na maksymalnie 500 obsługiwanych urządzeniach;
• /endpoint/v1/endpoint-groups dla grup komputerów i serwerów;
• /endpoint/v1/policies dla polityk Endpoint, Server i Device Encryption;
• POST /endpoint/v1/tags/assignment dla przypisań znaczników;
• endpointy dla izolacji, elementów dozwolonych i blokowanych, wyjątków, Web Control, pakietów i migracji Endpoint.

Należy używać metody HTTP i pełnej ścieżki podanych powyżej, bez zastępowania ich starszymi ścieżkami o podobnych nazwach. Przed zapisem sprawdzane są schemat żądania, wymagana rola i uprawnienie, ograniczenia platformy i licencji, kody statusu oraz limit wywołań konkretnej operacji.

Selektywna zmiana Tamper Protection i stanu ochrony za pomocą żądań zbiorczych

Obie operacje zbiorcze uzupełniają istniejące wywołania Endpoint v1; nie wymuszają migracji. Obie korzystają z ustalonego hosta regionalnego, tokenu Bearer, X-Tenant-ID docelowego tenantu i Content-Type: application/json. Każda wymaga uprawnienia endpoint-state:update. Tożsamość tylko do odczytu nie wystarcza; należy wcześniej sprawdzić, czy rola Service Principal obejmuje to uprawnienie w docelowym tenancie.

Tamper Protection: Treść JSON dla POST /endpoint/v1/endpoints/tamper-protection zawiera ids z 1–200 unikatowymi identyfikatorami UUID endpointów oraz co najmniej jedno z pól logicznych enabled lub regeneratePassword. enabled: true żąda włączenia, a enabled: false wyłączenia ochrony. regeneratePassword: true żąda nowych haseł urządzeń. Schemat używa anyOf, nie oneOf: dopuszcza zatem również oba pola jednocześnie. Dla zapewnienia rozliczalności zmian serwisowych należy mimo to osobno planować zmianę stanu i regenerację haseł oraz wysyłać tylko zamierzone pola. Regeneracja haseł nie jest lokalnym czterogodzinnym obejściem ani wspólnym hasłem dla wszystkich urządzeń.

Przed wyłączeniem ochrony: Używać wyłącznie zatwierdzonego zestawu ID i zapisać dla każdego urządzenia stan początkowy, koniec serwisu oraz osobę odpowiedzialną. Dla wyłączenia przez API nie udokumentowano automatycznego przywrócenia po czterech godzinach. Po serwisie zażądać włączenia dokładnie tych urządzeń, które wyłączono, i sprawdzić efekt. Lokalne metody serwisowe i metody dla pojedynczych urządzeń często pozostają lepszym wyborem dla pojedynczych urządzeń.

Najpierw odczytać GET /endpoint/v1/endpoints/{endpointId}?view=full i uwzględnić tylko urządzenia z potwierdzonym tamperProtectionSupported: true; brak wartości nie oznacza zgody. Zakres Windows/Linux resetowania stanu ochrony nie potwierdza obsługi tych platform przez Tamper Protection. Sprawdzić przełącznik globalny za pomocą GET /endpoint/v1/settings/tamper-protection: jeśli jest wyłączony, włączenie pojedynczych urządzeń nie przywróci ochrony. GET /endpoint/v1/endpoints/{endpointId}/tamper-protection zwraca zamierzony stan enabled, ale także password i ewentualnie previousPasswords. Nie zapisywać całej odpowiedzi w logach. Hasła nie mogą trafiać do zgłoszeń ani dzienników debugowania; rotacji nie można cofnąć przez ponowne zapisanie starego hasła.

Reset Health: POST /endpoint/v1/endpoints/reset-health oczekuje treści JSON z wymaganym polem ids: 1–500 unikatowych identyfikatorów UUID endpointów. Obsługiwane są komputery Windows, serwery Windows i Linux, ale nie macOS.

Przed resetem: Operacja ustawia stan ochrony na zielony i usuwa wszystkie alerty dotyczące wskazanych endpointów. Należy więc wcześniej zachować istotne ustalenia, szczegóły alertów i dowody audytowe poza widokiem, który zostanie wyczyszczony, oraz uzyskać wyraźną zgodę na usunięcie. Reset nie usuwa złośliwego oprogramowania i nie naprawia uszkodzonej usługi ochrony. Zielony stan po tej operacji nie dowodzi usunięcia przyczyny; kontrakt resetu nie przewiduje operacji cofnięcia umożliwiającej odzyskanie usuniętych alertów.

Po zatwierdzonym żądaniu pilotażowym ponownie odczytać szczegóły urządzeń, sprawdzić stan ochrony i alerty w Sophos Fusion, a rzeczywiste działanie ochrony zweryfikować osobno. Nowe alerty należy zbadać, a nie ukrywać kolejnymi resetami.

Przyjęcie nie oznacza wykonania

W obu operacjach zbiorczych HTTP 202 oznacza jedynie, że żądanie zostało przetworzone i oceniono przyjęcie dla każdego ID. items zawiera przyjęte żądania z id, status: requested i requestedAt; errors zawiera odrzucone żądania z id, errorCode i errorMessage. requestedAt nie jest czasem zakończenia. Porównać każdy wysłany ID z wynikami; brakujące lub sprzeczne przyporządkowania pozostają niewyjaśnione nawet przy pomyślnym statusie HTTP.

Kody błędów to notFound, notSupported, conflict, permissionDenied i internalError. Przy pierwszych czterech najpierw poprawić odpowiednio ID/tenant, obsługę urządzenia, stan lub uprawnienia. Nawet internalError nie upoważnia do ponownego wysłania całej partii. Przy błędach HTTP przeanalizować odpowiedź błędu; 202 może jednocześnie zawierać przyjęte i odrzucone ID.

Następnie osobno potwierdzić efekt: po udanym kontakcie urządzenia odczytać szczegóły endpointu z view=full, a dla Tamper Protection także ustawienia, po czym sprawdzić ochronę lokalnie. Ocenić lastSeenAt, tamperProtectionEnabled albo, zależnie od operacji, health.overall, health.threats i health.services. Sam odczyt stanu docelowego nie potwierdza wykonania na urządzeniu offline. Ustalić ograniczony interwał kontroli i łączny czas do przerwania; jeśli brak potwierdzenia, udokumentować wykonanie jako nadal otwarte i zbadać łączność urządzenia lub błędy.

Po przekroczeniu czasu oczekiwania lub zerwaniu połączenia żądanie zapisu mogło już zostać przyjęte. Nie ponawiać go w ciemno: najpierw porównać stan i dostępne dowody dla każdego ID. W przeciwnym razie kolejna rotacja hasła lub reset alertów może zmienić stany powstałe w międzyczasie. Ponownie zatwierdzać wyłącznie podzbiory, których odrzucenie jest udowodnione i które po korekcie można bezpiecznie powtórzyć; niewyjaśnione ID odłożyć do ręcznej weryfikacji.

Grupy, znaczniki, oprogramowanie i polityki

Grupy sterują przypisaniem polityk i pozostają w hierarchii tenantu. Znaczniki uzupełniają inwentaryzację i wyszukiwanie. Klucz ma 1–40 znaków, wartość 0–40, bez dwukropka. Endpoint może mieć maksymalnie 15 znaczników, a jeden klucz tylko jedną wartość. Żądanie przyjmuje maksymalnie 1 000 UUID i może zwrócić błędy częściowe dla endpointów; klient musi więc ocenić każdy zwrócony status endpointu.

W Device Software Protection, Encryption i ZTNA są osobnymi kategoriami. Komputery obsługują wszystkie trzy; serwery w tym przepływie tylko Protection. Każdy blok computer lub server przyjmuje maksymalnie 1 000 identyfikatorów. Prawidłowe identyfikatory oprogramowania zależą od endpointu, katalogu i licencji. Należy używać tylko identyfikatorów zwróconych przez wcześniejszy odczyt dokładnie tego endpointu; nie stosować All, None ani odgadniętych identyfikatorów bez walidacji.

Przed zmianą polityki należy zachować typ, ustawienia, przypisania i priorytet. Polityki bazowe i dodatkowe nie obsługują tych samych operacji. Zmieniać tylko pola, które aktualny obiekt tenantu udostępnia do zapisu i nie oznacza jako zablokowane. PATCH zawiera tylko sprawdzone klucze; stary pełny obiekt nie może nadpisać ustawień dodanych później.

Paginacja, limity i obsługa błędów

Listy endpointów używają paginacji opartej na kluczu: pierwsza strona bez pageFromKey, kolejne z pages.nextKey poprzedniej odpowiedzi. Inne zasoby używają numerów stron. Maksimum pageSize zależy od operacji: dla endpointów wartość domyślna wynosi 50, a dla grup endpointów maksymalnie 500. Należy stosować schemat konkretnego endpointu i kończyć dopiero bez kolejnego klucza lub strony.

Globalne limity interfejsów API Sophos Fusion:

• 10 wywołań na sekundę: zalecane;
• 100 na minutę: wymuszane, krótkie serie do 300 dozwolone;
• 1 000 na godzinę: zalecane;
• 200 000 na dzień: wymuszane.

Surowszy limit operacji ma pierwszeństwo. Sophos stosuje pierwsze trzy osobno do danych uwierzytelniających, konta i źródłowego adresu IP; limit dzienny dotyczy konta i danych uwierzytelniających, nie adresu IP. Nie wolno używać wielu zestawów danych uwierzytelniających ani adresów IP do obchodzenia limitów.

Dla odczytów, które można bezpiecznie powtarzać, obsługiwać 429 Too Many Requests i 5xx z ograniczoną liczbą prób, wykładniczym wydłużaniem odstępów i losowym jitterem. Nie dotyczy to automatycznie zapisu: przy niejasnym statusie przyjęcia najpierw sprawdzić efekt dla każdego obiektu. Przy 400, 401, 403, 404 i 409 najpierw poprawić żądanie, token, rolę, ID lub stan. Endpointy zbiorcze mogą zwracać listy błędów mimo HTTP 200 lub 202; należy więc oceniać sukcesy i błędy dla każdego obiektu oraz ponownie wysyłać tylko nieudane części, które można bezpiecznie powtórzyć.

Bezpieczne wdrażanie zapisu

1. Sprawdzić tenant, host regionalny, paginację i filtry za pomocą danych uwierzytelniających tylko do odczytu.
2. Wybrać najmniejszą udokumentowaną rolę i uprawnienie dla danej operacji.
3. Odczytać i zachować stan oraz identyfikatory urządzeń objętych zmianą jako dowód zmiany.
4. Wykonać dokładnie jedną zmianę na grupie pilotażowej lub urządzeniu testowym.
5. Ocenić pełną odpowiedź API i sprawdzić efekt na urządzeniu lub w Central.
6. Dopiero potem rozszerzyć zakres; wcześniej uwzględnić wycofanie zmian, wygaśnięcie danych uwierzytelniających, 429 i błędy częściowe.

Nadal obowiązują reguły dla grup Endpoint i inwentaryzacji urządzeń, kolejności polityk oraz Live Discover. Obsługiwany proces przenoszenia już chronionych Endpointów do innego tenantu opisano osobno i nie wolno go wyprowadzać z ogólnego przykładu API.

Często zadawane pytania