Dela via

Utveckla ASIM-parsare (Advanced Security Information Model) (offentlig förhandsversion)

  • Artikel

ASIM-användare (Advanced Security Information Model) använder enande parsers i stället för tabellnamn i sina frågor, för att visa data i ett normaliserat format och för att inkludera alla data som är relevanta för schemat i frågan. Enande parsers använder i sin tur källspecifika parsers för att hantera den specifika informationen för varje källa.

Microsoft Sentinel tillhandahåller inbyggda, källspecifika parsare för många datakällor. Du kanske vill ändra eller utveckla dessa källspecifika parsers i följande situationer:

  • När enheten tillhandahåller händelser som passar ett ASIM-schema, men en källspecifik parser för enheten och det relevanta schemat inte är tillgängligt i Microsoft Sentinel.

  • När ASIM-källspecifika parsers är tillgängliga för din enhet, men enheten skickar händelser i en metod eller ett annat format än förväntat av ASIM-parsarna. Till exempel:

    • Källenheten kan konfigureras för att skicka händelser på ett sätt som inte är standard.

    • Enheten kan ha en annan version än den som stöds av ASIM-parsern.

    • Händelserna kan samlas in, ändras och vidarebefordras av ett mellanliggande system.

Information om hur parsers passar i ASIM-arkitekturen finns i ASIM-arkitekturdiagrammet.

Viktigt!

ASIM är för närvarande i förhandsversion. Tilläggsvillkoren för Azure Preview innehåller ytterligare juridiska villkor som gäller för Azure-funktioner som är i betaversion, förhandsversion eller på annat sätt ännu inte har släppts i allmän tillgänglighet.

Utvecklingsprocess för anpassad ASIM-parser

Följande arbetsflöde beskriver de övergripande stegen i utvecklingen av en anpassad ASIM- och källspecifik parser:

  1. Samla in exempelloggar.

  2. Identifiera de scheman eller scheman som händelserna som skickas från källan representerar. Mer information finns i Schemaöversikt.

  3. Mappa källhändelsefälten till det identifierade schemat eller scheman.

  4. Utveckla en eller flera ASIM-parsers för din källa. Du måste utveckla en parser för filtrering och en parameterlös parser för varje schema som är relevant för källan.

  5. Testa parsern.

  6. Distribuera parsarna till dina Microsoft Sentinel-arbetsytor.

  7. Uppdatera den relevanta ASIM-enande parsern för att referera till den nya anpassade parsern. Mer information finns i Hantera ASIM-parsers.

  8. Du kanske också vill bidra med dina parsers till den primära ASIM-fördelningen. Bidragna parsare kan också göras tillgängliga på alla arbetsytor som inbyggda parsers.

Den här artikeln vägleder dig genom processens utvecklings-, testnings- och distributionssteg.

Dricks

Titta också på webbseminariet djupdykning på Microsoft Sentinel Normalisera parsers och normaliserat innehåll eller granska det relaterade bildspelet. Mer information finns under Nästa steg.

Samla in exempelloggar

För att skapa effektiva ASIM-parsers behöver du en representativ uppsättning loggar, som i de flesta fall kräver att källsystemet konfigureras och ansluts till Microsoft Sentinel. Om du inte har källenheten tillgänglig kan du distribuera många enheter för utveckling och testning med molnbaserade betala per användning-tjänster.

Dessutom kan du hitta leverantörsdokumentationen och exemplen för loggarna för att påskynda utvecklingen och minska misstagen genom att säkerställa bred loggformattäckning.

En representativ uppsättning loggar bör innehålla:

  • Händelser med olika händelseresultat.
  • Händelser med olika svarsåtgärder.
  • Olika format för användarnamn, värdnamn och ID och andra fält som kräver värdenormalisering.

Dricks

Starta en ny anpassad parser med en befintlig parser för samma schema. Att använda en befintlig parser är särskilt viktigt för filtrering av parsers för att se till att de accepterar alla parametrar som krävs av schemat.

Planera mappning

