Hoppa till innehållet
Avanet
Mitt konto
Mitt konto

Laddar …

Sök i Sophos Fusion Data Lake med Search GraphQL API

Med Search GraphQL API v1 kan en egen applikation söka i historiska Sophos Fusion (tidigare Sophos Central) Data Lake med QL. Förloppet är asynkront: starta sökningen, spara dess Search-URN, kontrollera att körningen är klar och vilket utfall den fick och läs sedan alla resultatsidor. Enbart COMPLETE betyder inte att alla delar av sökningen lyckades.

API:et är publicerat sedan 12 oktober 2026. Det kompletterar befintliga API:er och kräver inget omedelbart byte från XDR Query API, som fortfarande är tillgängligt. Det ersätter inte heller Live Endpoint Search (LES): LES frågar anslutna endpoints med osquery-liknande SQL. Skillnaden mellan Classic Live Discover, Data Lake Search och LES hjälper dig att välja rätt dataväg.

Före den första begäran

Du behöver en tenant med de historiska data som ska sökas, lämpliga API Credentials, tenantens unika UUID och en HTTP-klient som kan skicka JSON-POST-begäranden och spara fullständiga svar. För exemplet måste tenanten innehålla processhändelser. Utan dessa data kan även en tekniskt lyckad sökning vara tom.

Hantera API-inloggningsuppgifter säkert beskriver maskinidentitet, OAuth-flödet med client_credentials, tenantkoppling och rotation. En partner- eller organisationsidentifierare är inte ett tenant-UUID. Vid flera tenanter väljs måltenanten med en godkänd entydig koppling, inte enbart efter visningsnamnet.

Den exakta minsta rollen och de behörigheter som licens och avtal måste medge för den aktuella Search-klienten ska klarläggas före produktionsgodkännande. Namnet på en generell service-principalroll bekräftar inte Search-behörighet. Tilldela därför inte Super Admin i förebyggande syfte om åtkomsten nekas.

Bestäm undersökningsfråga, tidsperiod och nödvändiga fält före starten. Processdata kan innehålla användarnamn, sökvägar och kommandorader med konfidentiellt innehåll. Frågor och exporter hör hemma i en godkänd miljö med reglerad åtkomst och lagring. Token och Client Secret får inte finnas i begärandeloggar, ärenden eller sparade exempelfiler. Inte heller fullständiga resultatrader får loggas okontrollerat.

Använd API:ets specifika målvärd

Följande operationer har samma begärandekontrakt:

POST https://api.taegis.sophos.com/graphql
Authorization: Bearer <access-token>
X-Tenant-ID: <tenant-uuid>
X-GraphQL-Schema: default
Content-Type: application/json

Ersätt <access-token> med aktuell OAuth-åtkomsttoken och <tenant-uuid> med kontrollerat UUID i HTTP-klienten. URL och huvuden är desamma för varje JSON-kropp nedan. Exemplen är begärandemallar. Anpassa värdena och kontrollera de faktiska svaren i den egna miljön.

Den regionala REST-värden från apiHosts.dataRegion är inte målvärden för detta Search-kontrakt. Flytta omvänt inte alla befintliga REST-klienter till GraphQL-värden. Värdnamnet garanterar inte heller lagringsplats eller dataresidens; sådana krav klarläggs utifrån gällande tenant- och avtalsvillkor.

Starta och följ en sökning entydigt

Skapa en ny körning med createSearch

Följande mall söker processhändelser från den senaste timmen och begränsar de valda händelsefälten. -1h är ett relativt tidsfönster för en första funktionskontroll; ange identiska uttryckliga tidsgränser inför en senare jämförelse med en annan klient.

{
  "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"
    }
  }
}

Kontrollera tenant, tidsperiod och dataomfattning före sändning. createSearch skapar och startar en ny sökkörning men ändrar inte endpointskyddets konfiguration. Körningen kan skapa arbete i tjänsten och känsliga resultat. Ett klientfel får därför inte automatiskt starta en obegränsad serie nya sökningar.

