Condividi tramite

Sviluppare parser ASIM (Advanced Security Information Model) - Anteprima pubblica

  • Articolo

Per eseguire query, gli utenti di Advanced Security Information Model (ASIM) usano parser di unificazione al posto dei nomi di tabella, in modo da visualizzare i dati in un formato normalizzato e includere tutti i dati pertinenti per lo schema nella query. I parser di unificazione, a loro volta, usano parser specifici dell'origine per gestire i dettagli specifici di ogni origine.

Microsoft Sentinel offre parser predefiniti specifici dell'origine per molte origini dati. È possibile modificare, o sviluppare, questi parser specifici dell'origine nelle situazioni seguenti:

  • Quando il dispositivo fornisce eventi che soddisfano uno schema ASIM, ma in Microsoft Sentinel non è disponibile un parser specifico dell'origine per il dispositivo e lo schema pertinente.

  • Quando i parser ASIM specifici dell'origine sono disponibili per il dispositivo, ma il dispositivo invia eventi in un metodo o un formato diverso da quello previsto dai parser ASIM. Ad esempio:

    • Il dispositivo di origine può essere configurato per inviare eventi in modo non standard.

    • Il dispositivo può avere una versione diversa da quella supportata dal parser ASIM.

    • Gli eventi possono essere raccolti, modificati e inoltrati da un sistema intermedio.

Per comprendere in che modo i parser si inseriscono nell'architettura ASIM, vedere il diagramma dell'architettura ASIM.

Importante

ASIM è attualmente in anteprima. Le condizioni aggiuntive per l'anteprima di Azure includono termini legali aggiuntivi che si applicano a funzionalità di Azure in versione beta, anteprima o diversamente non ancora disponibili a livello generale.

Processo di sviluppo di parser ASIM personalizzati

Il flusso di lavoro seguente descrive i passaggi generali per lo sviluppo di un parser ASIM personalizzato specifico dell'origine:

  1. Raccogliere log di esempio.

  2. Identificare lo schema o gli schemi rappresentati dagli eventi inviati dall'origine. Per altre informazioni, vedere Panoramica dello schema.

  3. Eseguire il mapping dei campi degli eventi di origine allo schema o agli schemi identificati.

  4. Sviluppare uno o più parser ASIM per l'origine. Sarà necessario sviluppare un parser di filtro e un parser senza parametri per ogni schema rilevante per l'origine.

  5. Testare il parser.

  6. Distribuire i parser nelle aree di lavoro di Microsoft Sentinel.

  7. Aggiornare il parser di unificazione ASIM rilevante per fare riferimento al nuovo parser personalizzato. Per altre informazioni, vedere Gestione dei parser ASIM.

  8. È anche possibile contribuire con i propri parser alla distribuzione primaria di ASIM. I parser che hanno contribuito possono anche essere resi disponibili in tutti le aree di lavoro come parser predefiniti.

Questo articolo illustra le fasi di sviluppo, test e distribuzione del processo.

Suggerimento

Guardare anche il webinar Approfondimento sulla normalizzazione dei parser e sui contenuti normalizzati di Microsoft Sentinel o consultare la relativa presentazione. Per altre informazioni, vedere Passaggi successivi.

Raccogliere log di esempio

Per creare parser ASIM efficaci, è necessario un set rappresentativo di log, che nella maggior parte dei casi richiede la configurazione del sistema di origine e la connessione a Microsoft Sentinel. Se non si dispone del dispositivo di origine, i servizi cloud con pagamento in base al consumo consentono di distribuire molti dispositivi per lo sviluppo e il test.

Inoltre, trovare la documentazione del fornitore e gli esempi dei log può contribuire ad accelerare lo sviluppo e ridurre gli errori garantendo un'ampia copertura del formato dei log.

Un set rappresentativo di log deve includere:

  • Eventi con risultati di eventi diversi.
  • Eventi con azioni di risposta diverse.
  • Formati diversi per nome utente, nome host e ID e altri campi che richiedono la normalizzazione dei valori.

Suggerimento

Avviare un nuovo parser personalizzato usando un parser esistente per lo stesso schema. L'uso di un parser esistente è particolarmente importante per filtrare i parser in modo da avere la certezza che accettino tutti i parametri richiesti dallo schema.

Pianificazione del mapping

Prima di sviluppare un parser, eseguire il mapping delle informazioni disponibili nell'evento o negli eventi di origine allo schema identificato:

  • Eseguire il mapping di tutti i campi obbligatori e preferibilmente anche di quelli consigliati.
  • Provare a eseguire il mapping delle informazioni disponibili nell'origine ai campi normalizzati. Se non sono disponibili all'interno dello schema selezionato, considerare la possibilità di eseguire il mapping a campi disponibili in altri schemi.
  • Eseguire il mapping dei valori dei campi nell'origine ai valori normalizzati consentiti da ASIM. Il valore originale viene archiviato in un campo distinto, ad esempio EventOriginalResultDetails.

Sviluppo di parser

Sviluppare sia un parser di filtro che un parser senza parametri per ogni schema rilevante.

Un parser personalizzato è una query KQL sviluppata nella pagina Log di Microsoft Sentinel. La query del parser è composta da tre parti:

Filtra>Analizza>Prepara campi

Filtri

Filtro dei record rilevanti

In molti casi, una tabella di Microsoft Sentinel include più tipi di eventi. Ad esempio:

  • La tabella Syslog contiene dati provenienti da più origini.
  • Le tabelle personalizzate possono includere informazioni provenienti da una singola origine che fornisce più di un tipo di evento e può adattarsi a vari schemi.

Pertanto, un parser deve prima filtrare solo i record rilevanti per lo schema di destinazione.

L’operazione di filtro in KQL viene eseguita mediante l'operatore where. Ad esempio, l'evento Sysmon 1 segnala la creazione di un processo e viene quindi normalizzato nello schema ProcessEvent. L'evento Sysmon 1 fa parte della tabella Event, quindi occorre usare il filtro seguente:

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

Importante

Un parser non deve filtrare in base al tempo. La query che usa il parser applicherà un intervallo di tempo.

Filtro in base al tipo di origine tramite una watchlist

In alcuni casi, l'evento in sé non contiene informazioni che consentono di filtrare per tipi di origine specifici.

Ad esempio, gli eventi DNS Infoblox vengono inviati come messaggi Syslog e sono difficili da distinguere dai messaggi Syslog inviati da altre origini. In questi casi, il parser si basa su un elenco di origini che definisce gli eventi rilevanti. Questo elenco viene mantenuto nella watchlist Sources_by_SourceType.

Per usare la watchlist ASimSourceType nei parser, usare la funzione _ASIM_GetSourceBySourceType nella sezione relativa ai filtri dei parser. Ad esempio, il parser DNS Infoblox include quanto segue nella sezione filtro:

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

Per usare questo esempio nel parser:

  • Sostituire Computer con il nome del campo che include le informazioni relative all'origine. È possibile mantenere il nome Computer per qualsiasi parser basato su Syslog.

  • Sostituire il token InfobloxNIOS con un valore a scelta per il parser. Informare gli utenti del parser che devono aggiornare la watchlist ASimSourceType con il valore selezionato, oltre all'elenco di origini che inviano eventi di questo tipo.

Filtro basato sui parametri del parser

Quando si sviluppano parser di filtro, assicurarsi che il parser accetti i parametri di filtro per lo schema pertinente, come documentato nell'articolo di riferimento per tale schema. L'uso di un parser esistente come punto di partenza garantisce che il parser includa la firma della funzione corretta. Nella maggior parte dei casi, anche il codice di filtro effettivo è simile per i parser di filtro dello stesso schema.

Quando si filtra, assicurarsi di:

  • Filtrare prima di analizzare usando i campi fisici. Se i risultati filtrati non sono sufficientemente accurati, ripetere il test dopo avere applicato un parser per ottimizzare i risultati. Per altre informazioni, vedere Ottimizzazione del filtro.
  • Non filtrare se il parametro non è definito e ha ancora il valore predefinito.

Gli esempi seguenti illustrano come implementare il filtro per un parametro stringa, in cui il valore predefinito è in genere '*' e per un parametro elenco, in cui il valore predefinito è in genere un elenco vuoto.

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

Ottimizzazione dei filtri

Per garantire le prestazioni del parser, tenere presenti le raccomandazioni di filtro seguenti:

  • Filtrare sempre in base ai campi predefiniti anziché a quelli analizzati. Anche se a volte è più semplice filtrare usando campi con parser applicati, questa procedura influisce notevolmente sulle prestazioni.
  • Usare gli operatori che offrono prestazioni ottimizzate. In particolare, ==, has e startswith. Anche l'uso di operatori come contains o matches regex compromette notevolmente le prestazioni.

Le raccomandazioni di filtro per le prestazioni potrebbero non essere sempre facili da seguire. Ad esempio, l'uso di has è meno preciso di contains. In altri casi, la corrispondenza con il campo predefinito, ad esempio SyslogMessage, è meno precisa rispetto al confronto con un campo estratto, ad esempio DvcAction. In questi casi, è consigliabile adottare un filtro preliminare usando un operatore di ottimizzazione delle prestazioni su un campo predefinito e ripetere il filtro usando condizioni più accurate dopo l'analisi.

Per un esempio, vedere il frammento di parser Infoblox DNS riportato di seguito. Il parser usa innanzitutto il filtro has per verificare che il campo SyslogMessage “abbia” la parola client. Tuttavia, il termine potrebbe essere usato in una posizione diversa nel messaggio, quindi dopo l'analisi del campo Log_Type, il parser verifica nuovamente che la parola client corrispondesse effettivamente al valore del campo.

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

Nota

I parser non devono filtrare in base al tempo, perché questa operazione viene già eseguita dalla query che usa il parser.

Analisi in corso

Una volta che la query ha selezionato i record rilevanti, potrebbe essere necessario analizzarli. In genere, l'analisi è necessaria se più campi evento vengono trasmessi in un singolo campo di testo.

Gli operatori KQL che eseguono l'analisi sono elencati di seguito, ordinati in base all'ottimizzazione delle prestazioni. Il primo fornisce le prestazioni più ottimizzate, mentre l'ultimo fornisce le prestazioni meno ottimizzate.

Operatore Descrizione
split Analizzare una stringa di valori delimitati.
parse_csv Analizzare una stringa di valori formattata come riga CSV (valori delimitati da virgole).
parse-kv Estrae informazioni strutturate da un'espressione stringa e rappresenta le informazioni in formato chiave/valore.
parse Analizzare più valori da una stringa arbitraria usando un criterio, che può essere un modello semplificato con prestazioni migliori o un'espressione regolare.
extract_all Analizzare singoli valori da una stringa arbitraria usando un'espressione regolare. extract_all offre prestazioni simili a parse se quest'ultimo usa un'espressione regolare.
extract Estrarre un singolo valore da una stringa arbitraria usando un'espressione regolare.

L'uso di extract offre prestazioni migliori rispetto a parse o extract_all se è necessario un valore singolo. Tuttavia, l'uso di più attivazioni di extract sulla stessa stringa di origine è meno efficiente rispetto a un singolo uso di parse o extract_all e dovrebbe essere evitato.
parse_json Analizzare i valori in una stringa formattata come JSON. Se sono necessari solo alcuni valori del codice JSON, l’uso di parse, extract o extract_all offre prestazioni migliori.
parse_xml Analizzare i valori in una stringa formattata come XML. Se sono necessari solo alcuni valori del codice XML, l’uso di parse, extract o extract_all offre prestazioni migliori.

Normalizzazione

Mapping dei tipi di campi

La forma più semplice di normalizzazione consiste nel rinominare un campo originale con il relativo nome normalizzato. A questo scopo usare l’operatore project-rename. L'uso di project-rename garantisce che il campo sia ancora gestito come campo fisico e assicura una gestione più efficiente del campo. Ad esempio:

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

Normalizzazione del formato e del tipo di campo

In molti casi, il valore originale estratto deve essere normalizzato. Ad esempio, in ASIM un indirizzo MAC usa i due punti come separatore, mentre l'origine può inviare un indirizzo MAC delimitato da trattini. L'operatore principale per la trasformazione dei valori è extend, insieme a un ampio set di funzioni stringa KQL, numeriche e di data.

Inoltre, verificare che i campi di output del parser corrispondano al tipo definito nello schema è fondamentale per il funzionamento dei parser. Ad esempio, potrebbe essere necessario convertire una stringa che rappresenta data e ora in un campo datetime. In questi casi sono utili funzioni come todatetime e tohex.

Ad esempio, l'ID evento univoco originale può essere inviato come numero intero, ma ASIM richiede che il valore sia una stringa per garantire un'ampia compatibilità tra le origini dati. Pertanto, quando si assegna il campo di origine, usare extend e tostring invece di project-rename:

  | extend EventOriginalUid = tostring(ReportId),

Campi e valori derivati

Potrebbe essere necessario eseguire il mapping del valore del campo di origine, una volta estratto, al set di valori specificati per il campo dello schema di destinazione. Le funzioni iff, case e lookup possono essere utili per eseguire il mapping dei dati disponibili ai valori di destinazione.

Ad esempio, il parser DNS Microsoft assegna il campo EventResult in base all'ID evento e al codice di risposta usando un'istruzione iff, come nel codice seguente:

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

Per eseguire il mapping di più valori, definire il mapping mediante l'operatore datatable e usare lookup per eseguire il mapping. Ad esempio, alcune origini riportano codici di risposta DNS numerici e il protocollo di rete, mentre lo schema impone la più comune rappresentazione di etichette di testo per entrambi. L'esempio seguente mostra come derivare i valori necessari usando datatable e 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

Si noti che lookup è utile ed efficiente anche quando il mapping ha solo due valori possibili.

Quando le condizioni di mapping sono più complesse, combinare iff, case e lookup. L'esempio seguente mostra come combinare lookup e case. L'esempio lookup riportato sopra restituisce un valore vuoto nel campo DnsResponseCodeName se il valore di ricerca non viene trovato. L'esempio case riportato di seguito lo aumenta usando il risultato dell'operazione lookup, se disponibile, e specificando condizioni aggiuntive in caso contrario.

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

Microsoft Sentinel offre utili funzioni per i valori di ricerca più comuni. Ad esempio, la ricerca di DnsResponseCodeName riportata sopra può essere implementata usando una delle funzioni seguenti:


| extend DnsResponseCodeName = _ASIM_LookupDnsResponseCode(DnsResponseCode)

| invoke _ASIM_ResolveDnsResponseCode('DnsResponseCode')

La prima opzione accetta come parametro il valore da cercare e consente di scegliere il campo di output, pertanto è utile come funzione di ricerca generale. La seconda opzione, più orientata ai parser, accetta come input il nome del campo di origine e aggiorna il campo ASIM necessario, in questo caso DnsResponseCodeName.

Per un elenco completo delle funzioni della Guida di ASIM, vedere Funzioni ASIM.

Campi di arricchimento

Oltre ai campi disponibili dall'origine, un evento ASIM risultante include campi di arricchimento che devono essere generati dal parser. In molti casi, i parser possono assegnare un valore costante ai campi, ad esempio:

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

Un altro tipo di campi di arricchimento che deve essere impostato dai parser è costituito dai campi di tipo, che definiscono il tipo del valore archiviato in un campo correlato. Ad esempio, il campo SrcUsernameType definisce il tipo del valore archiviato nel campo SrcUsername. Altre informazioni sui campi di tipo sono disponibili nella descrizione delle entità.

Nella maggior parte dei casi, ai tipi viene assegnato anche un valore costante. Tuttavia, in alcuni casi il tipo deve essere determinato in base al valore effettivo, ad esempio:

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

Microsoft Sentinel offre funzioni utili per la gestione dell'arricchimento. Ad esempio, usare la funzione seguente per assegnare automaticamente i campi SrcHostname, SrcDomain, SrcDomainType e SrcFQDN in base al valore del campo Computer.

  | invoke _ASIM_ResolveSrcFQDN('Computer')

Questa funzione imposta i campi nel modo seguente:

Campo Computer Campi di output
server1 SrcHostname: server1
SrcDomain, SrcDomainType, SrcFQDN tutti vuoti
server1.microsoft.com SrcHostname: server1
SrcDomain: microsoft.com
SrcDomainType: FQDN
SrcFQDN:server1.microsoft.com

Le funzioni _ASIM_ResolveDstFQDN e _ASIM_ResolveDvcFQDN eseguono un'attività simile popolando i campi Dst e Dvc correlati. Per un elenco completo delle funzioni della Guida di ASIM, vedere Funzioni ASIM.

Selezionare campi nel set di risultati

Facoltativamente, il parser può selezionare campi nel set di risultati. La rimozione di campi non necessari può migliorare le prestazioni e aggiungere chiarezza, evitando confusione tra i campi normalizzati e i campi di origine rimanenti.

Per selezionare i campi nel set di risultati vengono usati gli operatori KQL seguenti:

Operatore Descrizione Quando usarlo in un parser
project-away Rimuove i campi. Usare project-away per campi specifici che devono essere rimossi dal set di risultati. È consigliabile non rimuovere i campi originali non normalizzati dal set di risultati, a meno che non creino confusione o siano molto grandi, con possibili implicazioni sulle prestazioni.
project Seleziona i campi già esistenti o creati come parte dell'istruzione e rimuove tutti gli altri campi. L’uso di questo operatore non è consigliato in un parser, perché il parser non deve rimuovere altri campi non normalizzati.

Se occorre rimuovere campi specifici, ad esempio i valori temporanei usati durante l'analisi, usare project-away per rimuoverli dai risultati.

Ad esempio, quando si analizza una tabella di log personalizzata, usare l’operatore seguente per rimuovere i campi originali rimanenti che dispongono ancora di un descrittore di tipo:

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

Gestire le varianti di analisi

Importante

Le diverse varianti rappresentano tipi di evento diversi, comunemente mappati a schemi diversi, per cui occorre sviluppare parser distinti

In molti casi, gli eventi in un flusso di eventi includono varianti che richiedono una logica di analisi diversa. Per analizzare varianti diverse in un singolo parser, usare istruzioni condizionali come iff e case oppure usare una struttura di unione.

Per usare union per gestire più varianti, creare una funzione distinta per ogni variante e usare l'istruzione UNION per combinare i risultati:

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…

Per evitare eventi duplicati e un’elaborazione eccessiva, assicurarsi che ogni funzione filtri innanzitutto, usando i campi nativi, solo gli eventi che deve analizzare. Inoltre, se necessario, usare project-away in ogni ramo, prima dell'unione.

Distribuire i parser

Distribuire manualmente i parser copiandoli nella pagina Log di Monitoraggio di Azure e salvando la query come funzione. Questo metodo è utile per i test. Per altre informazioni, vedere Creare una funzione.

Per distribuire un numero elevato di parser, è consigliabile usare i modelli di ARM del parser, come indicato di seguito:

  1. Creare un file YAML basato sul modello rilevante per ogni schema e includervi la query. Iniziare con il modello YAML pertinente per lo schema e il tipo di parser, ossia di filtro o senza parametri.

  2. Usare il convertitore ASIM da YAML a modello di ARM per convertire il file YAML in un modello di Resource Manager.

  3. In caso di distribuzione di un aggiornamento, eliminare le versioni precedenti delle funzioni usando il portale o lo strumento PowerShell per l’eliminazione di funzioni.

  4. Distribuire il modello usando il portale di Azure oppure PowerShell.

È anche possibile combinare più modelli in un singolo processo di distribuzione usando modelli collegati.

Suggerimento

I modelli di ARM possono combinare risorse diverse, in modo che i parser possano essere distribuiti insieme a connettori, regole analitiche o watchlist, per citare alcune opzioni utili. Ad esempio, il parser può fare riferimento a una watchlist distribuita insieme a esso.

Testare i parser

Questa sezione descrive gli strumenti di test forniti da ASIM per testare i parser. Tenere comunque presente che i parser sono codice, a volte complesso, quindi si consiglia di eseguire le procedure standard di controllo qualità, come le revisioni del codice, oltre ai test automatizzati.

Installare gli strumenti di test ASIM

Per testare ASIM, distribuire lo strumento di test ASIM in un'area di lavoro di Microsoft Sentinel in cui:

  • È stato distribuito il parser.
  • È disponibile la tabella di origine usata dal parser.
  • La tabella di origine usata dal parser è popolata con una raccolta diversificata di eventi rilevanti.

Convalidare lo schema di output

Per assicurarsi che il parser produca uno schema valido, usare il tester dello schema ASIM eseguendo la query seguente nella pagina Log di Microsoft Sentinel:

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

Gestire i risultati nel modo seguente:

Error Azione
Campo obbligatorio [<Campo>] mancante Aggiungere il campo al parser. In molti casi si tratta di un valore derivato o di un valore costante e non di un campo già disponibile dall'origine.
Il campo mancante [<Campo>] è obbligatorio quando è presente la colonna obbligatoria [<Campo>] Aggiungere il campo al parser. In molti casi questo campo indica i tipi della colonna esistente a cui fa riferimento.
Il campo mancante [<Campo>] è obbligatorio quando è presente la colonna [<Campo>] Aggiungere il campo al parser. In molti casi questo campo indica i tipi della colonna esistente a cui fa riferimento.
Manca l'alias obbligatorio [<Campo>] che funge da alias della colonna esistente [<Campo>] Aggiungere l’alias al parser.
Manca l'alias consigliato [<Campo>] che funge da alias della colonna esistente [<Campo>] Aggiungere l’alias al parser.
Manca l'alias facoltativo [<Campo>] che funge da alias della colonna esistente [<Campo>] Aggiungere l’alias al parser.
Manca l'alias obbligatorio [<Campo>] che funge da alias della colonna mancante [<Campo>] Questo errore si accompagna a un errore simile per il campo con alias. Correggere l'errore del campo con alias e aggiungere questo alias al parser.
Tipo non corrispondente per il campo [<Campo>]. Attualmente è [<Tipo>] e dovrebbe essere [<Tipo>] Assicurarsi che il tipo di campo normalizzato sia corretto, in genere usando una funzione di conversione, ad esempio tostring.
info Azione
Campo consigliato [<Campo>] mancante Valutare l'aggiunta di questo campo al parser.
info Azione
Manca l'alias consigliato [<Campo>] che funge da alias della colonna non esistente [<Campo>] Se si aggiunge il campo con alias al parser, assicurarsi di aggiungere anche questo alias.
Manca l'alias facoltativo [<Campo>] che funge da alias della colonna non esistente [<Campo>] Se si aggiunge il campo con alias al parser, assicurarsi di aggiungere anche questo alias.
Campo facoltativo [<Campo>] mancante Sebbene i campi facoltativi siano spesso mancanti, vale la pena esaminare l'elenco per determinare se uno dei campi facoltativi può essere mappato dall'origine.
Campo aggiuntivo [<Campo>] non normalizzato Anche se i campi non normalizzati sono validi, vale la pena esaminare l'elenco per determinare se può essere eseguito il mapping di uno dei valori non normalizzati a un campo facoltativo.

Nota

Gli errori impediscono il corretto funzionamento dei contenuti che usano il parser. Gli avvisi non impediscono il funzionamento dei contenuti, ma possono ridurre la qualità dei risultati.

Convalidare i valori di output

Per assicurarsi che il parser produca valori validi, usare il tester dei dati ASIM eseguendo la query seguente nella pagina Log di Microsoft Sentinel:

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

La specifica di uno schema è facoltativa. Se non viene specificato uno schema, viene usato il campo EventSchema per identificare lo schema a cui deve essere conforme l'evento. Se un evento non include un campo EventSchema, vengono verificati solo i campi comuni. Se uno schema viene specificato come parametro, lo schema stesso verrà usato per testare tutti i record. Ciò è utile per i parser meno recenti che non impostano il campo EventSchema.

Nota

Anche quando non viene specificato uno schema, dopo il nome della funzione è necessario aggiungere parentesi vuote.

Questo test richiede un utilizzo intensivo delle risorse e potrebbe non funzionare sull'intero set di dati. Impostare X sul numero più grande per il quale la query non raggiunge il timeout oppure impostare l'intervallo di tempo per la query usando l’apposito controllo di selezione.

Gestire i risultati nel modo seguente:

Messaggio Azione
(0) Errore: tipo non corrispondente per la colonna [<Campo>]. Attualmente è [<Tipo>] e dovrebbe essere [<Tipo>] Assicurarsi che il tipo di campo normalizzato sia corretto, in genere usando una funzione di conversione, ad esempio tostring.
(0) Errore: valori non validi (fino a 10 elencati) per il campo [<Campo>] di tipo [<Tipo logico>] Assicurarsi che il parser esegua il mapping del campo di origine corretto al campo di output. Se il mapping è corretto, aggiornare il parser per trasformare il valore di origine nel tipo, nel valore o nel formato corretto. Per altre informazioni sui valori e sui formati corretti per ogni tipo logico, vedere l'elenco di tipi logici.

Tenere presente che lo strumento di test elenca solo un campione di 10 valori non validi.
(1) Avviso: valore vuoto nel campo obbligatorio [<Campo>] I campi obbligatori devono essere popolati, non semplicemente definiti. Controllare se il campo può essere popolato da altre origini per i record per i quali l'origine attuale è vuota.
(2) Informazioni: valore vuoto nel campo consigliato [<Campo>] I campi consigliati devono in genere essere popolati. Controllare se il campo può essere popolato da altre origini per i record per i quali l'origine attuale è vuota.
(2) Informazioni: valore vuoto nel campo facoltativo [<Campo>] Controllare se il campo con alias è obbligatorio o consigliato e, in tal caso, se può essere popolato da altre origini.

Molti messaggi segnalano anche il numero di record che hanno generato il messaggio e la relativa percentuale del campione totale. Questa percentuale è un buon indicatore dell'importanza del problema. Ad esempio, per un campo consigliato:

  • Il 90% di valori vuoti può indicare un problema generale di analisi.
  • Il 25% di valori vuoti può indicare una variante di evento non analizzata correttamente.
  • Un numero esiguo di valori vuoti può indicare un problema trascurabile.

Nota

Gli errori impediscono il corretto funzionamento dei contenuti che usano il parser. Gli avvisi non impediscono il funzionamento dei contenuti, ma possono ridurre la qualità dei risultati.

Contribuire con i propri parser

È possibile contribuire con i propri parser alla distribuzione primaria di ASIM. Se accettati, i parser saranno disponibili per tutti i clienti come parser predefiniti di ASIM.

Per contribuire con i propri parser:

Documentazione degli avvisi accettati

Se gli avvisi elencati dagli strumenti di test ASIM sono considerati validi per un parser, documentare gli avvisi accettati nel file YAML del parser usando la sezione Exceptions, come illustrato nell'esempio seguente.

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

L'avviso specificato nel file YAML deve essere una forma breve del messaggio di avviso che lo identifichi in modo univoco. Il valore viene usato per trovare le corrispondenze con i messaggi di avviso durante l'esecuzione di test automatizzati e ignorarli.

Linee guida per l'invio di esempi

I dati di esempio sono necessari per la risoluzione dei problemi del parser e per garantire che gli aggiornamenti futuri del parser siano conformi agli esempi precedenti. Gli esempi inviati devono includere qualsiasi variante di evento supportata dal parser. Assicurarsi che gli eventi di esempio includano tutti i possibili tipi, formati e varianti di evento, ad esempio eventi che rappresentano attività riuscite e non riuscite. Assicurarsi inoltre che siano rappresentate le varianti nei formati dei valori. Ad esempio, se un nome di host può essere rappresentato come nome di dominio completo (FQDN) o come semplice nome di host, gli eventi di esempio devono includere entrambi i formati.

Per inviare gli esempi di eventi, seguire questa procedura:

  • Nella schermata Logs eseguire una query che estragga dalla tabella di origine solo gli eventi selezionati dal parser. Ad esempio, per il parser Infoblox DNS, usare la query seguente:
    Syslog
    | where ProcessName == "named"

  • Esportare i risultati usando l'opzione Esporta in CSV in un file denominato <EventVendor>_<EventProduct>_<EventSchema>_IngestedLogs.csv, dove EventProduct, EventProduct e EventSchema sono i valori assegnati dal parser a tali campi.

  • Nella schermata Logs eseguire una query che restituirà lo schema o la tabella di input del parser. Ad esempio, per lo stesso parser Infoblox DNS, la query è:

    Syslog
    | getschema

  • Esportare i risultati usando l'opzione Esporta in CSV in un file denominato <TableName>_schema.csv, dove TableName è il nome della tabella di origine usata dal parser.

  • Includere entrambi i file nella richiesta pull nella cartella /Sample Data/ASIM. Se il file esiste già, aggiungere l'handle GitHub al nome, ad esempio: <EventVendor>_<EventProduct>_<EventSchema>_SchemaTest_<GitHubHanlde>.csv

Linee guida per l'invio dei risultati dei test

I risultati dei test sono importanti per verificare la correttezza del parser e comprendere eventuali eccezioni segnalate.

Per inviare i risultati dei test, seguire questa procedura:

  • Eseguire i test del parser descritti nella sezione Testare i parser.

  • Esportare i risultati dei test usando l'opzione Esporta in CSV nei file denominati <EventVendor>_<EventProduct>_<EventSchema>_SchemaTest.csv e <EventVendor>_<EventProduct>_<EventSchema>_DataTest.csv rispettivamente.

  • Includere entrambi i file nella richiesta pull nella cartella /Parsers/ASim<schema>/Tests.

Passaggi successivi

In questo articolo è stato illustrato lo sviluppo di parser ASIM.

Altre informazioni sui parser ASIM:

Altre informazioni su ASIM in generale: