ASIM-parsers (Advanced Security Information Model) ontwikkelen (openbare preview)

  • Artikel

ASIM-gebruikers (Advanced Security Information Model) gebruiken unifying parsers in plaats van tabelnamen in hun query's om gegevens in een genormaliseerde indeling weer te geven en om alle gegevens op te nemen die relevant zijn voor het schema in de query. Parseringsfuncties op hun beurt gebruiken bronspecifieke parsers om de specifieke details van elke bron te verwerken.

Microsoft Sentinel biedt ingebouwde, bronspecifieke parsers voor veel gegevensbronnen. In de volgende situaties kunt u deze bronspecifieke parsers wijzigen of ontwikkelen:

  • Wanneer uw apparaat gebeurtenissen biedt die in een ASIM-schema passen, maar er geen bronspecifieke parser voor uw apparaat en het relevante schema beschikbaar is in Microsoft Sentinel.

  • Wanneer ASIM-bronspecifieke parsers beschikbaar zijn voor uw apparaat, maar uw apparaat gebeurtenissen verzendt in een methode of een andere indeling dan verwacht door de ASIM-parsers. Bijvoorbeeld:

    • Uw bronapparaat kan zijn geconfigureerd om gebeurtenissen op een niet-standaard manier te verzenden.

    • Uw apparaat heeft mogelijk een andere versie dan de versie die wordt ondersteund door de ASIM-parser.

    • De gebeurtenissen kunnen worden verzameld, gewijzigd en doorgestuurd door een tussenliggend systeem.

Raadpleeg het diagram ASIM-architectuur om te begrijpen hoe parsers binnen de ASIM-architectuur passen.

Belangrijk

ASIM is momenteel beschikbaar als PREVIEW-versie. De Aanvullende voorwaarden voor Azure-previews omvatten aanvullende juridische voorwaarden die van toepassing zijn op Azure-functies die in bèta of preview zijn of die anders nog niet algemeen beschikbaar zijn.

Ontwikkelingsproces voor aangepaste ASIM-parser

In de volgende werkstroom worden de stappen op hoog niveau beschreven voor het ontwikkelen van een aangepaste ASIM, bronspecifieke parser:

  1. Verzamel voorbeeldlogboeken.

  2. Identificeer de schema's of schema's die de gebeurtenissen vertegenwoordigen die vanuit de bron worden verzonden. Zie Schemaoverzicht voor meer informatie.

  3. Wijs de bron gebeurtenisvelden toe aan het geïdentificeerde schema of schema's.

  4. Ontwikkel een of meer ASIM-parsers voor uw bron. U moet een filterparser en een parameterloze parser ontwikkelen voor elk schema dat relevant is voor de bron.

  5. Test de parser.

  6. Implementeer de parsers in uw Microsoft Sentinel-werkruimten.

  7. Werk de relevante ASIM-unifying-parser bij om te verwijzen naar de nieuwe aangepaste parser. Zie ASIM-parsers beheren voor meer informatie.

  8. Mogelijk wilt u ook uw parsers bijdragen aan de primaire ASIM-distributie. Bijgedragen parsers kunnen ook beschikbaar worden gesteld in alle werkruimten als ingebouwde parsers.

In dit artikel wordt u begeleid bij de stappen voor het ontwikkelen, testen en implementeren van het proces.

Tip

Bekijk ook de Deep Dive Webinar op Microsoft Sentinel Normalizing Parsers and Normalized Content of bekijk de gerelateerde diaserie. Zie voor meer informatie Volgende stappen.

Voorbeeldlogboeken verzamelen

Als u effectieve ASIM-parsers wilt bouwen, hebt u een representatieve set logboeken nodig. In de meeste gevallen moet u het bronsysteem instellen en verbinden met Microsoft Sentinel. Als u het bronapparaat niet beschikbaar hebt, kunt u met cloudservices voor betalen per gebruik veel apparaten implementeren voor ontwikkeling en testen.

Daarnaast kan het vinden van de documentatie van de leverancier en voorbeelden voor de logboeken helpen de ontwikkeling te versnellen en fouten te verminderen door een brede dekking van de logboekindeling te garanderen.

