Odpytywanie Data Lake Sophos Fusion przez Search GraphQL API
Search GraphQL API v1 pozwala własnej aplikacji przeszukiwać historyczny Data Lake Sophos Fusion (dawniej Sophos Central) za pomocą QL. Przebieg jest asynchroniczny: uruchom wyszukiwanie, zachowaj jego Search-URN, sprawdź zakończenie i wynik wykonania, a następnie odczytaj wszystkie strony wyników. Sam status COMPLETE nie oznacza, że wszystkie części wyszukiwania się powiodły.
API jest opublikowane od 12 października 2026 r. Uzupełnia istniejące API i nie wymusza natychmiastowego przejścia z nadal dostępnego XDR Query API. Nie zastępuje też Live Endpoint Search (LES): LES odpytuje połączone endpointy przy użyciu SQL w stylu osquery. Rozróżnienie Classic Live Discover, Data Lake Search i LES pomaga wybrać właściwą ścieżkę danych.
Przed pierwszym żądaniem
Potrzebne są tenant z szukanymi danymi historycznymi, odpowiednie API Credentials, jednoznaczny UUID tenanta i klient HTTP wysyłający żądania POST JSON oraz zapisujący pełne odpowiedzi. W przykładzie tenant musi zawierać zdarzenia procesów. Bez tych danych nawet technicznie poprawne wyszukiwanie może zwrócić pusty wynik.
Bezpieczne zarządzanie poświadczeniami API wyjaśnia tożsamość maszynową, przepływ OAuth z client_credentials, przypisanie tenanta i rotację. Identyfikator partnera lub organizacji nie jest UUID tenanta. Przy wielu tenantach wybieraj docelowego na podstawie zatwierdzonego, jednoznacznego mapowania, a nie wyłącznie nazwy wyświetlanej.
Dokładną minimalną rolę i wymagane uprawnienia wynikające z licencji dla konkretnego klienta Search trzeba ustalić przed dopuszczeniem do produkcji. Nazwa ogólnej roli service principal nie potwierdza uprawnienia Search. W razie odmowy nie nadawaj zapobiegawczo roli Super Admin.
Przed uruchomieniem określ pytanie dochodzeniowe, zakres czasu i wymagane pola. Dane procesów mogą zawierać nazwy użytkowników, ścieżki i wiersze poleceń z poufną treścią. Zapytania i eksporty muszą trafiać do zatwierdzonego środowiska z ustalonymi uprawnieniami dostępu i przechowywania. Tokeny i Client Secret nie mogą znaleźć się w logach żądań, zgłoszeniach ani zapisanych plikach przykładowych. Nie zapisuj też bez kontroli pełnych wierszy wynikowych.
Używaj hosta docelowego właściwego dla API
Poniższe operacje mają wspólny kontrakt żądania:
POST https://api.taegis.sophos.com/graphql
Authorization: Bearer <access-token>
X-Tenant-ID: <tenant-uuid>
X-GraphQL-Schema: default
Content-Type: application/json
W kliencie HTTP zastąp <access-token> aktualnym tokenem dostępu OAuth, a <tenant-uuid> sprawdzonym UUID. URL i nagłówki pozostają jednakowe dla każdego z poniższych body JSON. Przykłady są szablonami żądań; wynik trzeba sprawdzić w docelowym tenancie.
Regionalny host REST z apiHosts.dataRegion nie jest hostem docelowym tego kontraktu Search. Nie przełączaj też globalnie istniejących klientów REST na host GraphQL. Sama ta nazwa hosta nie gwarantuje lokalizacji przechowywania ani rezydencji danych; wymagania te ustal zgodnie z obowiązującymi warunkami tenanta i umowy.
Uruchamianie i jednoznaczne śledzenie wyszukiwania
Utwórz nowe wykonanie przez createSearch
Poniższy szablon wyszukuje zdarzenia procesów z ostatniej godziny i ogranicza wybrane pola zdarzeń. -1h to względne okno czasowe do pierwszej kontroli działania; do późniejszego porównania z innym klientem ustal jednakowe jawne granice czasu.
{
"operationName": "CreateSearch",
"query": "mutation CreateSearch($input: CreateSearchInput) { createSearch(input: $input) { urn status } }",
"variables": {
"input": {
"text": "from process where earliest = -1h | fields host_id, commandline, image_path"
}
}
}
Przed wysłaniem sprawdź tenanta, czas i zakres danych. createSearch tworzy i uruchamia nowe wyszukiwanie, ale nie zmienia konfiguracji ochrony endpointów. Wykonanie może obciążyć usługę i wytworzyć wrażliwe wyniki. Błąd klienta nie może więc automatycznie uruchamiać nieograniczonej serii nowych wyszukiwań.
Po żądaniu najpierw oceń status HTTP i tablicę GraphQL errors najwyższego poziomu. Także HTTP 200 może zawierać błędy GraphQL. Dopiero po tej kontroli zachowaj data.createSearch.urn. Zwróconej URN używaj bez zmian do pobierania statusu i wyników; nie rozkładaj ani nie rekonstruuj jej formatu. Status początkowy może być różny.
Dla wykonania klient zapisuje co najmniej UUID tenanta, tekst zapytania, odniesienie czasowe, Search-URN i czas rozpoczęcia. Search-URN oznacza całe wykonanie. Partition-URN oznacza podzadanie, a Event Resource Name pojedyncze zdarzenie. Tych identyfikatorów nie można stosować zamiennie.
Świadomie wykorzystuj istniejące wyszukiwania
Jeśli wolno użyć odpowiedniego wyszukiwania już trwającego lub zakończonego, alternatywą jest getOrCreateSearch:
{
"operationName": "GetOrCreateSearch",
"query": "mutation GetOrCreateSearch($input: CreateSearchInput) { getOrCreateSearch(input: $input) { urn status } }",
"variables": {
"input": {
"text": "from process where earliest = -1h | fields host_id, commandline, image_path"
}
}
}
Tutaj przejmowana jest URN z data.getOrCreateSearch.urn. Dopasowanie uwzględnia dane wejściowe i porównuje zapytania według ich kanonicznej reprezentacji strukturalnej, a nie tylko identycznego tekstu. Ponowne wykorzystanie nie gwarantuje świeżych wyników i nie może być przedstawiane w kliencie jako nowe wykonanie. Gdy zadanie wymaga nowego wykonania, świadomie użyj createSearch.
Jeśli po createSearch odpowiedź zostanie utracona z powodu timeoutu, wyszukiwanie mimo to może działać. Ślepe ponowienie może utworzyć kolejne wykonanie. Zapisz ten stan jako „utworzenie niepewne” i zdecyduj o wznowieniu zgodnie z wcześniej ustalonymi wymaganiami ponownego wykorzystania i świeżości. getOrCreateSearch nie stanowi późniejszego dowodu znalezienia dokładnie tego utraconego wykonania.
Sprawdzanie zakończenia, częściowych niepowodzeń i wygaśnięcia
Odpytaj stan przy użyciu zapisanej Search-URN. Zastąp <search-urn> wyłącznie faktycznie zwróconą wartością:
{
"operationName": "SearchDiagnostics",
"query": "query SearchDiagnostics($urn: URN!) { search(urn: $urn) { urn status errors expireTime outcome { success errors { urn errors } } searchPartitions { urn schemaType status errors } } }",
"variables": {
"urn": "<search-urn>"
}
}
Dopóki status ma wartość QUEUED lub IN_PROGRESS, klient czeka między odpytywaniami. Przed zakończeniem należy spodziewać się outcome.success: UNKNOWN. Odstęp odpytywania, na przykład pięć sekund, jest możliwą decyzją klienta, a nie gwarantowanym limitem usługi. Każde żądanie wymaga też timeoutu, a cały przebieg terminu końcowego odpowiedniego do obciążenia. Po jego przekroczeniu wykonanie pozostaje niewyjaśnione; zatrzymanie lokalnego odpytywania nie anuluje wyszukiwania na serwerze.
Przy status: COMPLETE osobno oceń outcome.success:
| Wartość | Znaczenie |
|---|---|
ALL | Wszystkie partycje zakończyły się powodzeniem. |
PARTIAL | Tylko część partycji zakończyła się powodzeniem. |
NONE | Żadna partycja nie zakończyła się powodzeniem. |
Dla PARTIAL ustal przed użyciem produkcyjnym, czy i do czego dopuszczalne są wyniki częściowe. Pełny raport dochodzenia nie może bez wyjaśnienia uznawać ich za całościowe ustalenia. Przy NONE nie istnieje pomyślnie przeszukany zakres pozwalający ogłosić brak zagrożenia. outcome.errors przypisuje komunikaty do partycji; searchPartitions podaje ich schemat, status i błędy. Nawet przy pomyślnym wykonaniu errors na poziomie wyszukiwania lub partycji może zawierać ostrzeżenia.
Za pomocą expireTime sprawdź też plan późniejszego pobierania: do tego czasu odczytaj wymagane wyniki i w razie dłuższego zapotrzebowania zapisz je we własnym zatwierdzonym systemie. Zapisana URN lub kursor nie przedłuża dostępności. Nie wyprowadzamy tutaj stałej TTL z pojedynczego przykładu.
Odczytaj wszystkie strony wyników
Po zakończeniu i ocenie wyniku wykonania zażądaj pierwszej strony bez cursor w zmiennych:
{
"operationName": "SearchResults",
"query": "query SearchResults($urn: URN!, $limit: Int, $cursor: String) { searchResults(urn: $urn, limit: $limit, cursor: $cursor) { fields { name baseType originSchemaTypes } values totals { total { value } subtotals { schemaType value } } nextCursor } }",
"variables": {
"urn": "<search-urn>",
"limit": 2
}
}
limit: 2 ułatwia kontrolę kolejności stron w pilotażu. Ogranicza wiersze na stronę, a nie łączną liczbę trafień. W kliencie produkcyjnym dobierz wielkość strony do przetwarzania, nie wyprowadzając z niej udokumentowanego maksimum ani limitu wszystkich wyników.
Po każdym pobraniu sprawdź status HTTP, GraphQL errors i oczekiwaną ścieżkę odpowiedzi. Dopiero potem przetwarzaj stronę. Nawet po COMPLETE pobranie wyników może jeszcze trwać; timeout odczytu nie dowodzi błędu wyszukiwania. Ponawiaj przejściowe błędy odczytu z ograniczonym backoffem, używając tej samej Search-URN i tego samego kursora. Konsument musi zapobiegać dwukrotnemu dodaniu ponownie odczytanej strony do eksportu.
Jeśli data.searchResults.nextCursor zawiera wartość, przenieś ją bez zmian do zmiennych tego samego żądania SearchResults:
{
"urn": "<search-urn>",
"limit": 2,
"cursor": "<next-cursor>"
}
To tylko zastępowana sekcja variables, nie kompletne body GraphQL. <next-cursor> pochodzi z bezpośrednio poprzedzającej strony przetworzonej poprawnie. Każdy kursor pozostaje związany z Search-URN, która go zwróciła. Nie interpretuj go, nie zmieniaj ani nie przenoś do innego wykonania. Kontynuuj, aż nextCursor będzie null lub go zabraknie. Powtórzony kursor lub przekroczony termin klienta traktuj jako błąd pobierania, nie pomyślny koniec.
Rozróżniaj wartości, metadane i sumy
values zawiera obiekty wierszy JSON, a nie listę kolumn SQL ani zakodowany w JSON ciąg additionalColumns jak w formacie wyników LES. Wpisy mogą zawierać zagnieżdżone obiekty i listy. fields opisuje dostępne nazwy i typy pól; wpis metadanych nie gwarantuje wypełnionej wartości w każdym wierszu. Obsługuj zarówno brakujące pola, jak i jawne null, nie utożsamiając ich automatycznie z pustym ciągiem lub zerem trafień.
baseType służy do interpretacji wartości. Na przykład TIMESTAMP_SECONDS odróżnia sekundy od TIMESTAMP_MILLISECONDS i TIMESTAMP_MICROSECONDS; TIMESTAMP_ISO_8601 oznacza ciąg ISO-8601. Typy list i map przetwarzaj jako kolekcje, nie pojedynczy skalar. expireTime jest również znacznikiem czasu ISO-8601. Metadane mogą nazywać pola zagnieżdżone notacją kropkową, np. process_file_hash.md5. Parser nie może zatem zakładać, że każda taka nazwa jest płaskim kluczem w obiekcie wiersza.
Opcjonalne dane totals.total i totals.subtotals odnoszą się odpowiednio do całego zbioru wyników i jego schematów, nie do długości bieżącej listy values. Pełne pobranie wymaga przetworzenia wszystkich stron i porównania zebranych wierszy z dostępnymi sumami. Brak sum nie uzasadnia wymyślania liczby; nadal wymagane są zakończenie sekwencji kursorów i udokumentowany zakres pobrania. Nawet pełna paginacja nie sprawia, że wynik PARTIAL staje się w pełni pomyślny.
Zachowaj projekcję QL i wzbogacanie
W przykładzie | fields host_id, commandline, image_path ogranicza pola zdarzeń zapytania QL. Zestaw selekcji GraphQL określa natomiast, czy odpowiedź zawiera sekcje takie jak fields, totals lub nextCursor. values jest skalarem JSON: poszczególnych pól wierszy nie można wybierać zagnieżdżonym zestawem selekcji GraphQL.
Wzbogacanie dodaje informacje pochodne. hostname i enrichSummary nie mogą znajdować się bezpośrednio w | fields. Zachowaj host_id do rozwiązywania nazwy hosta. Nawet wtedy rozwiązywalna nazwa nie jest gwarantowana. Pola wejściowe dla enrichSummary zależą od zdarzenia; węższa projekcja może skrócić podsumowanie. Przed ograniczeniem porównaj reprezentatywne zdarzenia ze wzbogaceniami wymaganymi przez konsumenta.
Projekcja może zmniejszyć odpowiedź. Nie dowodzi niższych kosztów skanowania ani szybszego wykonania. Pominięcie zbędnych sekcji odpowiedzi nie może w szczególności oznaczać utraty nextCursor, a tym samym możliwości pełnego pobrania.
Kontrolowane porównanie istniejącego klienta XDR Query
Przejście z historycznego SQL na Search-QL nie polega na zamianie URL ani mechanicznym tłumaczeniu SQL. Najpierw zinwentaryzuj dotychczasowe zapytania, wymagane pola i raporty wynikowe. Ogólne rozróżnienie API XDR pozostaje osobno istotne dla Cases, Detections i innych procesów.
Dla każdego zapytania historycznego porównuj w tej kolejności:
- Zapisz pytanie merytoryczne i potrzebne źródła. Tabele SQL nie uzasadniają bezpośredniego mapowania na schematy QL o tej samej nazwie; sprawdź osobno schemat i nazwy pól.
- Ustal identyczne jawne granice
earliestilatestdla obu wyszukiwań oraz udokumentuj odniesienie czasowe. Dwa kolejno wykonane zapytania „ostatnia godzina” nie są rzetelnym porównaniem równości. - Sprawdź porównania ciągów, wielkość liter i wyrażenia regularne. QL nie obsługuje złączeń SQL; złączenia i kolumny pochodne wymagają przeprojektowanego procesu merytorycznego. Bez ustalonego odpowiednika nie przełączaj klienta.
- Najpierw sprawdź zapytanie QL interaktywnie w Security Operations > Data Lake Search. Następnie wykonaj wyszukiwanie API z tymi samymi warunkami merytorycznymi.
- Porównaj reprezentatywne rekordy, obowiązkowe pola, typy, znaczniki czasu i wzbogacenia, nie tylko liczby trafień. Oba klienty muszą odczytać swoje wyniki w całości.
- Dostosuj nowego konsumenta do
values/fields, Search-URN i kursorów. Nie mapuj bezrefleksyjnie dawnych stanów RESTfinishedisucceededna jedno pole statusu GraphQL:COMPLETEioutcome.successpozostają osobnymi kontrolami.
Przed przełączeniem muszą też działać polityka częściowych niepowodzeń, ograniczone ponowienia, obsługa niepewnego utworzenia, wygaśnięcie i przechowywanie eksportów. Zatwierdzony pilotaż tenanta rejestruje zapytanie, okno czasu, wymagane pola i wszystkie strony, ale bez sekretów. Puste wyszukiwanie jest merytorycznie ocenione dopiero po sprawdzeniu źródła, okresu, filtrów, wyniku wykonania i pełnego odczytu wyników; nie oznacza ogólnego braku zagrożenia.
Do odbioru dotychczasowy klient XDR Query pozostaje uzgodnioną ścieżką operacyjną. Jeśli nowy proces zawiedzie, zatrzymaj przełączenie lub przywróć aplikację do wcześniej zachowanego klienta. Nie usuwa to już wyeksportowanych danych ani nie naprawia powstałych luk dowodowych. Późniejsze nowe wyszukiwanie może różnić się od pierwszego ze względu na inne odniesienia czasowe lub brak dawniej dostępnych danych.
Ukierunkowana diagnostyka błędów
- Żądanie odrzucone: Sprawdź URL,
X-GraphQL-Schema: default, body JSON, ważny token Bearer i właściwy UUID tenanta. Osobno wyjaśnij uwierzytelnianie i uprawnienie do operacji; nie szukaj regionu metodą prób. Nie umieszczaj sekretów w diagnostyce. - HTTP 200, ale brak użytecznych
data: Odczytajerrorsnajwyższego poziomu. Sprawdź zapytanie, typy zmiennych i żądane pola przed dalszym przetwarzaniem danych. COMPLETEzPARTIALlubNONE: Oceńoutcome.errors, błędy wyszukiwania i właściwesearchPartitions. Traktuj eksport jako niepełny albo wstrzymaj go według wcześniej zatwierdzonej reguły wyników częściowych, nie myląc tego z zerem trafień.- Brak nazwy hosta lub krótsze podsumowanie: Sprawdź projekcję i typ zdarzenia. Zachowaj
host_iddo rozwiązywania nazwy hosta; nie zastępuj brakujących wejść wzbogacania przezhostnamelubenrichSummaryw| fields. - Pobieranie zatrzymuje się lub kończy zbyt wcześnie: Sprawdź timeout żądania, termin całego procesu, niezmienioną URN, ostatnią poprawnie przetworzoną stronę i powiązanie kursora. Mały
limitnie jest limitem całego wyniku. - Zapisana URN nie zwraca później wyników: Sprawdź
expireTimei już zabezpieczone dane. Ani URN, ani kursor nie jest trwałym archiwum. Jeśli potrzebne jest nowe wykonanie, udokumentuj je jako nowe, nie jako odtworzenie pierwotnego wyniku.
API jest nadal rozwijane. Ogranicz klienta do udokumentowanych operacji createSearch, getOrCreateSearch, search i searchResults oraz obsługiwanych pól. Dodatkowe pola z introspekcji nie stanowią automatycznej zgody na implementację.