Przejdz do tresci
Avanet

Bezpieczna automatyzacja Sophos Central Endpoint API

Sophos Endpoint

Sophos Central 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, Policies, wyjątkami, Tags 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 Central Admin i innymi APIs

Tworzenie, przechowywanie, rotacja i usuwanie Service Principals to wspólne zadanie Central Admin. Pełna procedura znajduje się w artykule Bezpieczne zarządzanie danymi uwierzytelniającymi API Sophos Central 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 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 Request

Sophos dokumentuje OAuth2 z Client Credentials Flow. Żądanie Tokenu to POST do https://id.sophos.com/api/v2/oauth2/token, z typem application/x-www-form-urlencoded i polami grant_type=client_credentials, client_id, client_secret oraz scope=token. Tymczasowy JWT wysyła się jako Authorization: Bearer <token>.

Credential tenantu wywołuje potem GET https://api.central.sophos.com/whoami/v1. Odpowiedź wyznacza Tenant ID i host regionalny. Aplikacje Partner i Enterprise pobierają te wartości ze swoich stronicowanych list tenantów. Request regionalny wymaga:

  • hosta zwróconego przez Sophos, np. https://api-eu02.central.sophos.com, a nie regionu odgadniętego z lokalizacji lub języka;
  • nagłówka X-Tenant-ID z ID dokładnie tego tenantu.

scope=token to OAuth Scope udokumentowanego żądania Tokenu. Nie zastępuje autoryzacji: rola Service Principal, dostęp do tenantu, licencja i uprawnienia endpointu określają dozwoloną operację. Partner Assistance lub Enterprise Admin Management musi również zezwalać na potrzebny dostęp do tenantu docelowego.

Nieszkodliwe wywołanie odczytu

Przykład nie wymyśla Tokenu ani danych tenantu. Oczekuje trzech wartości z własnego procesu Credential i Discovery 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 Secret Store, nie do skryptu, Shell History, argumentów wiersza poleceń, ticketu ani Debug Log. Konfiguracja przekazana przez standardowe wejście zapobiega umieszczeniu rozwiniętego Bearer Header 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żliwy Inventory.

Udany HTTP Status potwierdza tylko Request. 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

Aktualna reference Endpoint v1 obejmuje m.in.:

  • GET /endpoint/v1/endpoints i GET /endpoint/v1/endpoints/{endpointId} dla Inventory i szczegółów;
  • POST /endpoint/v1/endpoints/{endpointId}/scans do żądania skanu;
  • /endpoint/v1/endpoint-groups dla grup Computer i Server;
  • /endpoint/v1/policies dla Policies Endpoint, Server i Device Encryption;
  • POST /endpoint/v1/tags/assignment dla przypisań Tags;
  • endpointy dla izolacji, elementów dozwolonych i blokowanych, wyjątków, Web Control, pakietów i migracji Endpoint.

Metodę HTTP i pełną ścieżkę zawsze należy brać z bieżącej reference. Podobne guides mogą pokazywać starszą ścieżkę. Przed zapisem trzeba sprawdzić schema, rolę i uprawnienie, granice platformy i licencji, Status Codes oraz Rate Limit danej operacji.

Grupy, Tags, oprogramowanie i Policies

Grupy sterują przypisaniem Policies; Tags uzupełniają Inventory i wyszukiwanie. Key ma 1–40 znaków, Value 0–40, bez dwukropka. Endpoint może mieć maksymalnie 15 Tags, a jeden Key tylko jedną Value. Request przyjmuje maksymalnie 1 000 UUID i może zwrócić błędy częściowe dla Endpointów.

W Device Software Protection, Encryption i ZTNA są osobnymi kategoriami. Computer obsługuje wszystkie trzy; Server w tym przepływie tylko Protection. Każdy blok computer lub server przyjmuje maksymalnie 1 000 IDs. Prawidłowe Software IDs zależą od Endpointu, katalogu i licencji; All, None ani ID nie stosuje się bez wcześniejszego odczytu.

Przed zmianą Policy należy zachować typ, ustawienia, przypisania i priorytet. Base Policies i dodatkowe Policies nie obsługują tych samych operacji. PATCH zawiera tylko sprawdzone Keys; stary pełny obiekt nie może nadpisać ustawień dodanych później przez Sophos.

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

Listy Endpoint używają Pagination opartej na Key: pierwsza strona bez pageFromKey, kolejne z pages.nextKey poprzedniej odpowiedzi. Inne zasoby używają numerów stron. Maksimum pageSize zależy od operacji: Endpoint ma domyślnie 50, Endpoint Groups maksymalnie 500. Należy stosować schema konkretnego endpointu i kończyć dopiero bez kolejnego Key lub strony.

Globalne limity Sophos Central APIs:

  • 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 Credentials, konta i IP źródłowego; limit dzienny dotyczy konta i Credentials, nie IP. Nie wolno używać wielu Credentials ani IP do obchodzenia limitów.

429 Too Many Requests i 5xx można ponawiać ograniczoną liczbę razy z Exponential Backoff i losowym Jitter. Przy 400, 401, 403, 404 i 409 najpierw poprawia się Request, Token, rolę, ID lub stan. Bulk Endpoints mogą zwrócić listy błędów mimo HTTP 200; należy ocenić każdy obiekt i powtarzać tylko bezpieczne, nieudane części.

Bezpieczne wdrażanie zapisu

  1. Sprawdzić tenant, host regionalny, Pagination i filtry za pomocą Read-Only Credential.
  2. Wybrać najmniejszą udokumentowaną rolę i uprawnienie dla danej operacji.
  3. Odczytać i zachować stan oraz dotknięte IDs jako dowód zmiany.
  4. Wykonać dokładnie jedną zmianę na Pilot Group lub urządzeniu testowym.
  5. Ocenić pełną Response i sprawdzić efekt na urządzeniu lub w Central.
  6. Dopiero potem rozszerzyć zakres; wcześniej obsłużyć Rollback, wygaśnięcie, 429 i błędy częściowe.

Nadal obowiązują reguły dla grup Endpoint i Inventory urządzeń, kolejności Policies 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

Czy scope=token wystarcza dla każdego Endpoint Request?

Nie. scope=token należy do żądania OAuth. Rola, dostęp do tenantu, licencja i uprawnienia operacji dodatkowo decydują, czy Sophos zezwoli na Request.

Dlaczego brakuje urządzeń, choć pierwszy Request się powiódł?

Zwykle przetworzono tylko pierwszą stronę albo działał filtr. Sprawdzić pages.nextKey, filtry, Tenant ID i host regionalny oraz odczytać wszystkie strony.

Czy nieudany Bulk Request można powtórzyć w całości?

Nie bezwarunkowo. Najpierw ocenić błędy per obiekt i ustalić, czy operacja jest idempotentna lub bezpieczna do powtórzenia. Nie wykonywać ponownie udanych zmian.

Źródła