Een representatieve set logboeken moet het volgende bevatten:

  • Gebeurtenissen met verschillende gebeurtenisresultaten.
  • Gebeurtenissen met verschillende antwoordacties.
  • Verschillende indelingen voor gebruikersnaam, hostnaam en id's, en andere velden waarvoor waardenormalisatie is vereist.

Tip

Start een nieuwe aangepaste parser met behulp van een bestaande parser voor hetzelfde schema. Het gebruik van een bestaande parser is met name belangrijk voor het filteren van parsers om ervoor te zorgen dat ze alle parameters accepteren die door het schema zijn vereist.

Toewijzing plannen

Voordat u een parser ontwikkelt, wijst u de informatie die beschikbaar is in de bron-gebeurtenis of -gebeurtenissen toe aan het schema dat u hebt geïdentificeerd:

  • Wijs alle verplichte velden en bij voorkeur ook aanbevolen velden toe.
  • Probeer alle informatie die beschikbaar is vanuit de bron toe te wijzen aan genormaliseerde velden. Als dit niet beschikbaar is als onderdeel van het geselecteerde schema, kunt u overwegen velden toe te wijzen die beschikbaar zijn in andere schema's.
  • Wijs waarden voor velden aan de bron toe aan de genormaliseerde waarden die zijn toegestaan door ASIM. De oorspronkelijke waarde wordt opgeslagen in een afzonderlijk veld, zoals EventOriginalResultDetails.

Parsers ontwikkelen

Ontwikkel zowel een filter- als een parameterloze parser voor elk relevant schema.

Een aangepaste parser is een KQL-query die is ontwikkeld op de pagina Microsoft Sentinel-logboeken . De parserquery bestaat uit drie onderdelen:

Filter>Parse>Velden voorbereiden

Filteren

De relevante records filteren

In veel gevallen bevat een tabel in Microsoft Sentinel meerdere typen gebeurtenissen. Bijvoorbeeld:

  • De Syslog-tabel bevat gegevens uit meerdere bronnen.
  • Aangepaste tabellen kunnen informatie uit één bron bevatten die meer dan één gebeurtenistype biedt en die geschikt is voor verschillende schema's.

Daarom moet een parser eerst alleen de records filteren die relevant zijn voor het doelschema.

Filteren in KQL wordt uitgevoerd met behulp van de where operator. Sysmon-gebeurtenis 1 rapporteert bijvoorbeeld het maken van processen en is daarom genormaliseerd voor het schema ProcessEvent. De gebeurtenis Sysmon-gebeurtenis 1 maakt deel uit van de Event tabel, dus u gebruikt het volgende filter:

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

Belangrijk

Een parser mag niet filteren op tijd. Met de query die de parser gebruikt, wordt een tijdsbereik toegepast.

Filteren op brontype met behulp van een volglijst

In sommige gevallen bevat de gebeurtenis zelf geen informatie waarmee kan worden gefilterd op specifieke brontypen.

Dns-gebeurtenissen van Infoblox worden bijvoorbeeld verzonden als Syslog-berichten en zijn moeilijk te onderscheiden van Syslog-berichten die zijn verzonden vanuit andere bronnen. In dergelijke gevallen is de parser afhankelijk van een lijst met bronnen die de relevante gebeurtenissen definiëren. Deze lijst wordt bijgehouden in de Sources_by_SourceType volglijst.

Als u de volglijst ASimSourceType in uw parsers wilt gebruiken, gebruikt u de _ASIM_GetSourceBySourceType functie in de sectie parserfiltering. De Infoblox DNS-parser bevat bijvoorbeeld het volgende in de filtersectie:

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

Ga als volgt te werk om dit voorbeeld in uw parser te gebruiken:

  • Vervang door Computer de naam van het veld dat de brongegevens voor uw bron bevat. U kunt dit behouden als Computer voor alle parsers op basis van Syslog.

  • Vervang het InfobloxNIOS token door een waarde naar keuze voor uw parser. Informeer parsergebruikers dat ze de ASimSourceType volglijst moeten bijwerken met behulp van de geselecteerde waarde, evenals de lijst met bronnen die gebeurtenissen van dit type verzenden.

Filteren op basis van parserparameters

Wanneer u filterparser ontwikkelt, moet u ervoor zorgen dat de parser de filterparameters voor het relevante schema accepteert, zoals beschreven in het naslagartikel voor dat schema. Als u een bestaande parser als uitgangspunt gebruikt, zorgt u ervoor dat uw parser de juiste functiehandtekening bevat. In de meeste gevallen is de werkelijke filtercode ook vergelijkbaar voor het filteren van parsers voor hetzelfde schema.

