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, 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 Sophos Fusion Admin i innymi APIs

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 Request

Połączony artykuł Owner definiuje wyłącznie kontrakt Request/Response Tokenu, whoami, listy Partner/Enterprise, walidację hosta i ochronę sekretów. 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 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

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

• 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.

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ą schema, wymagana rola i uprawnienie, ograniczenia platformy i licencji, Status Codes oraz Rate Limit konkretnej operacji.

Grupy, Tags, oprogramowanie i Policies

Grupy sterują przypisaniem Policies i pozostają w hierarchii tenantu. 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; klient musi więc ocenić każdy zwrócony status Endpointu.

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. Należy używać tylko IDs zwróconych przez wcześniejszy odczyt dokładnie tego Endpointu; nie stosować All, None ani odgadniętych IDs bez walidacji.

Przed zmianą Policy należy zachować typ, ustawienia, przypisania i priorytet. Base Policies i dodatkowe Policies 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 Keys; stary pełny obiekt nie może nadpisać ustawień dodanych później.

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 Fusion 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