Utveckla ASIM-parsers (Advanced Security Information Model)

ASIM-användare (Advanced Security Information Model) använder enande parser 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. Enhetliga parserkomponenter använder i sin tur källspecifika parser för att hantera de specifika detaljerna 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. Ett 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.

Utvecklingsprocess för anpassad ASIM-parser

I följande arbetsflöde beskrivs de övergripande stegen för att utveckla 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 filtreringsparser och en parameterlös parser för varje schema som är relevant för källan.

  5. Testa din parser.

  6. Distribuera parsarna i dina Microsoft Sentinel-arbetsytor.

  7. Uppdatera den relevanta ASIM-enhetliga parsern så att den refererar 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-distributionen. Bidragsgivna parsare kan också göras tillgängliga i alla arbetsytor som inbyggda parsare.

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

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 i molnet med 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.

Tip

Skapa en ny anpassad parser utifrån en befintlig parser för samma schema. Det är särskilt viktigt att använda en befintlig parser för att filtrera parser för att se till att de accepterar alla parametrar som krävs av schemat.

Planera kartläggning

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 tolkare

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 Logs. Parser-frågan har tre delar:

Filter>Tolka>Förbereda fält

Filtrering

Filtrering av de relevanta posterna

I många fall innehåller en tabell i Microsoft Sentinel flera typer av händelser. Ett 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 Sysmon-händelse 1 rapporterar skapande av processer och normaliseras därför till ProcessEvent-schemat. Sysmon-händelse 1-händelsen ingår i Event tabellen, så du filtrerar till endast Sysmon-processskapandehändelser med följande fråga:

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

Important

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 begränsar Infoblox DNS-parsern poster till endast Infoblox NIOS-källor genom att inkludera följande filter, vilket säkerställer att parsern endast bearbetar relevanta syslog-poster:

  | 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 värde som du väljer för parsern. Informera parseranvändarna 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 filtreringsparsrar ska du se till 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 korrekta upprepar du testet efter parsningen för att finjustera resultatet. Mer information finns i filtreringsoptimering.
  • Filtrera inte om parametern inte har definierats och fortfarande har standardvärdet.

Använd villkorliga predikat för att implementera valfri parserparameterfiltrering, så att parsern endast applicerar filter när anropare anger värden. 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)

För mer information om array_length funktionen och operatorn has_any , se Kusto-dokumentationen:

Optimering av filtrering

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 ==, has, och 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. Till exempel är användningen av 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-parsningsfragment. Parsern kontrollerar först att fältet SyslogMessage has innehåller ordet client. Termen kan dock användas på en annan plats i meddelandet, så efter parsning av Log_Type 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"

Note

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

Parsning

När sökfrågan har valt de relevanta posterna kan det vara nödvändigt att tolka 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() Description
funktionen split() Parsa en sträng med avgränsade värden.
parse_csv()-funktionen 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.
extract_all()-funktionen 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 hjälp av 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.
parse_json()-funktionen 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, extract, eller extract_all ger bättre prestanda.
funktionen parse_xml() Parsa värdena i en sträng som är formaterad som XML. Om endast några få 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 project-rename säkerställer du att fältet fortfarande hanteras som ett fysiskt fält och att hanteringen ger bättre prestanda. Till exempel mappar följande fråga källkontofält till deras normaliserade ASIM-aktorfält:

 | 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änds till exempel kolon som avgränsare i en MAC-adress, medan källan kan skicka en bindestrecksavgränsad 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.

Att se till att parsningsutdatafälten matchar den typ som definierats i schemat är också viktigt 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. Därför, när källfältet tilldelas, konvertera det numeriska värdet till en sträng med hjälp av extend och tostring istället för project-rename, så att det normaliserade fältet uppfyller schemats strängtypkrav:

  | 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 härleder Microsoft DNS-parsern ett normaliserat resultat av framgång eller misslyckande från källkodsspecifika händelse- och svarskoder. Parsern tilldelar EventResult fältet baserat på Event ID och svarskod med hjälp av ett iff sätt, 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. Följande exempel visar hur man skapar uppslagstabeller som mappar numeriska protokollidentifierare och DNS-svarskoder till deras normaliserade textetiketter, och sedan tillämpar dessa uppslagningar på den parsade datan 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 sökning är användbart och effektivt även när mappningen bara har två möjliga värden.

När mappningsvillkoren är mer komplexa kombinerar du iff, case och 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 bygger vidare på detta genom att använda resultatet av lookup-operationen om det är tillgängligt och annars ange ytterligare villkor. Använd detta tillvägagångssätt för att hantera omatchade uppslagsvärden genom att falla tillbaka på ytterligare villkor eller en standardetikett:

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

Microsoft Sentinel tillhandahåller inbyggda hjälpfunktioner för vanliga uppslagsvärden. Istället för att manuellt bygga ett datatable och lookup för välkända mappningar kan du använda dessa funktioner för att fylla i det normaliserade fältet direkt. Till exempel kan uppslagningen DnsResponseCodeName ovan implementeras med en av följande funktioner:


| extend DnsResponseCodeName = _ASIM_LookupDnsResponseCode(DnsResponseCode)

| invoke _ASIM_ResolveDnsResponseCode('DnsResponseCode')

Det första alternativet accepterar som en parameter det värde som ska slås upp 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 dessa fält. Fyll i standardberikningsfälten så att varje parsad post innehåller konsekvent produkt-, leverantörs- och schemametadata, 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 dina parsers ska ange är typfält, som anger typen 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 dock typen bestämmas utifrån det faktiska värdet. Till exempel, avgör om det parsade värdnamnet är ett fullt kvalificerat domännamn (FQDN) genom att kontrollera om det innehåller mer än ett segment:

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

Microsoft Sentinel tillhandahåller användbara funktioner för att hantera berikning. Till exempel, använd _ASIM_ResolveSrcFQDN hjälpfunktionen för att härleda fälten för normaliserad källvärdnamn, domän, domäntyp och FQDN från kolumnen Computer . Följande utdrag fyller automatiskt fälten SrcHostname, SrcDomain, , SrcDomainTypeSrcFQDN och baserat på värdet i Computer fältet.

  | 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 är 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 Description 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.

Till exempel, när du tolkar en anpassad logtabell, ta bort de återstående källkodsspecifika typade kolumnerna (såsom fält med _d, _s, , _beller _g suffix) så att parserutdata endast innehåller de normaliserade fält du tänker behålla:

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

Hantera parsningsvarianter

Important

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

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 i varje gren, före union.

Distribuera parsers

Distribuera parsers manuellt genom att kopiera dem till sidan Azure Monitor Logg 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å den relevanta mallen 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 portalen Azure eller PowerShell.

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

Tip

ARM-mallar kan kombinera olika resurser, så att tolkar kan driftsättas tillsammans med anslutningar, analysregler eller bevakningslistor, för att nämna några användbara exempel. Din parser kan till exempel hänvisa till en bevakningslista som har distribuerats tillsammans med den.

Testparsers

ASIM tillhandahåller testverktyg som du kan använda för att validera dina anpassade parsers. Med det sagt är parsers kod och ibland komplexa, och standardmetoder för kvalitetssäkring, såsom kodgranskningar, rekommenderas utöver automatiserad testning.

Installera ASIM-testverktyg

Innan du distribuerar ASIM-testverktyget, se till att du har 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.

När din arbetsplats uppfyller dessa krav, distribuera ASIM-testverktyget till den arbetsplatsen.

Validera utdataschemat

För att säkerställa att din parser producerar ett giltigt schema, kör följande schematestfråga på Microsoft Sentinel Logs-sidan. Detta kommando verifierar att din parsers utdatafält, typer och aliaser matchar det förväntade ASIM-schemat:

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

Hantera resultatet på följande sätt:

Error Action
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.
Det saknade fältet [<Fält>] är obligatoriskt när den obligatoriska 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.
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.
Saknas obligatoriskt alias för [<Fält>], som aliaserar befintlig kolumn [<Fält>]. Lägg till aliaset i parsern
Det rekommenderade aliaset [<Fält>] saknas för att representera den befintliga kolumnen [<Fält>] Lägg till aliaset i parsern
Saknar valfritt alias [<Fält>] som ska aliasera befintlig kolumn [<Fält>] Lägg till aliaset i parsern
Obligatoriskt alias [<Fält>] saknas, alias saknar kolumn [<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>]. Den ä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 Action
Rekommenderat fält saknas [<Fält>] Överväg att lägga till det här fältet i parsern.
Info Action
Rekommenderat alias saknas [<Fält>] alias som inte finns i kolumnen [<Fält>] Om du lägger till det aliaserade fältet i parsern måste du även lägga till det här aliaset.
Det saknas ett valfritt alias [<Fält>] för en icke-existerande kolumn [<Fält>] Om du lägger till det aliaserade fältet i parsern måste du även 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.

Note

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 säkerställa att din parser ger giltiga värden, använd ASIM-datatestaren för att validera fältvärden på ett urval av parserutdata och identifiera eventuella fel eller varningar. Kör följande fråga på Microsoft Sentinel Logs-sidan:

<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. Om en händelse inte innehåller ett EventSchema fält verifieras endast vanliga fält. Om ett schema specificeras som en parameter används detta schema för att testa alla poster. Detta är användbart för äldre parsare som inte anger fältet EventSchema .

Note

Ä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 som det största tal för vilket frågan inte överskrider tidsgränsen, eller ställ in tidsintervallet för frågan med hjälp av tidsintervallväljaren.

Hantera resultatet på följande sätt:

Message Action
(0) Fel: typmatchningsfel för kolumnen [<Field>]. Den ä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) Information: 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.
  • Ett fåtal tomma värden kan vara ett försumbart problem.

Note

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.

Bidra med tolkar

Du kanske vill bidra med parsern till den primära ASIM-distributionen. Om de godkänns kommer parserna att vara tillgängliga för alla kunder som inbyggda parser i ASIM.

Så här bidrar du med dina parsers:

Dokumentera accepterade varningar

Om varningar som listas av ASIM-testverktygen anses giltiga för en parser, dokumentera de accepterade varningarna i parsern YAML-filen med avsnittet Undantag. Följande YAML-exempel visar hur man registrerar accepterade parsertestvarningar i Exceptions avsnittet om parserdefinitionen:

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 bör vara en kort form av motsvarande ASIM-testarvarningsmeddelande, tillräckligt unik för att identifiera just den varningen. Värdet används för att matcha ASIM-testarvarningar under automatiserad testning och ignorera dessa matchade varningar.

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. Till exempel, för Infoblox DNS-parsern, använd följande fråga för att endast hämta de Infoblox NIOS Syslog-poster som parsern hanterar:
    Syslog
    | where ProcessName == "named"

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

  • Kör på Logs källtabellen i skärmen getschema för att inspektera tillgängliga kolumner och deras typer. Exportera denna schemainformation tillsammans med dina exempeldata. Till exempel, för Infoblox DNS-parsern är frågan:

    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 parsern använder.

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

Riktlinjer för att skicka 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 parsertesterna enligt testparsers.

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

Relaterat innehåll

Läs mer om ASIM-parsers:

Läs mer om ASIM i allmänhet:

  • Last updated on