Zorg er bij het filteren voor dat u het volgende doet:

  • Filter vóór parseren met behulp van fysieke velden. Als de gefilterde resultaten niet nauwkeurig genoeg zijn, herhaalt u de test na het parseren om de resultaten te verfijnen. Zie Optimalisatie van filteren voor meer informatie.
  • Filter niet als de parameter niet is gedefinieerd en nog steeds de standaardwaarde heeft.

In de volgende voorbeelden ziet u hoe u filters implementeert voor een tekenreeksparameter, waarbij de standaardwaarde meestal '*' is, en voor een lijstparameter, waarbij de standaardwaarde meestal een lege lijst is.

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

Optimalisatie van filteren

Let op de volgende filteraanbevelingen om de prestaties van de parser te garanderen:

  • Filter altijd op ingebouwde velden in plaats van geparseerde velden. Hoewel het soms eenvoudiger is om te filteren met behulp van geparseerde velden, heeft dit een grote invloed op de prestaties.
  • Gebruik operators die geoptimaliseerde prestaties bieden. Met name , ==hasen startswith. Het gebruik van operators zoals contains of matches regex heeft ook een grote invloed op de prestaties.

Aanbevelingen voor het filteren van prestaties zijn niet altijd eenvoudig te volgen. Het gebruik has is bijvoorbeeld minder nauwkeurig dan contains. In andere gevallen is het afstemmen van het ingebouwde veld, zoals SyslogMessage, minder nauwkeurig dan het vergelijken van een geëxtraheerd veld, zoals DvcAction. In dergelijke gevallen raden we u aan om nog steeds vooraf te filteren met behulp van een operator voor het optimaliseren van prestaties op een ingebouwd veld en het filter te herhalen met behulp van nauwkeurigere voorwaarden na het parseren.

Zie het volgende Infoblox DNS-parserfragment voor een voorbeeld. De parser controleert eerst of het veld has SyslogMessage het woord bevat client. De term kan echter op een andere plaats in het bericht worden gebruikt, dus na het parseren van het Log_Type veld, controleert de parser opnieuw of het woord client inderdaad de waarde van het veld was.

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

Notitie

Parsers mogen niet filteren op tijd, omdat de query die de parser gebruikt, al op tijd filtert.

Parsing

Zodra de query de relevante records selecteert, moet deze mogelijk worden geparseerd. Normaal gesproken is parseren nodig als meerdere gebeurtenisvelden worden overgebracht in één tekstveld.

De KQL-operators die parseren uitvoeren, worden hieronder vermeld, geordend op hun prestatieoptimalisatie. De eerste biedt de meest geoptimaliseerde prestaties, terwijl de laatste de minst geoptimaliseerde prestaties biedt.

Operator Beschrijving
Split Parseert een tekenreeks met waarden met scheidingstekens.
parse_csv Parseert een tekenreeks met waarden die zijn opgemaakt als een CSV-regel (door komma's gescheiden waarden).
parse-kv Extraheert gestructureerde informatie uit een tekenreeksexpressie en vertegenwoordigt de informatie in een sleutel-/waardeformulier.
parse Parseert meerdere waarden uit een willekeurige tekenreeks met behulp van een patroon. Dit kan een vereenvoudigd patroon met betere prestaties of een reguliere expressie zijn.
extract_all Parseert enkele waarden uit een willekeurige tekenreeks met behulp van een reguliere expressie. extract_all heeft een vergelijkbare prestaties parse als als de laatste een reguliere expressie gebruikt.
Extract Eén waarde extraheren uit een willekeurige tekenreeks met behulp van een reguliere expressie.

Het gebruik extract biedt betere prestaties dan parse of extract_all als er één waarde nodig is. Het gebruik van meerdere activeringen van extract via dezelfde brontekenreeks is echter minder efficiënt dan één parse of extract_all en moet worden vermeden.
parse_json Parseert de waarden in een tekenreeks die is opgemaakt als JSON. Als er slechts een paar waarden nodig zijn van de JSON, biedt het gebruik van parse, extractof extract_all betere prestaties.
parse_xml Parseert de waarden in een tekenreeks die is opgemaakt als XML. Als er slechts een paar waarden nodig zijn voor de XML, biedt het gebruik van parse, extractof extract_all betere prestaties.

Normaliseren

Toewijzingsveldnamen

De eenvoudigste vorm van normalisatie is het wijzigen van de naam van een oorspronkelijk veld in de genormaliseerde naam. Gebruik hiervoor de operator project-rename . Als u projectnaam wijzigt, zorgt u ervoor dat het veld nog steeds wordt beheerd als een fysiek veld en dat de verwerking van het veld beter presteert. Bijvoorbeeld:

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

Indeling en type van velden normaliseren

In veel gevallen moet de oorspronkelijke geëxtraheerde waarde worden genormaliseerd. In ASIM gebruikt een MAC-adres bijvoorbeeld dubbele punten als scheidingsteken, terwijl de bron een door een afbreekstreepje gescheiden MAC-adres kan verzenden. De primaire operator voor het transformeren van waarden is extend, naast een brede set KQL-tekenreeksen, numerieke en datumfuncties.

Bovendien is het essentieel dat parseruitvoervelden overeenkomen met het type dat is gedefinieerd in het schema, zodat parsers werken. U moet bijvoorbeeld een tekenreeks die de datum en tijd vertegenwoordigt, converteren naar een datum/tijd-veld. Functies zoals todatetime en tohex zijn handig in deze gevallen.

De oorspronkelijke unieke gebeurtenis-id kan bijvoorbeeld worden verzonden als een geheel getal, maar ASIM vereist dat de waarde een tekenreeks is, om een brede compatibiliteit tussen gegevensbronnen te garanderen. Gebruik daarom bij het toewijzen van het bronveld extend en tostring in plaats van project-rename:

  | extend EventOriginalUid = tostring(ReportId),

Afgeleide velden en waarden

De waarde van het bronveld moet, nadat deze is geëxtraheerd, mogelijk worden toegewezen aan de set waarden die zijn opgegeven voor het doelschemaveld. De functies iff, caseen lookup kunnen handig zijn om beschikbare gegevens toe te wijzen aan doelwaarden.

De Microsoft DNS-parser wijst het veld bijvoorbeeld als volgt toe EventResult op basis van de gebeurtenis-id en antwoordcode met behulp van een iff -instructie:

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

Als u verschillende waarden wilt toewijzen, definieert u de toewijzing met behulp van de datatable operator en gebruikt lookup u om de toewijzing uit te voeren. Sommige bronnen rapporteren bijvoorbeeld numerieke DNS-antwoordcodes en het netwerkprotocol, terwijl het schema de meer algemene weergave van tekstlabels voor beide vereist. In het volgende voorbeeld ziet u hoe u de benodigde waarden kunt afleiden met behulp van datatable en 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

U ziet dat opzoeken nuttig en efficiënt is, ook wanneer de toewijzing slechts twee mogelijke waarden heeft.

Wanneer de toewijzingsvoorwaarden complexer zijn, combineert iffu , caseen lookup. In het onderstaande voorbeeld ziet u hoe u en casekunt combinerenlookup. In lookup het bovenstaande voorbeeld wordt een lege waarde in het veld DnsResponseCodeName geretourneerd als de opzoekwaarde niet wordt gevonden. In case het onderstaande voorbeeld wordt dit vergroot door het resultaat van de lookup bewerking te gebruiken, indien beschikbaar, en anders aanvullende voorwaarden op te geven.

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

Microsoft Sentinel biedt handige functies voor algemene opzoekwaarden. De bovenstaande zoekactie kan bijvoorbeeld DnsResponseCodeName worden geïmplementeerd met behulp van een van de volgende functies:


| extend DnsResponseCodeName = _ASIM_LookupDnsResponseCode(DnsResponseCode)

| invoke _ASIM_ResolveDnsResponseCode('DnsResponseCode')

De eerste optie accepteert als een parameter de waarde om op te zoeken en u kunt het uitvoerveld kiezen en daarom nuttig als een algemene opzoekfunctie. De tweede optie is meer gericht op parsers, neemt als invoer de naam van het bronveld en werkt het benodigde ASIM-veld bij, in dit geval DnsResponseCodeName.

Raadpleeg ASIM-functies voor een volledige lijst met ASIM-helpfuncties

Verrijkingsvelden

Naast de velden die beschikbaar zijn vanuit de bron, bevat een resulterende ASIM-gebeurtenis verrijkingsvelden die door de parser moeten worden gegenereerd. In veel gevallen kunnen de parsers een constante waarde toewijzen aan de velden, bijvoorbeeld:

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

Een ander type verrijkingsvelden dat uw parsers moeten instellen, zijn typevelden, waarmee het type van de waarde wordt aangegeven dat is opgeslagen in een gerelateerd veld. Het veld geeft bijvoorbeeld SrcUsernameType het type waarde aan dat in het SrcUsername veld is opgeslagen. Meer informatie over typevelden vindt u in de beschrijving van entiteiten.

In de meeste gevallen wordt aan typen ook een constante waarde toegewezen. In sommige gevallen moet het type echter worden bepaald op basis van de werkelijke waarde, bijvoorbeeld:

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

Microsoft Sentinel biedt handige functies voor het verwerken van verrijking. Gebruik bijvoorbeeld de volgende functie om de velden SrcHostname, SrcDomainTypeSrcDomainen SrcFQDN automatisch toe te wijzen op basis van de waarde in het veld Computer.

  | invoke _ASIM_ResolveSrcFQDN('Computer')

Met deze functie worden de velden als volgt ingesteld:

Computerveld Uitvoervelden
server1 SrcHostname: server1
SrcDomain, SrcDomainType, SrcFQDN allemaal leeg
server1.microsoft.com SrcHostname: server1
SrcDomain: microsoft.com
SrcDomainType: FQDN
SrcFQDN:server1.microsoft.com

De functies _ASIM_ResolveDstFQDN en _ASIM_ResolveDvcFQDN voeren een vergelijkbare taak uit door de gerelateerde Dst velden en Dvc in te vullen. Raadpleeg ASIM-functies voor een volledige lijst met ASIM-helpfuncties

Velden in de resultatenset selecteren

De parser kan desgewenst velden in de resultatenset selecteren. Als u overbodige velden verwijdert, kunt u de prestaties verbeteren en duidelijkheid toevoegen door verwarring tussen genormaliseerde velden en resterende bronvelden te voorkomen.

De volgende KQL-operators worden gebruikt om velden in uw resultatenset te selecteren:

Operator Beschrijving Wanneer gebruiken in een parser
project-away Hiermee verwijdert u velden. Gebruik project-away voor specifieke velden die u uit de resultatenset wilt verwijderen. We raden u aan de oorspronkelijke velden die niet zijn genormaliseerd niet uit de resultatenset te verwijderen, tenzij ze verwarring veroorzaken of erg groot zijn en gevolgen kunnen hebben voor de prestaties.
Project Selecteert velden die eerder bestonden of die zijn gemaakt als onderdeel van de instructie en verwijdert alle andere velden. Niet aanbevolen voor gebruik in een parser, omdat de parser geen andere velden mag verwijderen die niet zijn genormaliseerd.

Als u specifieke velden wilt verwijderen, zoals tijdelijke waarden die tijdens het parseren worden gebruikt, gebruikt project-away u om deze uit de resultaten te verwijderen.

Wanneer u bijvoorbeeld een aangepaste logboektabel parseert, gebruikt u het volgende om de resterende oorspronkelijke velden te verwijderen die nog steeds een typedescriptor hebben:

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

Parseervarianten verwerken

Belangrijk

De verschillende varianten vertegenwoordigen verschillende gebeurtenistypen, meestal toegewezen aan verschillende schema's, ontwikkelen afzonderlijke parsers

In veel gevallen bevatten gebeurtenissen in een gebeurtenisstroom varianten waarvoor een andere parseringslogica is vereist. Als u verschillende varianten in één parser wilt parseren, gebruikt u voorwaardelijke instructies zoals iff en caseof gebruikt u een samenvoegstructuur.

Als u meerdere varianten wilt verwerken union , maakt u een afzonderlijke functie voor elke variant en gebruikt u de samenvoegingsinstructie om de resultaten te combineren:

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…

Om dubbele gebeurtenissen en overmatige verwerking te voorkomen, moet u ervoor zorgen dat elke functie wordt gestart door te filteren, met behulp van systeemeigen velden, alleen de gebeurtenissen die moeten worden geparseerd. Gebruik indien nodig ook project-away bij elke vertakking, vóór de samenvoeging.

Parsers implementeren

Implementeer parsers handmatig door ze te kopiëren naar de azure Monitor-logboekpagina en de query op te slaan als een functie. Deze methode is handig voor het testen. Zie Een functie maken voor meer informatie.

Als u een groot aantal parsers wilt implementeren, raden we u aan om de ARM-sjablonen voor parser als volgt te gebruiken:

  1. Maak een YAML-bestand op basis van de relevante sjabloon voor elk schema en neem uw query hierin op. Begin met de YAML-sjabloon die relevant is voor uw schema en parsertype, filters of parameterloos.

  2. Gebruik het ASIM Yaml naar ARM-sjabloonconversieprogramma om uw YAML-bestand te converteren naar een ARM-sjabloon.

  3. Als u een update implementeert, verwijdert u oudere versies van de functies met behulp van de portal of het PowerShell-hulpprogramma voor functie verwijderen.

  4. Implementeer uw sjabloon met behulp van de Azure Portal of PowerShell.

U kunt ook meerdere sjablonen combineren tot één implementatieproces met behulp van gekoppelde sjablonen

Tip

ARM-sjablonen kunnen verschillende resources combineren, zodat parsers kunnen worden geïmplementeerd naast connectors, analyseregels of watchlists, om enkele handige opties te noemen. Uw parser kan bijvoorbeeld verwijzen naar een volglijst die ernaast is geïmplementeerd.

Parsers testen

In deze sectie wordt beschreven welke testhulpprogramma's ASIM biedt waarmee u uw parsers kunt testen. Parsers zijn echter code, soms complex, en naast geautomatiseerd testen worden standaardprocedures voor kwaliteitsbewaking aanbevolen, zoals codebeoordelingen.

ASIM-testhulpprogramma's installeren

Als u ASIM wilt testen, implementeert u het ASIM-testhulpprogramma in een Microsoft Sentinel-werkruimte waar:

  • Uw parser is geïmplementeerd.
  • De brontabel die door de parser wordt gebruikt, is beschikbaar.
  • De brontabel die door de parser wordt gebruikt, wordt gevuld met een gevarieerde verzameling relevante gebeurtenissen.

Het uitvoerschema valideren

Als u er zeker van wilt zijn dat uw parser een geldig schema produceert, gebruikt u de ASIM-schematester door de volgende query uit te voeren op de pagina Microsoft Sentinel-logboeken :

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

Behandel de resultaten als volgt:

Fout Actie
Verplicht veld ontbreekt [<Veld>] Voeg het veld toe aan uw parser. In veel gevallen is dit een afgeleide waarde of een constante waarde, en niet een veld dat al beschikbaar is vanuit de bron.
Ontbrekend veld [<Veld>] is verplicht wanneer verplichte kolom [<veld>] bestaat Voeg het veld toe aan uw parser. In veel gevallen geeft dit veld de typen van de bestaande kolom aan waarnaar het verwijst.
Ontbrekend veld [<Veld>] is verplicht wanneer kolom [<Veld>] bestaat Voeg het veld toe aan uw parser. In veel gevallen geeft dit veld de typen van de bestaande kolom aan waarnaar het verwijst.
Ontbrekende verplichte alias [<veld>] aliasing bestaande kolom [<veld>] De alias toevoegen aan uw parser
Aanbevolen alias [<veld>] ontbreekt als alias voor bestaande kolom [<veld>] De alias toevoegen aan uw parser
Optionele alias [<veld>] ontbreekt als alias voor bestaande kolom [<veld>] De alias toevoegen aan uw parser
Ontbrekende verplichte alias [<veld>] alias met ontbrekende kolom [<veld>] Deze fout gaat gepaard met een vergelijkbare fout voor het veld met alias. Corrigeer de fout met het aliasveld en voeg deze alias toe aan uw parser.
Typ niet-overeenkomend voor veld [<Veld>]. Het is momenteel [<Type>] en moet [<Type>] zijn Zorg ervoor dat het type genormaliseerd veld juist is, meestal met behulp van een conversiefunctie zoals tostring.
Info Actie
Aanbevolen veld ontbreekt [<Veld>] Overweeg dit veld toe te voegen aan uw parser.
Info Actie
Aanbevolen alias [<veld>] ontbreekt als alias voor niet-bestaande kolom [<Veld>] Als u het veld met de alias toevoegt aan de parser, moet u deze alias ook toevoegen.
Ontbrekende optionele alias [<veld>] aliasing niet-bestaande kolom [<Veld>] Als u het veld met de alias toevoegt aan de parser, moet u deze alias ook toevoegen.
Ontbrekend optioneel veld [<Veld>] Hoewel optionele velden vaak ontbreken, is het de moeite waard om de lijst te bekijken om te bepalen of een van de optionele velden uit de bron kan worden toegewezen.
Extra ongenormaliseerd veld [<Veld>] Hoewel niet-genormaliseerde velden geldig zijn, is het de moeite waard om de lijst te bekijken om te bepalen of een van de niet-genormaliseerde waarden kan worden toegewezen aan een optioneel veld.

Notitie

Fouten verhinderen dat inhoud die de parser gebruikt, correct werkt. Waarschuwingen verhinderen niet dat inhoud werkt, maar kunnen de kwaliteit van de resultaten verminderen.

De uitvoerwaarden valideren

Als u er zeker van wilt zijn dat uw parser geldige waarden produceert, gebruikt u de ASIM-gegevenstester door de volgende query uit te voeren op de pagina Microsoft Sentinel-logboeken :

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

Het opgeven van een schema is optioneel. Als er geen schema is opgegeven, wordt het EventSchema veld gebruikt om het schema te identificeren waaraan de gebeurtenis moet voldoen. Een gebeurtenis bevat EventSchema geen veld, alleen algemene velden worden geverifieerd. Als een schema is opgegeven als een parameter, wordt dit schema gebruikt om alle records te testen. Dit is handig voor oudere parsers die het EventSchema veld niet instellen.

Notitie

Zelfs wanneer er geen schema is opgegeven, zijn lege haakjes achter de functienaam nodig.

Deze test is resource-intensief en werkt mogelijk niet voor de hele gegevensset. Stel X in op het grootste getal waarvoor geen time-out optreedt voor de query of stel het tijdsbereik voor de query in met behulp van de tijdsbereikkiezer.

Behandel de resultaten als volgt:

Bericht Actie
(0) Fout: type komt niet overeen voor kolom [<veld>]. Het is momenteel [<Type>] en moet [<Type>] zijn Zorg ervoor dat het type genormaliseerd veld juist is, meestal met behulp van een conversiefunctie zoals tostring.
(0) Fout: Ongeldige waarde(s) (maximaal 10 vermeld) voor veld [<Veld>] van het type [<Logisch type>] Zorg ervoor dat de parser het juiste bronveld toe wijst aan het uitvoerveld. Als deze correct is toegewezen, werkt u de parser bij om de bronwaarde te transformeren naar het juiste type, de juiste waarde of de juiste indeling. Raadpleeg de lijst met logische typen voor meer informatie over de juiste waarden en opmaak voor elk logisch type.

Houd er rekening mee dat het testhulpprogramma alleen een steekproef van 10 ongeldige waarden bevat.
(1) Waarschuwing: lege waarde in verplicht veld [<veld>] Verplichte velden moeten worden ingevuld, niet alleen gedefinieerd. Controleer of het veld kan worden ingevuld vanuit andere bronnen voor records waarvoor de huidige bron leeg is.
(2) Info: Lege waarde in aanbevolen veld [<Veld>] Aanbevolen velden moeten meestal worden ingevuld. Controleer of het veld kan worden ingevuld vanuit andere bronnen voor records waarvoor de huidige bron leeg is.
(2) Info: Lege waarde in optioneel veld [<Veld>] Controleer of het veld met alias verplicht of aanbevolen is en zo ja, of het kan worden ingevuld vanuit andere bronnen.

Veel van de berichten rapporteren ook het aantal records dat het bericht heeft gegenereerd en hun percentage van de totale steekproef. Dit percentage is een goede indicatie van het belang van het probleem. Bijvoorbeeld voor een aanbevolen veld:

  • 90% lege waarden kunnen duiden op een algemeen parseringsprobleem.
  • 25% lege waarden kunnen duiden op een gebeurtenisvariant die niet correct is geparseerd.
  • Een handvol lege waarden kan een verwaarloosbaar probleem zijn.

Notitie

Fouten verhinderen dat inhoud die de parser gebruikt, correct werkt. Waarschuwingen verhinderen niet dat inhoud werkt, maar kunnen de kwaliteit van de resultaten verminderen.

Parsers bijdragen

U kunt de parser bijdragen aan de primaire ASIM-distributie. Indien geaccepteerd, zijn de parsers beschikbaar voor elke klant als ingebouwde ASIM-parsers.

Uw parsers bijdragen:

Geaccepteerde waarschuwingen documenteren

Als waarschuwingen die worden vermeld door de ASIM-testhulpprogramma's als geldig worden beschouwd voor een parser, documenteert u de geaccepteerde waarschuwingen in het YAML-bestand parser met behulp van de sectie Uitzonderingen, zoals wordt weergegeven in het onderstaande voorbeeld.

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

De waarschuwing die in het YAML-bestand is opgegeven, moet een korte vorm zijn van het waarschuwingsbericht dat uniek wordt geïdentificeerd. De waarde wordt gebruikt om waarschuwingsberichten te vinden bij het uitvoeren van geautomatiseerde tests en deze te negeren.

Richtlijnen voor het indienen van voorbeelden

Voorbeeldgegevens zijn nodig bij het oplossen van parserproblemen en om ervoor te zorgen dat toekomstige updates van de parser voldoen aan oudere voorbeelden. De voorbeelden die u indient, moeten elke gebeurtenisvariant bevatten die door de parser wordt ondersteund. Zorg ervoor dat de voorbeeldgebeurtenissen alle mogelijke gebeurtenistypen, gebeurtenisindelingen en variaties bevatten, zoals gebeurtenissen die geslaagde en mislukte activiteiten vertegenwoordigen. Zorg er ook voor dat variaties in waardenotaties worden weergegeven. Als een hostnaam bijvoorbeeld kan worden weergegeven als een FQDN of een eenvoudige hostnaam, moeten de voorbeeldgebeurtenissen beide indelingen bevatten.

Gebruik de volgende stappen om de gebeurtenisvoorbeelden in te dienen:

  • Voer in het Logs scherm een query uit die alleen de gebeurtenissen uit de brontabel haalt die door de parser zijn geselecteerd. Gebruik bijvoorbeeld voor de Infoblox DNS-parser de volgende query:
    Syslog
    | where ProcessName == "named"

  • Exporteer de resultaten met de optie Exporteren naar CSV naar een bestand met de naam <EventVendor>_<EventProduct>_<EventSchema>_IngestedLogs.csv, Waar EventProduct, EventProducten EventSchema zijn de waarden die door de parser aan deze velden zijn toegewezen.

  • Voer in het Logs scherm een query uit waarmee het schema of de parserinvoertabel wordt uitgevoerd. Voor dezelfde Infoblox DNS-parser is de query bijvoorbeeld:

    Syslog
    | getschema

  • Exporteer de resultaten met de optie Exporteren naar CSV naar een bestand met de naam <TableName>_schema.csv, waarbij TableName de naam is van de brontabel die door de parser wordt gebruikt.

  • Neem beide bestanden op in uw pull-aanvraag in de map /Sample Data/ASIM. Als het bestand al bestaat, voegt u uw GitHub-ingang toe aan de naam, bijvoorbeeld: <EventVendor>_<EventProduct>_<EventSchema>_SchemaTest_<GitHubHanlde>.csv

Richtlijnen voor het verzenden van testresultaten

Testresultaten zijn belangrijk om de juistheid van de parser te controleren en eventuele gerapporteerde uitzonderingen te begrijpen.

Voer de volgende stappen uit om uw testresultaten in te dienen:

  • Voer de parsertests uit die worden beschreven in de sectie testen .

  • en exporteer de testresultaten met behulp van de optie Exporteren naar CSV naar bestanden met respectievelijk de naam <EventVendor>_<EventProduct>_<EventSchema>_SchemaTest.csv en <EventVendor>_<EventProduct>_<EventSchema>_DataTest.csv .

  • Neem beide bestanden op in uw pull-aanvraag in de map /Parsers/ASim<schema>/Tests.

Volgende stappen

In dit artikel wordt het ontwikkelen van ASIM-parsers besproken.

Meer informatie over ASIM-parsers:

Meer informatie over de ASIM in het algemeen: