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

Artikel
03/23/2023

ASIM-användare (Advanced Security Information Model) använder enande parsare 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 parsrar använder i sin tur källspecifika parsare för att hantera den specifika informationen om 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 parsare i följande situationer:

När enheten tillhandahåller händelser som passar ett ASIM-schema, men en källspecifik parsare 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. Exempel:
- Källenheten kan konfigureras för att skicka händelser på ett icke-standard sätt.
- 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 parsare 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.

Anpassad UTVECKLINGsprocess för ASIM-parser

Följande arbetsflöde beskriver de övergripande stegen för att utveckla en anpassad ASIM- och källspecifik parser:

Samla in exempelloggar.
Identifiera de scheman eller scheman som händelserna som skickas från källan representerar. Mer information finns i Schemaöversikt.
Mappa källhändelsefälten till det identifierade schemat eller schemana.
Utveckla en eller flera ASIM-parsare 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.
Testa parsern.
Distribuera parsarna till dina Microsoft Sentinel-arbetsytor.
Uppdatera den relevanta ASIM-enande parsern för att referera till den nya anpassade parsern. Mer information finns i Hantera ASIM-parsare.
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 parsare.

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

Tips

Titta också på webbseminariet för djupdykning på Microsoft Sentinel Normalizing Parsers and Normalized Content (Normaliserat innehåll ) eller granska det relaterade bildspelet. Mer information finns under Nästa steg.

Samla in exempelloggar

För att skapa effektiva ASIM-parsare 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:t och andra fält som kräver värdenormalisering.

Tips

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 informationen som är tillgänglig i källhändelsen eller -händelserna till det schema som du identifierade:

Mappa alla obligatoriska fält och gärna ä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 parsrar

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 . Parsningsfrågan har tre delar:

Filter>Tolka>Förbereda fält

Filtrering

Filtrera relevanta poster

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

Tabellen Syslog 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 rapporterar Sysmon händelse 1 att processen skapas och normaliseras därför till ProcessEvent-schemat . Händelsen Sysmon händelse 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 visningslista

I vissa fall innehåller själva händelsen inte information som tillåter 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 Sources_by_SourceType visningslista.

Om du vill använda ASimSourceType-visningslistan i dina parsers använder du _ASIM_GetSourceBySourceType funktionen i avsnittet parserfiltrering. Till exempel innehåller Dns-parsern Infoblox 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å fältet som innehåller källinformationen för källan. 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 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å parsningsparametrar

När du utvecklar filtreringsparsers kontrollerar du att parsern accepterar filtreringsparametrarna för det relevanta schemat, enligt beskrivningen i referensartikeln för schemat. Om du använder en befintlig parser som startpunkt ser du till att parsern innehåller rätt funktionssignatur. I de flesta fall är den faktiska filtreringskoden också liknande för filtrering av parsers 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.

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)

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 ==, has, och startswith. Användning av operatorer som contains eller matches regex påverkar prestanda dramatiskt.

Filtreringsrekommendationer för prestanda kanske inte alltid är enkla 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 korrekt ä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 SyslogMessage anger 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"

Anteckning

Parser bör inte filtreras 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.

KQL-operatorerna 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	Beskrivning
Split	Parsa en sträng med avgränsade värden.
parse_csv	Parsa en sträng med värden som är formaterade som en CSV-linje (kommaavgränsade värden).
parsa-kv	Extraherar strukturerad information från ett stränguttryck och representerar informationen i ett nyckel/värde-formulär.
parse	Parsa flera värden från en godtycklig sträng med ett mönster, vilket kan vara ett förenklat mönster med bättre prestanda eller ett reguljärt uttryck.
extract_all	Parsa enskilda värden från en godtycklig sträng med hjälp av ett reguljärt uttryck. `extract_all` har en liknande prestanda som `parse` om den senare använder ett reguljärt uttryck.
Extrahera	Extrahera ett enda värde från en godtycklig sträng med hjälp av ett reguljärt uttryck. Användning `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	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.
parse_xml	Parsa värdena i en sträng som är formaterad som XML. Om bara några få värden behövs från XML-koden, med hjälp av `parse`, `extract`eller `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 projektbyte säkerställer du att fältet fortfarande hanteras som ett fysiskt fält och att hanteringen av fältet är mer högpresterande. 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 avgränsad MAC-adress med bindestreck. 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. När du tilldelar källfältet används extend 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 vanligare 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 kombinerar iffdu , 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. Uppslag ovan kan till exempel DnsResponseCodeName implementeras med någon av följande funktioner:


