Разработка средств анализа расширенной информационной модели безопасности (ASIM)

Пользователи расширенной информационной модели безопасности (ASIM) используют унифицированные средства синтаксического анализа вместо имен таблиц в своих запросах, чтобы просматривать данные в нормализованном формате и включать в запрос все данные, относящиеся к схеме. Объединяющие средства синтаксического анализа, в свою очередь, используют средства синтаксического анализа, зависящие от источника, для обработки конкретных сведений о каждом источнике.

Microsoft Sentinel предоставляет встроенные средства синтаксического анализа для многих источников данных. Вы можете изменить или разработать эти средства синтаксического анализа для конкретного источника в следующих ситуациях:

  • Когда ваше устройство предоставляет события, соответствующие схеме ASIM, но парсер для вашего устройства и подходящая схема отсутствуют в Microsoft Sentinel.

  • Если средства синтаксического анализа, зависящие от источника ASIM, доступны для устройства, но ваше устройство отправляет события в методе или формате, отличном от ожидаемого средствами синтаксического анализа ASIM. Рассмотрим пример.

    • Исходное устройство может быть настроено для отправки событий нестандартным способом.

    • устройство может иметь версию, отличную от той, которая поддерживается средством синтаксического анализа ASIM;

    • события могут собираться, изменяться и пересылаться промежуточной системой.

Чтобы понять, как средства синтаксического анализа вписываются в архитектуру ASIM, см. схему архитектуры ASIM.

Процесс разработки пользовательского синтаксического анализатора ASIM

В следующей схеме описаны основные этапы разработки настраиваемого парсера ASIM для конкретного источника:

  1. Соберите примеры логов.

  2. Определите, каким схемам соответствуют события, отправляемые источником. Подробнее см. в статье Общее представление схемы.

  3. Сопоставьте поля исходного события с выбранной схемой или схемами.

  4. Разработайте одно или несколько средств синтаксического анализа ASIM для вашего источника. Вам потребуется разработать парсер для фильтрации и парсер без параметров для каждой схемы, относящейся к источнику.

  5. Протестируйте свое средство синтаксического анализа.

  6. Разверните парсеры в рабочие области Microsoft Sentinel.

  7. Обновите соответствующее объединяющее средство синтаксического анализа ASIM, чтобы оно ссылалось на новое пользовательское средство синтаксического анализа. Дополнительные сведения см. в статье Управление средствами синтаксического анализа ASIM.

  8. Вы также можете добавить собственные средства синтаксического анализа в основной дистрибутив ASIM. Добавленные парсеры также можно сделать доступными во всех рабочих областях в качестве встроенных.

В этой статье описывается процедура разработки, тестирования и развертывания процесса.

Соберите образцы журналов

Для создания эффективных средств синтаксического анализа ASIM требуется репрезентативный набор журналов, который в большинстве случаев потребует настройки исходной системы и ее подключения к Microsoft Sentinel. Если у вас нет исходного устройства, вы сможете развернуть множество устройств для разработки и тестирования в облачных службах с оплатой по мере использования.

Кроме того, поиск документации и примеров журналов от поставщиков может помочь ускорить разработку и уменьшить количество ошибок, обеспечивая охват различных форматов журналов.

Репрезентативный набор журналов должен включать:

  • События с разными результатами событий.
  • События с различными действиями реагирования.
  • Различные форматы для имени пользователя, имени узла и идентификаторов, а также других полей, требующих нормализации значений.

Tip

Запустите новое пользовательское средство синтаксического анализа с помощью существующего средства синтаксического анализа для той же схемы. Использование существующего средства синтаксического анализа особенно важно для фильтрации средств синтаксического анализа, чтобы убедиться, что они принимают все параметры, необходимые для схемы.

Составление карты планирования