Bedöm först HTTP-statusen och GraphQL-arrayen errors på översta nivån efter begäran. Även HTTP 200 kan innehålla GraphQL-fel. Spara data.createSearch.urn först efter denna kontroll. Använd returnerad URN oförändrad för status- och resultathämtning; dela inte upp eller bygg om dess format. Den inledande statusen kan variera.

För körningen sparar klienten minst tenant-UUID, frågetext, tidsreferens, Search-URN och starttid. En Search-URN identifierar hela körningen. En Partition-URN identifierar däremot ett deluppdrag och ett Event Resource Name en enskild händelse. Identifierarna är inte utbytbara.

Återanvänd befintliga sökningar medvetet

Om en lämplig sökning som redan pågår eller har avslutats får användas är getOrCreateSearch ett alternativ:

{
  "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"
    }
  }
}

Här hämtas URN från data.getOrCreateSearch.urn. Matchningen tar hänsyn till indata och jämför frågor utifrån deras kanoniska strukturerade representation, inte bara identisk text. Återanvändning är ingen garanti för färska resultat och får inte visas som en ny körning i klienten. Använd medvetet createSearch när uppgiften kräver en ny körning.

Om svaret efter createSearch går förlorat på grund av timeout kan sökningen ändå pågå. En blind upprepning kan skapa ytterligare en körning. Registrera tillståndet som ”skapande oklart” och besluta om återstart enligt de tidigare fastställda kraven på återanvändning och aktualitet. getOrCreateSearch bevisar inte i efterhand att just den förlorade körningen hittades.

Kontrollera avslut, delfel och förfallotid

Fråga efter tillståndet med sparad Search-URN. Ersätt <search-urn> endast med det värde som faktiskt returnerats:

{
  "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>"
  }
}

Så länge status är QUEUED eller IN_PROGRESS väntar klienten mellan förfrågningarna. outcome.success: UNKNOWN är förväntat före avslut. Ett pollningsintervall på exempelvis fem sekunder är ett möjligt klientbeslut, inte en garanterad tjänstegräns. Varje begäran behöver dessutom en timeout och hela förloppet en tidsgräns som passar arbetsbelastningen. Därefter är körningen fortfarande oklar; att stoppa lokal pollning avbryter inte sökningen på servern.

Vid status: COMPLETE bedöms outcome.success separat:

VärdeBetydelse
ALLAlla partitioner lyckades.
PARTIALBara en del av partitionerna lyckades.
NONEIngen partition lyckades.

För PARTIAL bestäms före produktionsanvändning om och till vad delresultat är tillåtna. En fullständig undersökningsrapport får inte tyst behandla dem som ett samlat resultat. Vid NONE finns ingen framgångsrikt genomsökt omfattning att grunda ett klartecken på. outcome.errors kopplar meddelanden till partitionerna; searchPartitions ger deras schema, status och fel. Även efter en lyckad körning kan errors på sök- eller partitionsnivå innehålla varningar.

Kontrollera även hämtningsplanen med expireTime: nödvändiga resultat måste läsas före den tidpunkten och vid längre behov sparas i ett eget godkänt system. En sparad URN eller markör förlänger inte tillgängligheten. Ingen fast TTL härleds här från ett enstaka exempel.

Läs alla resultatsidor

Efter avslut och bedömning av körningsutfallet begärs första sidan utan cursor i variablerna:

{
  "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 gör sidföljden lätt att kontrollera i piloten. Det begränsar rader per sida, inte det totala antalet träffar. Välj för produktion en sidstorlek som passar bearbetningen, utan att härleda ett dokumenterat maximum eller en total resultatgräns ur den.

Kontrollera HTTP-status, GraphQL-errors och förväntad svarssökväg efter varje hämtning. Bearbeta sidan först därefter. Även efter COMPLETE kan resultathämtningen ta tid; en lästimeout bevisar inte sökfel. Upprepa tillfälliga läsfel med begränsad backoff och samma Search-URN och markör. Konsumenten måste hindra att en omläst sida hamnar två gånger i exporten.

Om data.searchResults.nextCursor innehåller ett värde kopieras det oförändrat till variablerna i samma SearchResults-begäran:

{
  "urn": "<search-urn>",
  "limit": 2,
  "cursor": "<next-cursor>"
}

Detta är bara den ersatta delen variables, inte en fullständig GraphQL-kropp. <next-cursor> kommer från den omedelbart föregående framgångsrikt bearbetade sidan. Varje markör är knuten till den Search-URN som gav den. Tolka, ändra eller överför den inte till en annan körning. Fortsätt tills nextCursor är null eller saknas. En upprepad markör eller överskriden klienttidsgräns behandlas som hämtningsfel, inte som ett lyckat slut.

Skilj värden, metadata och totalsummor åt

values innehåller JSON-radobjekt, inte en SQL-kolumnlista eller en JSON-kodad additionalColumns-sträng som i LES-resultatformatet. Posterna kan innehålla nästlade objekt och listor. fields beskriver tillgängliga fältnamn och typer; en metadatapost garanterar inte ett ifyllt värde på varje rad. Hantera både saknade fält och uttryckligt null utan att generellt likställa dem med en tom sträng eller noll träffar.

baseType används för att tolka värden. Exempelvis skiljer TIMESTAMP_SECONDS sekunder från TIMESTAMP_MILLISECONDS och TIMESTAMP_MICROSECONDS; TIMESTAMP_ISO_8601 betecknar en ISO-8601-sträng. Hantera list- och maptyper som samlingar, inte som en enskild skalär. Även expireTime är en ISO-8601-tidsstämpel. Metadata kan namnge nästlade fält med punktnotation som process_file_hash.md5. Parsern får därför inte anta att varje sådant namn är en platt nyckel i radobjektet.

De valfria uppgifterna totals.total och totals.subtotals avser hela resultatmängden respektive dess scheman, inte längden på den aktuella values-listan. För fullständig hämtning bearbetas alla sidor och insamlade rader stäms av mot tillgängliga totalsummor. Saknade totalsummor är inget skäl att hitta på ett antal; avslutad markörföljd och dokumenterad hämtningsomfattning krävs fortfarande. Inte ens fullständig paginering gör ett PARTIAL-resultat helt framgångsrikt.

Bevara QL-projektion och enrichment

I exemplet begränsar | fields host_id, commandline, image_path händelsefälten i QL-frågan. GraphQL-urvalet bestämmer däremot om svarsdelar som fields, totals eller nextCursor följer med. values är en JSON-skalär: dess enskilda radfält kan inte väljas genom ett nästlat GraphQL-urval.

Enrichment lägger till härledd information. hostname och enrichSummary får inte stå direkt i | fields. Behåll host_id för namnuppslagning av värden. Inte ens då garanteras ett namn som kan slås upp. Indatafälten för enrichSummary beror på händelsen; en snävare projektion kan korta sammanfattningen. Jämför därför representativa händelser med de berikningar konsumenten behöver före en begränsning.

En projektion kan minska svaret. Den bevisar varken lägre skanningskostnader eller snabbare körning. Att utelämna onödiga svarsdelar får i synnerhet inte innebära att nextCursor och därmed möjligheten till fullständig hämtning går förlorade.

Jämför en befintlig XDR Query-klient kontrollerat

Bytet från historisk SQL till Search-QL är varken ett URL-byte eller en mekanisk SQL-översättning. Inventera först befintliga frågor, nödvändiga fält och efterföljande rapporter. Den allmänna avgränsningen av XDR-API:er är fortfarande separat relevant för Cases, Detections och andra arbetsflöden.

Jämför varje historisk fråga i denna ordning:

  1. Dokumentera sakfrågan och nödvändiga källor. SQL-tabeller motiverar ingen direkt koppling till QL-scheman med samma namn; kontrollera schema och fältnamn var för sig.
  2. Ange identiska uttryckliga earliest- och latest-gränser för båda sökningarna och dokumentera tidsreferensen. Två efterföljande ”senaste timmen”-frågor är ingen korrekt likhetsjämförelse.
  3. Kontrollera strängjämförelser, skiftlägeskänslighet och reguljära uttryck. QL stöder inte SQL-joiner; joiner och härledda kolumner kräver ett omarbetat sakligt arbetsflöde. Byt inte utan klarlagd motsvarighet.
  4. Kontrollera först QL-frågan interaktivt under Security Operations > Data Lake Search. Kör sedan API-sökningen med samma sakliga villkor.
  5. Jämför representativa poster, obligatoriska fält, typer, tidsstämplar och enrichment, inte bara träffantal. Båda klienterna måste läsa sina respektive resultat fullständigt.
  6. Anpassa den nya konsumenten till values/fields, Search-URN och markörer. Mappa inte blint de gamla REST-tillstånden finished och succeeded till ett enda GraphQL-statusfält: COMPLETE och outcome.success förblir separata kontroller.

Före övergången måste även policy för delfel, begränsade återförsök, oklart skapande, förfallotid och exportlagring fungera. Den godkända tenantpiloten loggar fråga, tidsfönster, nödvändiga fält och alla sidor, men inga hemligheter. En tom sökning är sakligt bedömd först efter kontroll av källa, tidsperiod, filter, utfall och fullständigt lästa resultat; den är inget allmänt klartecken.

Fram till godkännande förblir den befintliga XDR Query-klienten den överenskomna driftvägen. Om det nya förloppet misslyckas stoppas bytet eller applikationen återförs till denna tidigare bevarade klient. Det raderar inga redan exporterade data och åtgärdar inte uppkomna bevisluckor. En senare ny sökning kan avvika från den första på grund av andra tidsreferenser eller data som inte längre finns.

Avgränsa fel systematiskt

  • Begäran avvisad: Kontrollera URL, X-GraphQL-Schema: default, JSON-kropp, giltig bearer-token och rätt tenant-UUID. Klarlägg autentisering och operationsspecifikt tillstånd separat; sök inte en region genom att prova dig fram. Ta inte med hemligheter i diagnostikutdata.
  • HTTP 200 men inga användbara data: Läs errors på översta nivån. Kontrollera fråga, variabeltyper och begärda fält innan efterföljande data bearbetas.
  • COMPLETE med PARTIAL eller NONE: Bedöm outcome.errors, sökfel och berörda searchPartitions. Behandla exporten som ofullständig eller håll den tillbaka enligt den tidigare godkända delresultatregeln; förväxla inte detta med noll träffar.
  • Inget värdnamn eller kortare sammanfattning: Kontrollera projektion och händelsetyp. Behåll host_id för namnuppslagning; ersätt inte saknade enrichment-indata med hostname eller enrichSummary i | fields.
  • Hämtningen fastnar eller slutar för tidigt: Kontrollera begärandetimeout, hela förloppets tidsgräns, oförändrad URN, senast framgångsrikt bearbetade sida och markörkoppling. Ett litet limit är ingen total resultatgräns.
  • Sparad URN ger senare inte längre resultat: Kontrollera expireTime och redan sparade data. Varken URN eller markör är ett permanent arkiv. Dokumentera en eventuell ny körning som en ny exekvering, inte som återställning av det ursprungliga resultatet.

API:et vidareutvecklas. Begränsa klienten till de dokumenterade operationerna createSearch, getOrCreateSearch, search och searchResults samt stödda fält. Ytterligare fält från introspektion innebär inget automatiskt implementeringsgodkännande.