| extend DnsResponseCodeName = _ASIM_LookupDnsResponseCode(DnsResponseCode)

| invoke _ASIM_ResolveDnsResponseCode('DnsResponseCode')

Det första alternativet accepterar värdet som ska sökas upp som en parameter och låter dig välja utdatafältet och därför vara 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 dina parsare 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 SrcUsername fältet. 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 att hantera berikning. Använd till exempel följande funktion för att automatiskt tilldela fälten SrcHostname, SrcDomainTypeSrcDomainoch 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 ä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 i relaterade Dst fält och Dvc fält. 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:

Operator	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 tillfälliga värden som används under parsningen, använder `project-away` du 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 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 på varje gren, före facket.

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:

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 parsningstyp, filtrering eller parameterlös.
Använd ASIM Yaml till ARM-mallkonverteraren för att konvertera YAML-filen till en ARM-mall.
Om du distribuerar en uppdatering tar du bort äldre versioner av funktionerna med hjälp av portalen eller funktionen ta bort PowerShell-verktyget.
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

Tips

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. Till exempel kan parsern referera till en visningslista som distribuerats tillsammans med den.

Testparsers

Det här avsnittet beskriver de testverktyg som ASIM tillhandahåller som gör att du kan testa dina parsers. Som sagt, parsare är kod, ibland komplexa, och standardkvalitetssäkringsmetoder som kodgranskningar rekommenderas utöver automatiserad testning.

Installera ASIM-testverktyg

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

Parsern distribueras.
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

Kontrollera att parsern skapar ett giltigt schema genom att använda ASIM-schematestaren genom att köra följande fråga på sidan Microsoft Sentinel-loggar :

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

Hantera resultaten 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 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.
Obligatoriskt alias saknas [<Fält>] alias för befintlig kolumn [<Fält>]	Lägg till aliaset i parsern
Rekommenderat alias saknas [<Fält>] alias för befintlig kolumn [<Fält>]	Lägg till aliaset i parsern
Det valfria aliaset [<Field>] saknas som alias för befintlig kolumn [<Fält>]	Lägg till aliaset i parsern
Obligatoriskt alias saknas [<Fält>] alias saknas 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`.

Information	Åtgärd
Rekommenderat fält saknas [<Fält>]	Överväg att lägga till det här fältet i parsern.

Information	Å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 även lägga till det här aliaset.
Det valfria aliaset [<Field>] 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 ä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.

Anteckning

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. Om en händelse inte innehåller något EventSchema fält verifieras bara vanliga fält. 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 .

Anteckning

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

Det här testet är resurskrävande 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 resultaten på följande sätt:

Meddelande	Åtgärd
(0) Fel: typmatchningsfel för kolumnen [<Field>]. 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 i listan) 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 transformera 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) Information: 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 exemplet. 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 parsats korrekt.
En handfull tomma värden kan vara ett försumbart problem.

Anteckning

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 parsers

Du kanske vill bidra med parsern till den primära ASIM-fördelningen. Om de godkänns blir parsarna tillgängliga för alla kunder 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 parsare 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 parsar YAML-filer i ASIM-parsningsmapparna (/Parsers/ASim<schema>/Parsers)
- Representativa exempeldata enligt riktlinjerna för inlämning 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 accepterade 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 bör 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 inlämning av exempel

Exempeldata behövs vid felsökning av parsningsproblem 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 endast extraherar från källtabellen de händelser som valts av parsern. 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, Där 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 parsningsindatatabellen. 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_<GitHubHanlde>.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 respektive namn <EventVendor>_<EventProduct>_<EventSchema>_SchemaTest.csv<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:

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

Anpassad UTVECKLINGsprocess för ASIM-parser

Samla in exempelloggar

Planera mappning

Utveckla parsrar

Filtrering

Filtrera relevanta poster

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

Filtrering baserat på parsningsparametrar

Filtreringsoptimering

Parsning

Normalisera

Mappa fältnamn

Normalisera fältformat och typ

Härledda fält och värden

Berikningsfält

Välj fält i resultatuppsättningen

Hantera parsningsvarianter

Distribuera parsers

Testparsers

Installera ASIM-testverktyg

Verifiera utdataschemat

Verifiera utdatavärdena

Bidra med parsers

Dokumentera accepterade varningar

Riktlinjer för inlämning av exempel

Riktlinjer för inlämning av testresultat

Nästa steg

Ytterligare resurser