Перед разработкой средства синтаксического анализа сопоставьте сведения, доступные в исходном событии или событиях, с выбранной вами схемой:

  • Сопоставьте все обязательные поля (желательно также сопоставить рекомендуемые).
  • Попробуйте сопоставить любую информацию, доступную из источника, с нормализованным полям. Если она недоступна в рамках выбранной схемы, рассмотрите возможность сопоставления с полями, доступными в других схемах.
  • Сопоставьте значения полей в источнике с нормализованными значениями, допустимыми в ASIM. Исходное значение хранится в отдельном поле, например EventOriginalResultDetails.

Разработка средств синтаксического анализа

Разработайте как парсер для фильтрации, так и парсер без параметров для каждой соответствующей схемы.

Настраиваемый анализатор — это запрос KQL, разработанный на странице Microsoft Sentinel Logs. Запрос средства синтаксического анализа состоит из трех частей:

Фильтр>Анализа>Подготовка полей

Фильтрация

Фильтрация соответствующих записей

Во многих случаях таблица в Microsoft Sentinel включает несколько типов событий. Рассмотрим пример.

  • Таблица Syslog содержит данные из нескольких источников.
  • Пользовательские таблицы могут содержать сведения из одного источника, который предоставляет несколько типов событий и может соответствовать различным схемам.

Таким образом, средство синтаксического анализа должно сначала отфильтровать только те записи, которые относятся к целевой схеме.

Фильтрация в KQL выполняется с помощью оператора where. Например, событие Sysmon 1 сообщает о создании процесса и поэтому должно быть нормализовано до схемы ProcessEvent. Событие Sysmon event 1 является частью Event таблицы, поэтому вы фильтруете только для событий создания процессов Sysmon с помощью следующего запроса:

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

Important

Средство синтаксического анализа не должно выполнять фильтрацию по времени. Запрос, использующий средство синтаксического анализа, будет применять диапазон времени.

Фильтрация по типу источника с помощью списка отслеживания

В некоторых случаях само событие не содержит сведений, которые позволили бы выполнять фильтрацию по определенным типам источников.

Например, события Infoblox DNS отправляются в виде сообщений системного журнала, и их трудно отличить от сообщений системного журнала, отправленных из других источников. В таких случаях средство синтаксического анализа использует список источников, определяющих соответствующие события. Этот список ведётся в списке наблюдения Sources_by_SourceType.

Чтобы использовать список наблюдения ASimSourceType в ваших анализаторах, используйте функцию _ASIM_GetSourceBySourceType в разделе фильтрации анализатора. Например, парсер DNS Infoblox ограничивает записи только источниками Infoblox NIOS, добавляя следующий фильтр, гарантируя, что парсер обрабатывает только соответствующие записи Syslog:

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

Чтобы использовать этот пример в средстве синтаксического анализа, выполните следующие действия.

  • Замените Computer на имя поля, включающее сведения об источнике для вашего источника. Вы можете оставить это как Computer для любых парсеров на базе Syslog.

  • Замените токен InfobloxNIOS на значение по вашему выбору для вашего парсера. Сообщите пользователям средства синтаксического анализа, что они должны обновить список отслеживания ASimSourceType, используя выбранное вами значение, а также список источников, отправляющих события этого типа.

Фильтрация на основе параметров средства синтаксического анализа

При разработке парсеров фильтрации убедитесь, что ваш парсер принимает параметры фильтрации для соответствующей схемы, как описано в справочной статье для этой схемы. Использование существующего средства синтаксического анализа в качестве начальной точки гарантирует, что ваше средство синтаксического анализа содержит правильную сигнатуру функции. В большинстве случаев фактический код фильтрации также аналогичен для фильтрации средств синтаксического анализа для одной и той же схемы.

При фильтрации необходимо помнить о следующих моментах.

  • Выполняйте фильтрацию перед синтаксическим анализом с использованием физических полей. Если отфильтрованные результаты недостаточно точны, повторите тест после анализа, чтобы точно настроить результаты. Дополнительные сведения см. в разделе Оптимизация фильтрации.
  • Не выполняйте фильтрацию, если параметр не определен и по-прежнему содержит значение по умолчанию.

Используйте условные предикаты для реализации опциональной фильтрации параметров парсера, чтобы парсер применял фильтры только тогда, когда вызывающие предоставляют значения. В следующих примерах показано, как реализовать фильтрацию для параметра строки, где значением по умолчанию обычно является "*", и для параметра списка, где значением по умолчанию обычно является пустой список.

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

Для получения дополнительной информации о array_length функции и операторе has_any см. документацию Kusto:

Оптимизация фильтрации

Чтобы обеспечить производительность средства синтаксического анализа, обратите внимание на следующие рекомендации по фильтрации:

  • Всегда фильтруйте по встроенным, а не по проанализированным полям. Хотя иногда проще выполнять фильтрацию с помощью проанализированных полей, это значительно снижает производительность.
  • Используйте операторы, обеспечивающие оптимизированную производительность. В частности, ==, has и startswith. Использование таких операторов, как contains или matches regex, также существенно влияет на производительность.

Рекомендации по фильтрации для повышения производительности не всегда легко выполнить. Например, использование has менее точно, чем contains. В других случаях сопоставление встроенного поля, например SyslogMessage, является менее точным, чем сравнение извлеченного поля, например DvcAction. В таких случаях рекомендуется по-прежнему выполнять предварительную фильтрацию с помощью оператора оптимизации производительности по встроенному полю и повторять фильтр, используя более точные условия после синтаксического анализа.

Например, см. следующий фрагмент синтаксического анализатора Infoblox DNS. Сначала средство синтаксического анализа проверяет наличие в поле SyslogMessage has слова client. Однако термин может использоваться в другом месте сообщения, поэтому после синтаксического анализа поля Log_Type средство синтаксического анализа снова проверяет, действительно ли слово client было значением поля.

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

Замечание

Синтаксические анализаторы не должны фильтровать данные по времени, так как запрос, использующий средство синтаксического анализа, уже выполняет фильтрацию по времени.

Разбор

После того как запрос выберет соответствующие записи, может потребоваться проанализировать их. Как правило, анализ необходим, если несколько полей событий передаются в одном текстовом поле.

Ниже перечислены операторы KQL, выполняющие синтаксический анализ, упорядоченные по оптимизации производительности. Первый обеспечивает наиболее оптимизированную производительность, а последний — наименее оптимизированную.

Оператор или функция() Description
функция split() Парсинг строки с разделёнными значениями.
функция parse_csv() Проанализировать строку значений, форматированную как строку CSV (значения, разделённые запятыми).
Оператор parse-kv Извлекает структурированную информацию из строкового выражения и представляет информацию в форме "ключ-значение".
Оператор синтаксического анализа Анализ нескольких значений из произвольной строки с помощью шаблона, который может быть упрощенным шаблоном с более высокой производительностью или регулярным выражением.
функция extract_all() Анализ отдельных значений из произвольной строки с использованием регулярного выражения. extract_all имеет производительность, аналогичную parse, если в последнем случае используется регулярное выражение.
Функция extract() Извлечение одного значения из произвольной строки с использованием регулярного выражения.

Использование extract обеспечивает лучшую производительность, чем parse или extract_all, если требуется одно значение. Однако несколько активаций extract для одной и той же исходной строки менее эффективно, чем одна активация parse или extract_all, и этого варианта следует избегать.
функция parse_json() Выполните синтаксический анализ значений в строке в формате JSON. Если вам нужно получить из JSON только несколько значений, parse, extract и extract_all обеспечивают лучшую производительность.
Функция parse_xml() Выполните синтаксический анализ значений в строке в формате XML. Если вам нужно получить из XML только несколько значений, parse, extract и extract_all обеспечивают лучшую производительность.

Нормализация

Сопоставление имен полей

Простейшая форма нормализации — переименование исходного поля в его нормализованное имя. Для этого используйте оператор project-rename . Использование project-rename гарантирует, что поле по-прежнему будет управляться как физическое поле, а его обработка будет более эффективной. Например, следующий запрос сопоставляет исходные поля аккаунта с их нормализованными ASIM-именами актёров:

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

Нормализация формата и типа полей

Во многих случаях извлеченное исходное значение необходимо нормализовать. Например, в ASIM в MAC-адресе в качестве разделителя используются двоеточия, а источник может отправлять MAC-адрес с разделителями-дефисами. Основным оператором преобразования значений является extend; кроме того, применяется широкий набор функций KQL для работы со строками, числами и датами.

Кроме того, для работы парсеров крайне важно, чтобы поля вывода парсера соответствовали типам, определённым в схеме. Например, может потребоваться преобразовать строку, представляющую дату и время, в поле datetime. В таких случаях полезны такие функции, как todatetime и tohex .

Например, исходный уникальный идентификатор события может быть отправлен в виде целого числа, но ASIM требует, чтобы значение было строковым, чтобы обеспечить широкую совместимость источников данных. Поэтому при назначении исходного поля преобразуем числовое значение в строку с extend помощью и tostring вместо project-rename, чтобы нормированное поле соответствовало требованию схемы типа строк:

  | extend EventOriginalUid = tostring(ReportId),

Производные поля и значения

Значение исходного поля после извлечения может потребоваться сопоставить с набором значений, указанных для поля целевой схемы. Функции iff, case и lookup могут быть полезны для сопоставления доступных данных с целевыми значениями.

Например, парсер Microsoft DNS выводит нормализованный результат успеха или неудачи на основе кодов событий и ответов, специфичных для источника. Парсер назначает EventResult поле на основе идентификатора события и кода ответа с помощью iff оператора, следующим образом:

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

Чтобы сопоставить несколько значений, задайте сопоставление с помощью оператора datatable и используйте lookup для его выполнения. Например, некоторые источники сообщают числовые коды ответов DNS и сетевых протоколов, в то время как схема требует более распространенного представления текстовых меток для обоих. Следующий пример демонстрирует, как создавать таблицы поиска, которые сопоставляют числовые идентификаторы протокола и коды ответа DNS на их нормализованные текстовые метки, а затем применять эти поиски к проанализированным данным с помощью datatable и 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

Обратите внимание, что поиск полезен и эффективен, если сопоставление имеет только два возможных значения.

Если условия сопоставления более сложные, объедините iff, case и lookup. В приведенном ниже примере показано, как объединить lookup и case. В приведенном выше примере lookup в поле DnsResponseCodeName возвращается пустое значение, если искомое значение не найдено. В приведённом ниже примере case он дополняется за счёт использования результата операции lookup, если он доступен, а в противном случае — за счёт указания дополнительных условий. Используйте этот подход для обработки несоответствующих значений поиска, возвращаясь к дополнительным условиям или метке по умолчанию:

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

Microsoft Sentinel предоставляет встроенные вспомогательные функции для распространённых значений поиска. Вместо ручного построения datatablelookup a и для известных отображений, эти функции можно использовать для прямого заполнения нормализованного поля. Например, приведённый DnsResponseCodeName выше поиск можно реализовать с помощью одной из следующих функций:


| extend DnsResponseCodeName = _ASIM_LookupDnsResponseCode(DnsResponseCode)

| invoke _ASIM_ResolveDnsResponseCode('DnsResponseCode')

Первый вариант принимает в качестве параметра значение, которое нужно найти, и позволяет выбрать поле вывода, что делает его полезным в качестве общей функции поиска. Второй вариант более ориентирован на средства синтаксического анализа, принимает в качестве входных данных имя исходного поля и обновляет необходимое поле ASIM, в данном случае DnsResponseCodeName.

Полный список вспомогательных функций ASIM см. в статье Функции ASIM.

Поля обогащения

Помимо полей, доступных из источника, результирующее событие ASIM включает поля обогащения, которые должно создать средство синтаксического анализа. Во многих случаях парсеры могут присваивать этим полям постоянное значение. Заполните стандартные поля обогащения так, чтобы каждая парсируемая запись включала согласованные метаданные продукта, поставщика и схемы, например:

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

Другим типом полей обогащения, которые должны задать средства синтаксического анализа, являются поля типов, которые обозначают тип значения, хранящегося в связанном поле. Например, поле SrcUsernameType указывает тип значения, хранящегося в поле SrcUsername. Дополнительные сведения о полях типов можно найти в описании сущностей.

В большинстве случаев типам также присваивается постоянное значение. Однако в некоторых случаях тип нужно определить на основе фактической стоимости. Например, определите, является ли пропарсированное имя хоста полностью квалифицированным доменным именем (FQDN), проверив, содержит ли оно более одного сегмента:

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

Microsoft Sentinel предоставляет полезные функции для работы с обогащением данных. Например, используйте _ASIM_ResolveSrcFQDN вспомогательную функцию, чтобы вывести нормализованное исходное имя хоста, домен, тип домена и поля FQDN из столбца Computer . Следующий фрагмент автоматически заполняет SrcHostnameполя , SrcDomain, SrcDomainType, и SrcFQDN на основе значения в Computer поле.

  | invoke _ASIM_ResolveSrcFQDN('Computer')

Эта функция задает поля следующим образом:

Область компьютерных технологий Поля вывода
server1 SrcHostname: server1
SrcDomain, SrcDomainType, SrcFQDN все пустые
server1.microsoft.com SrcHostname: server1
SrcDomain: microsoft.com
SrcDomainType: полное доменное имя
SrcFQDN:server1.microsoft.com

Функции _ASIM_ResolveDstFQDN и _ASIM_ResolveDvcFQDN выполняют аналогичную задачу, заполняя связанные Dst и Dvc поля. Полный список вспомогательных функций ASIM см. в статье Функции ASIM.

Выбор полей в результирующем наборе

При необходимости средство синтаксического анализа может выбирать поля в наборе результатов. Удаление ненужных полей может повысить производительность и добавить ясность, избегая путаницы между нормализованными полями и оставшимися исходными полями.

Для выбора полей в наборе результатов используются следующие операторы KQL:

Operator Description Когда следует использовать его в анализаторе синтаксиса
project-away Удаляет поля. Используйте project-away для конкретных полей, которые нужно удалить из результирующего набора. Мы не рекомендуем удалять исходные поля, которые не нормализованы из результирующих наборов, если они не создают путаницу или имеют очень большой размер и могут повлиять на производительность.
проект Выбирает поля, которые существовали ранее или были созданы в рамках инструкции, и удаляет все остальные поля. Не рекомендуется использовать в синтаксическом анализаторе, так как средство синтаксического анализа не должно удалять другие поля, которые не нормализованы.

Если необходимо удалить определенные поля, например временные значения, используемые при синтаксическом анализе, используйте project-away , чтобы удалить их из результатов.

Например, при разборе пользовательской таблицы логарифма уберите оставшиеся типизированные столбцы (например, поля с _d, _s, _b, или _g суффиксами), чтобы вывод парсера содержал только нормализованные поля, которые вы намерены сохранить:

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

Обработка вариантов синтаксического анализа

Important

Различные варианты представляют разные типы событий, для которых обычно используются разные схемы и разрабатываются отдельные парсеры.

Во многих случаях события в потоке событий включают варианты, требующие разной логики синтаксического анализа. Чтобы проанализировать различные варианты в одном синтаксическом анализаторе, используйте условные операторы, такие как iff и case, или структуру объединения.

Чтобы использовать union для обработки нескольких вариантов, создайте отдельную функцию для каждого варианта и используйте оператор union для объединения результатов:

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…

Чтобы избежать дублирования событий и лишней обработки, убедитесь, что каждая функция начинает работу с фильтрации (с использованием собственных полей) только тех событий, которые предназначены для синтаксического анализа. Кроме того, при необходимости используйте оператор project-away в каждой ветви перед объединением.

Развертывание средств синтаксического анализа

Разверните средства синтаксического анализа вручную, скопировав их на страницу журнала мониторинга Azure и сохранив запрос как функцию. Этот способ удобен для тестирования. Дополнительные сведения см. в статье Создание функции.

Чтобы развернуть большое количество средств синтаксического анализа, рекомендуется использовать шаблоны ARM для средств синтаксического анализа следующим образом.

  1. Создайте файл YAML на основе соответствующего шаблона для каждой схемы и включите в него свой запрос. Начните с шаблона YAML, соответствующего схеме и типу средства синтаксического анализа, без фильтрации или параметров.

  2. Используйте преобразователь шаблонов ASIM YAML для ARM , чтобы преобразовать файл YAML в шаблон ARM.

  3. При развертывании обновления удалите старые версии функций с помощью портала или инструмента PowerShell для удаления функций.

  4. Разверните шаблон с помощью портала Azure или PowerShell.

Вы также можете объединить несколько шаблонов в один процесс развертывания с помощью связанных шаблонов.

Tip

Шаблоны ARM могут объединять различные ресурсы, поэтому средства синтаксического анализа можно развертывать вместе с соединителями, правилами аналитики или списками отслеживания, чтобы назвать несколько полезных вариантов. Например, ваш парсер может ссылаться на список отслеживания, который развертывается вместе с ним.

Парсеры тестов

ASIM предоставляет инструменты тестирования, которые можно использовать для проверки ваших пользовательских парсеров. При этом средства синтаксического анализа — это код, иногда сложный, и в дополнение к автоматическому тестированию рекомендуется использовать стандартные методы обеспечения качества, такие как проверки кода.

Установка средств тестирования ASIM

Перед развертыванием инструмента тестирования ASIM убедитесь, что у вас есть рабочее пространство Microsoft Sentinel, где:

  • Ваш парсер развернут.
  • Исходная таблица, используемая анализатором, доступна.
  • Исходная таблица, используемая анализатором, заполняется разнообразной коллекцией соответствующих событий.

Когда ваше рабочее пространство соответствует этим требованиям, разверните инструмент тестирования ASIM в этом пространстве.

Проверка выходной схемы

Чтобы убедиться, что ваш парсер создаёт корректную схему, выполните следующий тестовый запрос на странице Microsoft Sentinel Logs. Эта команда проверяет, совпадают ли поля, типы и псевдонимы вашего парсера с ожидаемой схемой ASIM:

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

Обработайте результаты следующим образом:

Ошибка Action
Отсутствует обязательное поле [<Поле>] Добавьте поле в средство синтаксического анализа. Во многих случаях это будет производное значение или константное значение, а не поле, которое уже доступно из источника.
Отсутствующее поле [<Поле>] является обязательным, если существует обязательный столбец [<Поле>] Добавьте поле в средство синтаксического анализа. Во многих случаях это поле обозначает типы существующего столбца, на который оно ссылается.
Отсутствующее поле [<поле>] является обязательным, если существует столбец [<поле>] Добавьте поле в средство синтаксического анализа. Во многих случаях это поле обозначает типы существующего столбца, на который оно ссылается.
Отсутствует обязательный псевдоним [<поле>], являющийся псевдонимом существующего столбца [<поле>] Добавьте псевдоним в парсер
Отсутствует рекомендуемый псевдоним [<поле>], являющийся псевдонимом существующего столбца [<поле>] Добавьте псевдоним в парсер
Отсутствует необязательный псевдоним [<поле>], являющийся псевдонимом существующего столбца [<поле>] Добавьте псевдоним в парсер
Отсутствует обязательный псевдоним [<поле>], являющийся псевдонимом отсутствующего столбца [<поле>] Эта ошибка сопровождается похожей ошибкой для поля с псевдонимом. Исправьте ошибку поля с псевдонимом и добавьте этот псевдоним в парсер.
Несоответствие типов для поля [<Поле>]. В настоящее время он имеет значение [<Type>] и должен иметь значение [<Type>] Убедитесь, что тип нормализованного поля правильный, обычно с помощью функции преобразования, такой как tostring.
Информация Action
Отсутствует рекомендуемое поле [<Поле>] Попробуйте добавить это поле в средство синтаксического анализа.
Информация Action
Отсутствует рекомендуемый псевдоним [<поле>], являющийся псевдонимом несуществующего столбца [<поле>] Если вы добавляете в парсер поле с псевдонимом, обязательно добавьте и этот псевдоним.
Отсутствует необязательный псевдоним [<поле>], являющийся псевдонимом несуществующего столбца [<поле>] Если вы добавляете в парсер поле с псевдонимом, обязательно добавьте и этот псевдоним.
Отсутствует необязательное поле [<поле>] Хотя необязательные поля часто отсутствуют, стоит просмотреть список, чтобы определить, можно ли сопоставить какие-либо необязательные поля из источника.
Дополнительное ненормализованное поле [<поле>] Хотя ненормализованные поля являются допустимыми, стоит просмотреть список, чтобы определить, можно ли сопоставить какие-либо ненормализованные значения с необязательным полем.

Замечание

Ошибки будут препятствовать правильной работе содержимого, использующего средство синтаксического анализа. Предупреждения не будут препятствовать работе содержимого, но могут снизить качество результатов.

Проверка выходных значений

Чтобы убедиться, что ваш парсер выдаёт корректные значения, используйте тестер данных ASIM для проверки значений полей на выборке вывода парсера и выявления ошибок или предупреждений. Выполните следующий запрос на странице Microsoft Sentinel Logs:

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

Указание схемы является необязательным. Если схема не указана, используется поле EventSchema для идентификации схемы, которой должно соответствовать событие. Если событие не включает EventSchema поле, будут проверяться только общие поля. Если схема указана в качестве параметра, она будет использоваться для проверки всех записей. Это полезно для старых парсеров, которые не устанавливают поле EventSchema.

Замечание

Даже если схема не указана, после имени функции требуются пустые скобки.

Этот тест является ресурсоемким и может не работать со всем набором данных. Задайте для X наибольшее число, для которого время ожидания запроса не будет истекать, или задайте диапазон времени для запроса с помощью средства выбора диапазона времени.

Обработайте результаты следующим образом:

Message Action
(0) Ошибка: несоответствие типов для столбца [<Поле>]. В настоящее время он имеет значение [<Type>] и должен иметь значение [<Type>] Убедитесь, что тип нормализованного поля правильный, обычно с помощью функции преобразования, такой как tostring.
(0) Ошибка: недопустимые значения (до 10 в списке) для поля [<Поле>] типа [<Логический тип>] Убедитесь, что средство синтаксического анализа сопоставляет правильное поле источника с полем вывода. При правильном сопоставлении обновите средство синтаксического анализа, чтобы преобразовать исходное значение в правильный тип, значение или формат. Дополнительные сведения о правильных значениях и форматах для каждого логического типа см. в списке логических типов.

Обратите внимание, что средство тестирования содержит только выборку из 10 недопустимых значений.
(1) Предупреждение: пустое значение в обязательном поле [<поле>] Обязательные поля должны быть заполнены, а не просто определены. Проверьте, можно ли заполнить поле из других источников для записей, для которых текущий источник пуст.
(2) Информация: пустое значение в рекомендуемом поле [<поле>] Рекомендуемые поля обычно следует заполнять. Проверьте, можно ли заполнить поле из других источников для записей, для которых текущий источник пуст.
(2) Информация: пустое значение в необязательном поле [<поле>] Проверьте, является ли поле с псевдонимом обязательным или рекомендуемым, и если да, можно ли его заполнить из других источников.

Многие сообщения также указывают количество записей, которые сформировали сообщение, и их процент от общего числа в выборке. Этот процент является хорошим показателем важности вопроса. Например, для рекомендуемого поля:

  • 90 % пустых значений могут указывать на общую проблему синтаксического анализа.
  • 25 % пустых значений могут указывать на разновидность события, которая не была проанализирована правильным образом.
  • Горстка пустых значений может быть незначительной проблемой.

Замечание

Ошибки будут препятствовать правильной работе содержимого, использующего средство синтаксического анализа. Предупреждения не будут препятствовать работе содержимого, но могут снизить качество результатов.

Внести вклад разработкой парсеров

Может потребоваться добавить средство синтаксического анализа в основной дистрибутив ASIM. Если они будут приняты, средства синтаксического анализа будут доступны каждому клиенту как встроенные средства синтаксического анализа ASIM.

Чтобы добавить свои парсеры:

Документирование принятых предупреждений

Если предупреждения, перечисленные инструментами тестирования ASIM, считаются действительными для парсера, задокументируйте принятые предупреждения в файле парсера YAML с помощью раздела «Исключения». Следующий пример YAML показывает, как записывать принятые предупреждения о тестах парсера в разделе определения парсера:Exceptions

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

Предупреждение, указанное в файле YAML, должно быть сокращением соответствующего предупреждения ASIM-тестера, достаточно уникальным для идентификации конкретного предупреждения. Это значение используется для сопоставления предупреждающих сообщений ASIM-тестера во время автоматизированного тестирования и игнорирования соответствующих предупреждений.

Рекомендации по отправке примеров

Пример данных необходим при устранении неполадок средства синтаксического анализа и для обеспечения соответствия будущих обновлений средства синтаксического анализа старым образцам. Отсылаемые примеры должны включать любой вариант события, поддерживаемый анализатором. Убедитесь, что примеры событий включают все возможные типы событий, форматы событий и варианты, такие как события, представляющие успешные и неудачные действия. Кроме того, убедитесь, что варианты форматов значений представлены. Например, если имя узла может быть представлено как полное доменное имя или простое имя узла, то примеры событий должны включать оба формата.

Чтобы отправить примеры событий, выполните следующие действия.

  • Logs На экране выполните запрос, который извлекает из исходной таблицы только события, выбранные анализатором. Например, для парсера DNS Infoblox используйте следующий запрос, чтобы получить только те записи Infoblox NIOS Syslog, которые обрабатывает парсер:
    Syslog
    | where ProcessName == "named"

  • Экспортируйте результаты, используя параметр "Экспорт в CSV", в файл с именем <EventVendor>_<EventProduct>_<EventSchema>_IngestedLogs.csv, где EventProduct, EventProduct, и EventSchema являются значениями, назначенными средством синтаксического анализа для этих полей.

  • На Logs экране запустите getschema исходную таблицу, чтобы проверить доступные столбцы и их типы. Экспортируйте эту информацию о схеме вместе с вашими выборочными данными. Например, для парсера DNS Infoblox запрос выглядит так:

    Syslog
    | getschema

  • Экспортируйте результаты с помощью параметра Экспорт в CSV в файл с именем <TableName>_schema.csv, где TableName — имя исходной таблицы, используемой анализатором.

  • Добавьте оба файла в ваш PR в папке /Sample Data/ASIM. Если файл уже существует, добавьте дескриптор GitHub в имя, например <EventVendor>_<EventProduct>_<EventSchema>_SchemaTest_<GitHubHandle>.csv

Рекомендации по отправке результатов теста

Результаты теста важны для проверки правильности средства синтаксического анализа и понимания любого сообщаемого исключения.

Чтобы отправить результаты теста, выполните следующие действия.

  • Запускайте тесты парсера так, как описано в разделе Тестовые парсеры.

  • и экспортируйте результаты тестов, используя параметр "Экспорт в CSV ", в файлы с именем <EventVendor>_<EventProduct>_<EventSchema>_SchemaTest.csv и <EventVendor>_<EventProduct>_<EventSchema>_DataTest.csv соответственно.

  • Добавьте оба файла в ваш PR в папке /Parsers/ASim<schema>/Tests.

Связанные материалы

Дополнительные сведения о средствах синтаксического анализа ASIM:

Дополнительные сведения о ASIM в целом:

  • Last updated on