ASIM-parsers (Advanced Security Information Model) ontwikkelen

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. Verenigende parsers gebruiken op hun beurt 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 bevat die passen bij een ASIM-schema, maar een bronspecifieke parser voor uw apparaat en het relevante schema niet 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. Voorbeeld:

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

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

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 het schema of de schema’s waarmee de gebeurtenissen die door de bron worden verzonden overeenkomen. Zie Schema-overzicht voor meer informatie.

  3. Koppel de brongebeurtenisvelden 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 jouw parser.

  6. Implementeer de parsers in uw Microsoft Sentinel werkplekken.

  7. Werk de relevante ASIM-unificerende 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 ontwikkelings-, test- en implementatiestappen van het proces.

Voorbeeldlogboeken verzamelen

Als u effectieve ASIM-parsers wilt maken, hebt u een representatieve set logboeken nodig. In het meeste geval moet u het bronsysteem instellen en deze 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 te zorgen voor een brede dekking van de logboekindeling.

Een representatieve set logboeken moet het volgende omvatten:

  • Gebeurtenissen met verschillende gebeurtenisresultaten.
  • Gebeurtenissen met verschillende reactieacties.
  • 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.

Planningstoewijzing

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

  • Breng alle verplichte velden en bij voorkeur ook de aanbevolen velden in kaart.
  • Probeer alle beschikbare informatie uit de bron toe te wijzen aan genormaliseerde velden. Als dit niet beschikbaar is als onderdeel van het geselecteerde schema, overweeg dan velden te koppelen aan velden die beschikbaar zijn in andere schema's.
  • Ken waarden van bronnenvelden 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 Logs. De parserquery bestaat uit drie onderdelen:

Filteren>Parseren>Velden voorbereiden

Filteren

De relevante records filteren

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

  • 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 procescreatie en wordt daarom genormaliseerd naar het ProcessEvent-schema. De 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

Important

Een parser zou niet op basis van tijd moeten filteren. De query die gebruikmaakt van de parser, past een tijdsbereik toe.

Filteren op brontype met behulp van een volglijst

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

Infoblox DNS-gebeurtenissen worden bijvoorbeeld verzonden als Syslog-berichten en zijn moeilijk te onderscheiden van Syslog-berichten die worden 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 bewaard in de Sources_by_SourceType volglijst.

Als u de ASimSourceType-watchlist 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 te gebruiken in uw parser:

  • Vervang Computer door 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 uw geselecteerde waarde, evenals de lijst met bronnen die gebeurtenissen van dit type verzenden.

Filteren op basis van parserparameters

Zorg er bij het ontwikkelen van filterparsers voor dat de parser de filterparameters voor het relevante schema accepteert, zoals beschreven in het referentieartikel 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 voordat u gegevens parseert met behulp van fysieke velden. Als de gefilterde resultaten niet nauwkeurig genoeg zijn, herhaalt u de test na het parseren om de resultaten af te stemmen. Zie filteroptimalisatie 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)

Zie meer informatie over de volgende items in de Kusto-documentatie:

Optimalisatie van filteren

Houd rekening met de volgende filteraanbevelingen voor het waarborgen van de prestaties van de parser.

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

Aanbevelingen voor filteren op prestaties zijn niet altijd eenvoudig te volgen. Het gebruik has is bijvoorbeeld minder nauwkeurig dan contains. In andere gevallen is het vergelijken 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 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 nadat het Log_Type veld is geparserd, 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"

Opmerking

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

Parseren

Zodra de query de relevante records heeft geselecteerd, moet deze mogelijk worden geparseerd. Parseren is doorgaans nodig als meerdere gebeurtenisvelden in één tekstveld worden overgebracht.

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

Operator/function() Description
split() functie Een tekenreeks met door scheidingstekens gescheiden waarden parseren.
parse_csv() functie Parseert een reeks waarden die is opgemaakt als een CSV-regel (door komma's gescheiden waarden).
parse-kv-operator Haalt gestructureerde informatie uit een tekenreeksexpressie en vertegenwoordigt de informatie in een sleutel-/waardevorm.
parser-operator 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() functie Parseert enkele waarden uit een willekeurige tekenreeks met behulp van een reguliere expressie. extract_all heeft vergelijkbare prestaties als parse als die laatste een reguliere expressie gebruikt.
extract() functie Eén waarde uit een willekeurige tekenreeks extraheren 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() functie Parseert de waarden in een tekenreeks die is opgemaakt als JSON. Als er slechts enkele waarden nodig zijn uit de JSON, biedt het gebruik van parse, extract of extract_all betere prestaties.
parse_xml() functie Parseer de waarden van een tekenreeks in XML-indeling. Als er slechts enkele waarden nodig zijn uit de XML, dan biedt het gebruik van parse, extract, of extract_all betere prestaties.

Normaliseren

Veldnamen in kaart brengen

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 . Door project-rename te gebruiken, zorgt u ervoor dat het veld nog steeds als een fysiek veld wordt beheerd en dat de verwerking van het veld efficiënter is. Voorbeeld:

 | 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 mogelijk een met streepjes gescheiden MAC-adres verzendt. De primaire operator voor het transformeren van waarden is extend, naast een brede set KQL-tekenreeksen, numerieke en datumfuncties.

Bovendien is het essentieel dat parser-uitvoervelden overeenkomen met het type dat in het schema is gedefinieerd, zodat parsers kunnen werken. U moet bijvoorbeeld een tekenreeks die datum en tijd vertegenwoordigt converteren naar een datum/tijd-veld. Functies zoals todatetime en tohex zijn nuttig 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, zodra deze is geëxtraheerd, mogelijk worden toegewezen aan de set waarden die zijn opgegeven voor het doelschemaveld. De functies iff, case, en lookup kunnen handig zijn om beschikbare gegevens toe te wijzen aan doelwaarden.

De Microsoft DNS-parser wijst bijvoorbeeld het EventResult veld toe op basis van de Event-id en responscode 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 deze 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

Merk op dat opzoeken nuttig en efficiënt is, ook wanneer de mapping maar twee mogelijke waarden heeft.

Wanneer de toewijzingsvoorwaarden complexer zijn, combineer iff, case en lookup. In het onderstaande voorbeeld ziet u hoe u lookup en case kunt combineren. In lookup het bovenstaande voorbeeld wordt een lege waarde in het veld DnsResponseCodeName geretourneerd als de opzoekwaarde niet wordt gevonden. Het onderstaande voorbeeld case breidt dit uit door, indien beschikbaar, het resultaat van de bewerking lookup te gebruiken 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 zoekopdracht DnsResponseCodeName kan bijvoorbeeld 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 parameter de waarde die moet worden opgezoekd en laat u het uitvoerveld kiezen en daarom nuttig zijn 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 op basis van de bron, bevat een resulterende ASIM-gebeurtenis verrijkingsvelden die de parser moet genereren. 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, die het type van de waarde aanduiden 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 nuttige functies voor het omgaan met verrijking. Gebruik bijvoorbeeld de volgende functie om de velden SrcHostname, SrcDomain, SrcDomainType en 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:

Computergebied 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 waarin de gerelateerde Dst en Dvc velden worden ingevuld. Raadpleeg ASIM-functies voor een volledige lijst met ASIM-helpfuncties

Velden selecteren in de resultatenset

De parser kan desgewenst velden selecteren in de resultatenset. Het verwijderen van overbodige velden kan de prestaties verbeteren en duidelijkheid toevoegen door verwarring te voorkomen tussen genormaliseerde velden en resterende bronvelden.

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

Operator Description Wanneer moet het worden gebruikt in een parser?
project-away Verwijdert velden. Gebruik project-away voor specifieke velden die u uit de resultatenset wilt verwijderen. We raden aan de originele velden die niet zijn genormaliseerd niet uit de resultatenset te verwijderen, tenzij ze verwarring veroorzaken of erg groot zijn en prestatie-implicaties kunnen hebben.
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, zoals tijdelijke waarden die tijdens het parseren worden gebruikt, uit de resultaten wilt verwijderen, gebruik dan project-away om ze te verwijderen.

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

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

Parseringsvarianten afhandelen

Important

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

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

Als u union wilt gebruiken om meerdere varianten te verwerken, maakt u een afzonderlijke functie voor elke variant en gebruikt u de union-verklaring 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…

Als u dubbele gebeurtenissen en overmatige verwerking wilt voorkomen, moet u ervoor zorgen dat elke functie begint met 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 naar de Azure Monitor Logboeken-pagina te kopiëren en de query als functie op te slaan. 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 als volgt arm-sjablonen voor parser te gebruiken:

  1. Maak een YAML-bestand op basis van de relevante sjabloon voor elk schema en voeg daarin uw query toe. Begin met de YAML-sjabloon die relevant is voor uw schema en parsertype, filteren 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, analytische regels of volglijsten, om een paar handige opties te noemen. Uw parser kan bijvoorbeeld verwijzen naar een volglijst die ernaast is geïmplementeerd.

Parsers testen

In deze sectie wordt beschreven dat ASIM testhulpprogramma's biedt waarmee u uw parsers kunt testen. Dat gezegd hebbende, parsers zijn code, soms complex en standaardprocedures voor kwaliteitscontrole, zoals codebeoordelingen, worden aanbevolen naast geautomatiseerde tests.

ASIM-testhulpmiddelen 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

Gebruik de ASIM-schematester om ervoor te zorgen dat uw parser een geldig schema produceert door de volgende query uit te voeren op de pagina Microsoft Sentinel Logs:

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

Behandel de resultaten als volgt:

Fout Action
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 wordt verwezen.
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 wordt verwezen.
Ontbrekende verplichte alias [<veld>] alias van bestaande kolom [<veld>] De alias toevoegen aan uw parser
Aanbevolen alias [<veld>] ontbreekt bij het aliasen van bestaande kolom [<veld>] De alias toevoegen aan uw parser
Ontbrekende optionele alias [<Veld>] voor bestaande kolom [<Veld>] De alias toevoegen aan uw parser
Ontbrekende verplichte alias [<veld>] alias ontbrekende kolom [<veld>] Deze fout gaat gepaard met een vergelijkbare fout voor het veld met alias. Corrigeer de aliasveldfout en voeg deze alias toe aan uw parser.
Type-onenigheid 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.
Informatie Action
Aanbevolen veld ontbreekt [<Veld>] Overweeg dit veld toe te voegen aan uw parser.
Informatie Action
Aanbevolen alias [<Field>] ontbreekt bij het aliassen van niet-bestaande kolom [<Field>] Als u het veld met alias toevoegt aan de parser, moet u deze alias ook toevoegen.
Ontbrekende optionele alias [<Veld>] als alias voor niet-bestaande kolom [<Veld>] Als u het veld met alias toevoegt aan de parser, moet u deze alias ook toevoegen.
Optioneel veld ontbreekt [<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 kan worden toegewezen vanuit de bron.
Extra niet-genormaliseerd 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.

Opmerking

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

Gebruik de ASIM-gegevenstester om ervoor te zorgen dat uw parser geldige waarden produceert door de volgende query uit te voeren op de pagina Microsoft Sentinel Logs:

<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. Als een gebeurtenis geen veld bevat EventSchema , worden alleen algemene velden geverifieerd. Als een schema is opgegeven als parameter, wordt dit schema gebruikt om alle records te testen. Dit is handig voor oudere parsers die het EventSchema veld niet instellen.

Opmerking

Zelfs wanneer een schema niet is opgegeven, zijn er lege haakjes nodig na de functienaam.

Deze test is resource-intensief en werkt mogelijk niet voor uw hele gegevensset. Stel X in op het grootste getal waarbij de query niet vastloopt, of stel het tijdsbereik voor de query in met de tijdsbereikselector.

Behandel de resultaten als volgt:

Bericht Action
(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 het juiste bronveld aan het uitvoerveld wordt toegewezen door de parser. Als de toewijzing correct is, werkt u de parser bij om de bronwaarde te transformeren naar het juiste type, de juiste waarde of het juiste formaat. 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 testprogramma alleen een voorbeeld 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 waarvan 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 waarvan 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 het percentage van de totale steekproef. Dit percentage is een goede indicator 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.

Opmerking

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 aanleveren

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

Om uw parsers bij te dragen:

  • Ontwikkel zowel een filterparser als een parameterloze parser.
  • Maak een YAML-bestand voor de parser, zoals hierboven beschreven in Parsers implementeren.
  • Zorg ervoor dat uw parsers alle tests zonder fouten doorstaan. Als er waarschuwingen overblijven, documenteert u deze in het YAML-bestand van de parser.
  • Maak een pull-aanvraag voor de Microsoft Sentinel GitHub-opslagplaats, waaronder:

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 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 van het waarschuwingsbericht zijn waarmee dit bericht op unieke wijze kan worden geïdentificeerd. De waarde wordt gebruikt om waarschuwingsberichten te vergelijken 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 voor 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 een geslaagde en mislukte activiteit vertegenwoordigen. Zorg er ook voor dat verschillende waarde-indelingen worden weergegeven. Als een hostnaam bijvoorbeeld kan worden weergegeven als een FQDN of een eenvoudige hostnaam, moeten de voorbeeldgebeurtenissen beide indelingen bevatten.

Als u de gebeurtenisvoorbeelden wilt verzenden, gebruikt u de volgende stappen:

  • Voer in het Logs scherm een query uit die alleen de gebeurtenissen uit de brontabel haalt die door de parser zijn geselecteerd. Gebruik bijvoorbeeld de volgende query voor de Infoblox DNS-parser:
    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 invoertabel van de parser 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 de parser gebruikt.

  • Voeg beide bestanden toe aan je PR 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_<GitHubHandle>.csv

Richtlijnen voor het indienen van testresultaten

Testresultaten zijn belangrijk om de juistheid van de parser te controleren en inzicht te krijgen in eventuele gerapporteerde uitzonderingen.

Voer de volgende stappen uit om uw testresultaten te verzenden:

  • Voer de parsertests uit zoals beschreven in de sectie testings.

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

  • Voeg beide bestanden toe aan je PR in de map /Parsers/ASim<schema>/Tests.

Verwante onderwerpen

Meer informatie over ASIM-parsers:

Meer informatie over de ASIM in het algemeen:

  • Last updated on