Innan du utvecklar en parser mappar du den information som är tillgänglig i källhändelsen eller -händelserna till det schema som du identifierade:

  • Mappa alla obligatoriska fält och helst även rekommenderade fält.
  • Försök mappa all information som är tillgänglig från källan till normaliserade fält. Om det inte är tillgängligt som en del av det valda schemat bör du överväga att mappa till fält som är tillgängliga i andra scheman.
  • Mappa värden för fält vid källan till de normaliserade värden som tillåts av ASIM. Det ursprungliga värdet lagras i ett separat fält, till exempel EventOriginalResultDetails.

Utveckla parsers

Utveckla både en filtrering och en parameterlös parser för varje relevant schema.

En anpassad parser är en KQL-fråga som utvecklats på sidan Microsoft Sentinel-loggar. Parser-frågan har tre delar:

Filterparse>>Förbered fält

Filtrering

Filtrera relevanta poster

I många fall innehåller en tabell i Microsoft Sentinel flera typer av händelser. Till exempel:

  • Syslog-tabellen innehåller data från flera källor.
  • Anpassade tabeller kan innehålla information från en enda källa som tillhandahåller mer än en händelsetyp och som kan passa olika scheman.

Därför bör en parser först filtrera endast de poster som är relevanta för målschemat.

Filtrering i KQL görs med operatorn where . Till exempel bearbetar Sysmon händelse 1 skapande av rapporter och normaliseras därför till ProcessEvent-schemat . Händelsen Sysmon event 1 är en del av Event tabellen, så du använder följande filter:

Event | where Source == "Microsoft-Windows-Sysmon" and EventID == 1

Viktigt!

En parser bör inte filtrera efter tid. Frågan som använder parsern tillämpar ett tidsintervall.

Filtrera efter källtyp med hjälp av en bevakningslista

I vissa fall innehåller själva händelsen inte information som skulle tillåta filtrering för specifika källtyper.

Till exempel skickas Infoblox DNS-händelser som Syslog-meddelanden och är svåra att skilja från Syslog-meddelanden som skickas från andra källor. I sådana fall förlitar sig parsern på en lista över källor som definierar relevanta händelser. Den här listan finns i bevakningslistan för Sources_by_SourceType .

Om du vill använda ASimSourceType-visningslistan i dina parsers använder du _ASIM_GetSourceBySourceType funktionen i avsnittet parserfiltrering. Till exempel innehåller Infoblox DNS-parsern följande i filtreringsavsnittet:

  | where Computer in (_ASIM_GetSourceBySourceType('InfobloxNIOS'))

Så här använder du det här exemplet i parsern:

  • Ersätt Computer med namnet på det fält som innehåller källinformationen för din källa. Du kan behålla detta som Computer för alla parsare baserat på Syslog.

  • InfobloxNIOS Ersätt token med ett valfritt värde för parsern. Informera parsningsanvändare om att de måste uppdatera ASimSourceType visningslistan med det valda värdet, samt listan över källor som skickar händelser av den här typen.

Filtrering baserat på parserparametrar

När du utvecklar filtreringsparsers kontrollerar du att parsern accepterar filtreringsparametrarna för det relevanta schemat, enligt beskrivningen i referensartikeln för det schemat. Om du använder en befintlig parser som utgångspunkt ser du till att parsern innehåller rätt funktionssignatur. I de flesta fall är den faktiska filtreringskoden också liknande för filtrering av parsare för samma schema.

När du filtrerar kontrollerar du att du:

  • Filtrera innan du parsar med hjälp av fysiska fält. Om de filtrerade resultaten inte är tillräckligt exakta upprepar du testet efter parsning för att finjustera resultatet. Mer information finns i filtreringsoptimering.
  • Filtrera inte om parametern inte har definierats och fortfarande har standardvärdet.

I följande exempel visas hur du implementerar filtrering för en strängparameter, där standardvärdet vanligtvis är *, och för en listparameter, där standardvärdet vanligtvis är en tom lista.

srcipaddr=='*' or ClientIP==srcipaddr
array_length(domain_has_any) == 0 or Name has_any (domain_has_any)

Se mer information om följande objekt i Kusto-dokumentationen:

Filtreringsoptimering

Observera följande filtreringsrekommendationer för att säkerställa parserns prestanda:

  • Filtrera alltid på inbyggda fält i stället för parsade fält. Även om det ibland är enklare att filtrera med hjälp av parsade fält, påverkar det prestanda avsevärt.
  • Använd operatorer som ger optimerad prestanda. I synnerhet ==, hasoch startswith. Användning av operatorer som contains eller matches regex påverkar också prestanda avsevärt.

Filtreringsrekommendationer för prestanda kanske inte alltid är lätta att följa. Användning är till exempel has mindre exakt än contains. I andra fall är matchning av det inbyggda fältet, till exempel SyslogMessage, mindre exakt än att jämföra ett extraherat fält, till exempel DvcAction. I sådana fall rekommenderar vi att du fortfarande förfiltrerar med hjälp av en prestandaoptimeringsoperator över ett inbyggt fält och upprepar filtret med mer exakta villkor efter parsning.

Ett exempel finns i följande Infoblox DNS-parserfragment . Parsern kontrollerar först att fältet SyslogMessage innehåller has ordet client. Termen kan dock användas på en annan plats i meddelandet, så efter parsning Log_Type av fältet kontrollerar parsern igen att ordet client verkligen var fältets värde.

Syslog | where ProcessName == "named" and SyslogMessage has "client"
…
      | extend Log_Type = tostring(Parser[1]),
      | where Log_Type == "client"

Kommentar

Parsare bör inte filtrera efter tid, eftersom frågan som använder parsern redan filtrerar för tid.

Parsning

När frågan har valt relevanta poster kan den behöva parsa dem. Vanligtvis krävs parsning om flera händelsefält förmedlas i ett enda textfält.

De KQL-operatorer som utför parsning visas nedan, ordnade efter deras prestandaoptimering. Den första ger den mest optimerade prestandan, medan den sista ger minst optimerad prestanda.

Operator/funktion() beskrivning
funktionen split() Parsa en sträng med avgränsade värden.
funktionen parse_csv() Parsa en sträng med värden som är formaterade som en CSV-rad (kommaavgränsade värden).
parse-kv-operator Extraherar strukturerad information från ett stränguttryck och representerar informationen i ett nyckel/värde-formulär.
parsningsoperator Parsa flera värden från en godtycklig sträng med hjälp av ett mönster, vilket kan vara ett förenklat mönster med bättre prestanda eller ett reguljärt uttryck.
funktionen extract_all() Parsa enskilda värden från en godtycklig sträng med ett reguljärt uttryck. extract_all har en liknande prestanda som parse om den senare använder ett reguljärt uttryck.
funktionen extract() Extrahera ett enda värde från en godtycklig sträng med ett reguljärt uttryck.

Att använda extract ger bättre prestanda än parse eller extract_all om ett enda värde behövs. Att använda flera aktiveringar av extract över samma källsträng är dock mindre effektivt än en enskild parse eller extract_all och bör undvikas.
funktionen parse_json() Parsa värdena i en sträng formaterad som JSON. Om bara några få värden behövs från JSON, med hjälp av parse, extracteller extract_all ger bättre prestanda.
funktionen parse_xml() Parsa värdena i en sträng som är formaterad som XML. Om endast ett fåtal värden behövs från XML-koden, med hjälp av parse, extracteller extract_all ger bättre prestanda.

Normalisera

Mappa fältnamn

Den enklaste formen av normalisering är att byta namn på ett ursprungligt fält till dess normaliserade namn. Använd operatorn project-rename för det. Genom att använda projektbytet ser du till att fältet fortfarande hanteras som ett fysiskt fält och att hanteringen av fältet är mer högpresterande. Till exempel:

 | project-rename
    ActorUserId = InitiatingProcessAccountSid,
    ActorUserAadId = InitiatingProcessAccountObjectId,
    ActorUserUpn = InitiatingProcessAccountUpn,

Normalisera fältformat och typ

I många fall måste det ursprungliga värdet som extraheras normaliseras. I ASIM använder till exempel en MAC-adress kolon som avgränsare, medan källan kan skicka en avstavad MAC-adress. Den primära operatorn för att transformera värden är extend, tillsammans med en bred uppsättning KQL-sträng-, numeriska och datumfunktioner.

Dessutom är det viktigt att se till att parsningsutdatafälten matchar den typ som definierats i schemat för att parsarna ska fungera. Du kan till exempel behöva konvertera en sträng som representerar datum och tid till ett datetime-fält. Funktioner som todatetime och tohex är användbara i dessa fall.

Det ursprungliga unika händelse-ID:t kan till exempel skickas som ett heltal, men ASIM kräver att värdet är en sträng för att säkerställa bred kompatibilitet mellan datakällor. När du tilldelar källfältet använder extend du därför och tostring i stället för project-rename:

  | extend EventOriginalUid = tostring(ReportId),

Härledda fält och värden

Värdet för källfältet, när det har extraherats, kan behöva mappas till den uppsättning värden som angetts för målschemafältet. Funktionerna iff, caseoch lookup kan vara användbara för att mappa tillgängliga data till målvärden.

Till exempel tilldelar Microsoft DNS-parsern EventResult fältet baserat på händelse-ID och svarskod med hjälp av en iff instruktion enligt följande:

   extend EventResult = iff(EventId==257 and ResponseCode==0 ,'Success','Failure')

Om du vill mappa flera värden definierar du mappningen med operatorn datatable och använder lookup för att utföra mappningen. Vissa källor rapporterar till exempel numeriska DNS-svarskoder och nätverksprotokollet, medan schemat kräver en mer vanlig textetikettrepresentation för båda. I följande exempel visas hur du härleder de värden som behövs med hjälp av datatable och lookup:

   let NetworkProtocolLookup = datatable(Proto:real, NetworkProtocol:string)[
        6, 'TCP',
        17, 'UDP'
   ];
    let DnsResponseCodeLookup=datatable(DnsResponseCode:int,DnsResponseCodeName:string)[
      0,'NOERROR',
      1,'FORMERR',
      2,'SERVFAIL',
      3,'NXDOMAIN',
      ...
   ];
   ...
   | lookup DnsResponseCodeLookup on DnsResponseCode
   | lookup NetworkProtocolLookup on Proto

Observera att uppslag är användbart och effektivt även när mappningen bara har två möjliga värden.

När mappningsvillkoren är mer komplexa kan du kombinera iff, caseoch lookup. Exemplet nedan visar hur du kombinerar lookup och case. Exemplet lookup ovan returnerar ett tomt värde i fältet DnsResponseCodeName om uppslagsvärdet inte hittas. Exemplet case nedan utökar det genom att använda resultatet av åtgärden om det lookup är tillgängligt och ange ytterligare villkor i annat fall.

   | extend DnsResponseCodeName = 
      case (
        DnsResponseCodeName != "", DnsResponseCodeName,
        DnsResponseCode between (3841 .. 4095), 'Reserved for Private Use',
        'Unassigned'
      )

Microsoft Sentinel tillhandahåller praktiska funktioner för vanliga uppslagsvärden. Sökningen DnsResponseCodeName ovan kan till exempel implementeras med någon av följande funktioner:


| extend DnsResponseCodeName = _ASIM_LookupDnsResponseCode(DnsResponseCode)

| invoke _ASIM_ResolveDnsResponseCode('DnsResponseCode')

Det första alternativet accepterar som parameter värdet för sökning och låter dig välja utdatafältet och därför användbart som en allmän sökningsfunktion. Det andra alternativet är mer inriktat på parsers, tar som indata namnet på källfältet och uppdaterar det ASIM-fält som behövs, i det här fallet DnsResponseCodeName.

En fullständig lista över ASIM-hjälpfunktioner finns i ASIM-funktioner

Berikningsfält

Förutom de fält som är tillgängliga från källan innehåller en resulterande ASIM-händelse berikande fält som parsern ska generera. I många fall kan parsarna tilldela ett konstant värde till fälten, till exempel:

  | extend                  
     EventCount = int(1),
     EventProduct = 'M365 Defender for Endpoint',
     EventVendor = 'Microsoft',
     EventSchemaVersion = '0.1.0',
     EventSchema = 'ProcessEvent'

En annan typ av berikningsfält som parsarna ska ange är typfält, som anger vilken typ av värde som lagras i ett relaterat fält. Fältet anger till exempel SrcUsernameType vilken typ av värde som lagras i fältet SrcUsername . Mer information om typfält finns i entitetsbeskrivningen.

I de flesta fall tilldelas typer också ett konstant värde. I vissa fall måste typen dock fastställas baserat på det faktiska värdet, till exempel:

   DomainType = iif (array_length(SplitHostname) > 1, 'FQDN', '')

Microsoft Sentinel tillhandahåller användbara funktioner för hantering av berikning. Använd till exempel följande funktion för att automatiskt tilldela fälten SrcHostname, SrcDomainType SrcDomainoch SrcFQDN baserat på värdet i fältet Computer.

  | invoke _ASIM_ResolveSrcFQDN('Computer')

Den här funktionen anger fälten på följande sätt:

Datorfält Utdatafält
server1 SrcHostname: server1
SrcDomain, SrcDomainType, SrcFQDN alla tomma
server1.microsoft.com SrcHostname: server1
SrcDomain: microsoft.com
SrcDomainType: FQDN
SrcFQDN:server1.microsoft.com

Funktionerna _ASIM_ResolveDstFQDN och _ASIM_ResolveDvcFQDN utför en liknande uppgift som fyller de relaterade Dst fälten och Dvc fälten. En fullständig lista över ASIM-hjälpfunktioner finns i ASIM-funktioner

Välj fält i resultatuppsättningen

Parsern kan välja fält i resultatuppsättningen. Om du tar bort onödiga fält kan du förbättra prestanda och öka tydligheten genom att undvika förvirrande mellan normaliserade fält och återstående källfält.

Följande KQL-operatorer används för att välja fält i resultatuppsättningen:

Operatör beskrivning När du ska använda i en parser
project-away Tar bort fält. Använd project-away för specifika fält som du vill ta bort från resultatuppsättningen. Vi rekommenderar att du inte tar bort de ursprungliga fälten som inte normaliseras från resultatuppsättningen, såvida de inte skapar förvirring eller är mycket stora och kan ha prestandakonsekvenser.
projekt Markerar fält som fanns tidigare eller skapades som en del av -instruktionen och tar bort alla andra fält. Rekommenderas inte för användning i en parser eftersom parsern inte bör ta bort andra fält som inte är normaliserade.

Om du behöver ta bort specifika fält, till exempel temporära värden som används under parsningen, använder du project-away för att ta bort dem från resultaten.

När du till exempel parsar en anpassad loggtabell använder du följande för att ta bort de återstående ursprungliga fälten som fortfarande har en typbeskrivning:

    | project-away
        *_d, *_s, *_b, *_g

Hantera parsningsvarianter

Viktigt!

De olika varianterna representerar olika händelsetyper, som ofta mappas till olika scheman, utvecklar separata parsers

I många fall innehåller händelser i en händelseström varianter som kräver olika parsningslogik. Om du vill parsa olika varianter i en enskild parser använder du antingen villkorssatser som iff och caseeller använder en unionsstruktur.

Om du vill använda union för att hantera flera varianter skapar du en separat funktion för varje variant och använder union-instruktionen för att kombinera resultaten:

let AzureFirewallNetworkRuleLogs = AzureDiagnostics
    | where Category == "AzureFirewallNetworkRule"
    | where isnotempty(msg_s);
let parseLogs = AzureFirewallNetworkRuleLogs
    | where msg_s has_any("TCP", "UDP")
    | parse-where
        msg_s with           networkProtocol:string 
        " request from "     srcIpAddr:string
        ":"                  srcPortNumber:int
    …
    | project-away msg_s;
let parseLogsWithUrls = AzureFirewallNetworkRuleLogs
    | where msg_s has_all ("Url:","ThreatIntel:")
    | parse-where
        msg_s with           networkProtocol:string 
        " request from "     srcIpAddr:string
        " to "               dstIpAddr:string
    ...
union parseLogs,  parseLogsWithUrls…

För att undvika duplicerade händelser och överdriven bearbetning kontrollerar du att varje funktion startar genom att filtrera, med hjälp av interna fält, endast de händelser som den är avsedd att parsa. Om det behövs kan du också använda project-away på varje gren, före unionen.

Distribuera parsers

Distribuera parsers manuellt genom att kopiera dem till Azure Monitor-loggsidan och spara frågan som en funktion. Den här metoden är användbar för testning. Mer information finns i Skapa en funktion.

Om du vill distribuera ett stort antal parsers rekommenderar vi att du använder PARSER ARM-mallar på följande sätt:

  1. Skapa en YAML-fil baserat på relevant mall för varje schema och inkludera din fråga i den. Börja med YAML-mallen som är relevant för ditt schema och parsertyp, filtrering eller parameterlös.

  2. Använd ASIM Yaml till ARM-mallkonverteraren för att konvertera YAML-filen till en ARM-mall.

  3. Om du distribuerar en uppdatering tar du bort äldre versioner av funktionerna med hjälp av portalen eller funktionen ta bort PowerShell-verktyget.

  4. Distribuera mallen med hjälp av Azure Portal eller PowerShell.

Du kan också kombinera flera mallar till en enda distributionsprocess med hjälp av länkade mallar

Dricks

ARM-mallar kan kombinera olika resurser, så att parsare kan distribueras tillsammans med anslutningsappar, analysregler eller visningslistor för att nämna några användbara alternativ. Din parser kan till exempel referera till en visningslista som distribuerats tillsammans med den.

Testparsers

I det här avsnittet beskrivs att testverktyg som ASIM tillhandahåller som gör att du kan testa dina parsers. Med det sagt rekommenderas parsare kod, ibland komplexa och standardmetoder för kvalitetssäkring, till exempel kodgranskningar, utöver automatiserad testning.

Installera ASIM-testverktyg

Om du vill testa ASIM distribuerar du ASIM-testverktyget till en Microsoft Sentinel-arbetsyta där:

  • Parsern har distribuerats.
  • Källtabellen som används av parsern är tillgänglig.
  • Källtabellen som används av parsern fylls i med en varierad samling relevanta händelser.

Verifiera utdataschemat

Om du vill se till att parsern skapar ett giltigt schema använder du ASIM-schematestaren genom att köra följande fråga på sidan Microsoft Sentinel-loggar:

<parser name> | getschema | invoke ASimSchemaTester('<schema>')

Hantera resultatet på följande sätt:

Fel Åtgärd
Obligatoriskt fält saknas [<Fält>] Lägg till fältet i parsern. I många fall skulle detta vara ett härlett värde eller ett konstant värde, och inte ett fält som redan är tillgängligt från källan.
Fältet [<Fält>] saknas är obligatoriskt när obligatorisk kolumn [<Fält>] finns Lägg till fältet i parsern. I många fall anger det här fältet de typer av den befintliga kolumnen som det refererar till.
Fältet [<Fält>] saknas är obligatoriskt när kolumnen [<Fält>] finns Lägg till fältet i parsern. I många fall anger det här fältet de typer av den befintliga kolumnen som det refererar till.
Obligatoriskt alias [<Fält>] saknas som alias för befintlig kolumn [<Fält>] Lägg till aliaset i parsern
Rekommenderat alias [<Fält>] saknas som alias för befintlig kolumn [<Fält>] Lägg till aliaset i parsern
Ett valfritt alias [<Fält>] saknas som alias för befintlig kolumn [<Fält>] Lägg till aliaset i parsern
Obligatoriskt alias [<Fält>] saknas i kolumnen [<Fält>] Det här felet åtföljer ett liknande fel för det aliaserade fältet. Korrigera det aliaserade fältfelet och lägg till det här aliaset i parsern.
Typmatchningsfel för fältet [<Fält>]. Det är för närvarande [<Typ>] och bör vara [<Typ>] Kontrollera att typen av normaliserat fält är korrekt, vanligtvis med hjälp av en konverteringsfunktion som tostring.
Info Åtgärd
Rekommenderat fält saknas [<Fält>] Överväg att lägga till det här fältet i parsern.
Info Åtgärd
Rekommenderat alias [<Fält>] saknas för alias som inte finns i kolumnen [<Fält>] Om du lägger till det aliaserade fältet i parsern måste du också lägga till det här aliaset.
Valfritt alias [<Fält>] saknas för alias som inte finns i kolumnen [<Fält>] Om du lägger till det aliaserade fältet i parsern måste du också lägga till det här aliaset.
Valfritt fält saknas [<Fält>] Även om valfria fält ofta saknas är det värt att granska listan för att avgöra om något av de valfria fälten kan mappas från källan.
Extra onormaliserat fält [<Fält>] Även om onormaliserade fält är giltiga är det värt att granska listan för att avgöra om något av de onormaliserade värdena kan mappas till ett valfritt fält.

Kommentar

Fel förhindrar att innehåll som använder parsern fungerar korrekt. Varningar hindrar inte innehåll från att fungera, men kan försämra resultatets kvalitet.

Verifiera utdatavärdena

För att se till att parsern genererar giltiga värden använder du ASIM-datatestaren genom att köra följande fråga på sidan Microsoft Sentinel-loggar:

<parser name> | limit <X> | invoke ASimDataTester ('<schema>')

Det är valfritt att ange ett schema. Om ett schema inte har angetts används fältet EventSchema för att identifiera schemat som händelsen ska följa. Ig en händelse innehåller inte ett EventSchema fält, endast vanliga fält verifieras. Om ett schema anges som en parameter används det här schemat för att testa alla poster. Detta är användbart för äldre parsare som inte anger fältet EventSchema .

Kommentar

Även om ett schema inte har angetts behövs tomma parenteser efter funktionsnamnet.

Det här testet är resursintensivt och kanske inte fungerar på hela datamängden. Ange X till det största talet som frågan inte överskrider tidsgränsen för, eller ange tidsintervallet för frågan med hjälp av tidsintervallväljaren.

Hantera resultatet på följande sätt:

Meddelande Åtgärd
(0) Fel: typmatchningsfel för kolumnen [<Fält>]. Det är för närvarande [<Typ>] och bör vara [<Typ>] Kontrollera att typen av normaliserat fält är korrekt, vanligtvis med hjälp av en konverteringsfunktion som tostring.
(0) Fel: Ogiltiga värden (upp till 10 listade) för fältet [<Fält>] av typen [<Logisk typ>] Kontrollera att parsern mappar rätt källfält till utdatafältet. Om den mappas korrekt uppdaterar du parsern för att omvandla källvärdet till rätt typ, värde eller format. Mer information om rätt värden och format för varje logisk typ finns i listan över logiska typer .

Observera att testverktyget endast visar ett exempel på 10 ogiltiga värden.
(1) Varning: Tomt värde i obligatoriskt fält [<Fält>] Obligatoriska fält ska fyllas i, inte bara definieras. Kontrollera om fältet kan fyllas i från andra källor för poster som den aktuella källan är tom för.
(2) Info: Tomt värde i rekommenderat fält [<Fält>] Rekommenderade fält bör vanligtvis fyllas i. Kontrollera om fältet kan fyllas i från andra källor för poster som den aktuella källan är tom för.
(2) Info: Tomt värde i valfritt fält [<Fält>] Kontrollera om det aliaserade fältet är obligatoriskt eller rekommenderat och i så fall om det kan fyllas i från andra källor.

Många av meddelandena rapporterar också antalet poster som genererade meddelandet och deras procentandel av det totala urvalet. Den här procentandelen är en bra indikator på problemets betydelse. Till exempel för ett rekommenderat fält:

  • 90 % tomma värden kan tyda på ett allmänt parsningsproblem.
  • 25 % tomma värden kan tyda på en händelsevariant som inte parsades korrekt.
  • En handfull tomma värden kan vara ett försumbart problem.

Kommentar

Fel förhindrar att innehåll som använder parsern fungerar korrekt. Varningar hindrar inte innehåll från att fungera, men kan försämra resultatets kvalitet.

Contribute-parsers

Du kanske vill bidra med parsern till den primära ASIM-fördelningen. Om det godkänns blir parsarna tillgängliga för varje kund som inbyggda ASIM-parsare.

Så här bidrar du med dina parsers:

  • Utveckla både en filtreringsparser och en parameterlös parser.
  • Skapa en YAML-fil för parsern enligt beskrivningen i Distribuera parsers ovan.
  • Kontrollera att parsarna klarar alla tester utan fel. Om några varningar finns kvar dokumenterar du dem i YAML-filen parser.
  • Skapa en pull-begäran mot Microsoft Sentinel GitHub-lagringsplatsen, inklusive:
    • Dina parsers YAML-filer i ASIM-parsningsmapparna (/Parsers/ASim<schema>/Parsers)
    • Representativa exempeldata enligt riktlinjerna för insändning av exempel.
    • Testresultat enligt riktlinjerna för inlämning av testresultat.

Dokumentera accepterade varningar

Om varningar som anges av ASIM-testverktygen anses vara giltiga för en parser dokumenterar du de godkända varningarna i YAML-parsningsfilen med hjälp av avsnittet Undantag enligt exemplet nedan.

Exceptions:
- Field: DnsQuery 
  Warning: Invalid value
  Exception: May have values such as "1164-ms-7.1440-9fdc2aab.3b2bd806-978e-11ec-8bb3-aad815b5cd42" which are not valid domains names. Those are related to TKEY RR requests.
- Field: DnsQuery
  Warning: Empty value in mandatory field
  Exception: May be empty for requests for root servers and for requests for RR type DNSKEY

Varningen som anges i YAML-filen ska vara en kort form av varningsmeddelandet som unikt identifierar. Värdet används för att matcha varningsmeddelanden när automatiserade tester utförs och ignorera dem.

Riktlinjer för insändning av exempel

Exempeldata behövs vid felsökning av parserproblem och för att säkerställa att framtida uppdateringar av parsern överensstämmer med äldre exempel. Exemplen som du skickar bör innehålla alla händelsevarianter som parsern stöder. Kontrollera att exempelhändelserna innehåller alla möjliga händelsetyper, händelseformat och variationer, till exempel händelser som representerar lyckad och misslyckad aktivitet. Kontrollera också att variationer i värdeformat representeras. Om ett värdnamn till exempel kan representeras som ett FQDN eller ett enkelt värdnamn, bör exempelhändelserna innehålla båda formaten.

Använd följande steg för att skicka händelseexemplen:

  • Logs På skärmen kör du en fråga som extraherar endast de händelser som valts av parsern från källtabellen. För Dns-parsern Infoblox använder du till exempel följande fråga:
    Syslog
    | where ProcessName == "named"

  • Exportera resultaten med alternativet Exportera till CSV till en fil med namnet <EventVendor>_<EventProduct>_<EventSchema>_IngestedLogs.csv, Var EventProduct, EventProductoch EventSchema är de värden som tilldelas av parsern till dessa fält.

  • Logs På skärmen kör du en fråga som matar ut schemat eller parser-indatatabellen. För samma Infoblox DNS-parser är frågan till exempel:

    Syslog
    | getschema

  • Exportera resultaten med alternativet Exportera till CSV till en fil med namnet <TableName>_schema.csv, där TableName är namnet på källtabellen som parsaren använder.

  • Inkludera båda filerna i din PR i mappen /Sample Data/ASIM. Om filen redan finns lägger du till ditt GitHub-handtag i namnet, till exempel: <EventVendor>_<EventProduct>_<EventSchema>_SchemaTest_<GitHubHandle>.csv

Riktlinjer för inlämning av testresultat

Testresultat är viktiga för att verifiera parserns korrekthet och förstå eventuella rapporterade undantag.

Använd följande steg för att skicka dina testresultat:

  • Kör parsningstesterna och beskrivs i avsnittet tester .

  • och exportera testresultaten med alternativet Exportera till CSV till filer med namnet <EventVendor>_<EventProduct>_<EventSchema>_SchemaTest.csv respektive <EventVendor>_<EventProduct>_<EventSchema>_DataTest.csv .

  • Inkludera båda filerna i din PR i mappen /Parsers/ASim<schema>/Tests.

Nästa steg

I den här artikeln beskrivs hur du utvecklar ASIM-parsare.

Läs mer om ASIM-parsers:

Läs mer om ASIM i allmänhet: