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

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

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

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

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

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

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

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

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

Внимание

ASIM сейчас находится на стадии ПРЕДВАРИТЕЛЬНОЙ ВЕРСИИ. Предварительная версия дополнительных условий использования Azure включают дополнительные юридические условия, применимые к функциям Azure, которые находятся в бета-версии, предварительной версии или еще не общедоступны по другим причинам.

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

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

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

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

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

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

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

6. Разверните средства синтаксического анализа в рабочих областях Microsoft Sentinel.

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

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

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

Совет

Также ознакомьтесь с подробным вебинаром по средствам синтаксического анализа для нормализации и нормализованному содержимому Microsoft Sentinel или просмотрите соответствующую демонстрацию слайдов. Дополнительные сведения см. в разделе Дальнейшие действия.

Сбор образцов журналов

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

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

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

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

Совет

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

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

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

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

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

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

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

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

Фильтрация

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

Часто таблица в Microsoft Sentinel содержит события нескольких типов. Например:

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

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

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

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

Внимание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Operator	Description
split	Синтаксический анализ строки значений с разделителями.
parse_csv	Синтаксический анализ строки значений в формате CSV (значения с разделителями-запятыми).
parse-kv	Извлекает структурированные сведения из строкового выражения и представляет сведения в форме key/value.
parse	Анализ нескольких значений из произвольной строки на основе шаблона, который может быть упрощенным шаблоном с повышенной производительностью или регулярным выражением.
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 гарантирует, что поле по-прежнему будет управляться как физическое поле, а его обработка будет более эффективной. Например:

 | 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 и сетевой протокол, в то время как схема требует более распространенного представления текстовых подписей для обоих. В следующем примере показано, как наследовать необходимые значения с помощью 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 предоставляет удобные функции для общих значений поиска. Например, приведенный выше поиск 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. Дополнительные сведения о полях типа можно найти в описании сущностей.

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

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

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

  | invoke _ASIM_ResolveSrcFQDN('Computer')

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

Поле компьютера	Поля вывода
server1	SrcHostname: server1 SrcDomain, SrcDomainType, SrcFQDN все пустые
server1.microsoft.com	SrcHostname: server1 SrcDomain: microsoft.com SrcDomainType: FQDN SrcFQDN:server1.microsoft.com

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

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

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

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

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

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

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

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

Внимание

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

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

Чтобы использовать 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 Monitor и сохранения запроса в качестве функции. Этот способ удобен для тестирования. Дополнительные сведения см. в статье Создание функции.

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

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

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

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

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

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

Совет

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

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

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

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

Чтобы протестировать ASIM, разверните средство тестирования ASIM в рабочей области Microsoft Sentinel, где:

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

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

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

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

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

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

Сведения	Действие
Отсутствует рекомендуемое поле [<поле>]	Попробуйте добавить это поле в средство синтаксического анализа.

Сведения	Действие
Отсутствует рекомендуемый псевдоним [<поле>], являющийся псевдонимом несуществующего столбца [<поле>]	При добавлении поля с псевдонимом в средство синтаксического анализа необходимо также добавить этот псевдоним.
Отсутствует необязательный псевдоним [<поле>], являющийся псевдонимом несуществующего столбца [<поле>]	При добавлении поля с псевдонимом в средство синтаксического анализа необходимо также добавить этот псевдоним.
Отсутствует необязательное поле [<поле>]	Хотя необязательные поля часто отсутствуют, стоит просмотреть список, чтобы определить, можно ли сопоставить какие-либо необязательные поля из источника.
Дополнительное ненормализованное поле [<поле>]	Хотя ненормализованные поля являются допустимыми, стоит просмотреть список, чтобы определить, можно ли сопоставить какие-либо ненормализованные значения с необязательным полем.

Примечание.

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

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

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

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

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

Примечание.

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

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

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

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

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

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

Примечание.

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

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

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

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

• Разработка синтаксического анализа фильтрации и средства синтаксического анализа без параметров.
• Создайте YAML-файл для средства синтаксического анализа, как описано выше в разделе "Развертывание синтаксического анализа".
• Убедитесь, что средства синтаксического анализа передают все тесты без ошибок. Если какие-либо предупреждения остаются, задокументируйте их в файле YAML средства синтаксического анализа.
• Создайте запрос на вытягивание для репозитория GitHub Microsoft Sentinel, в том числе:
  • Файлы YAML синтаксического анализа в папках синтаксического анализа ASIM (/Parsers/ASim<schema>/Parsers)
  • Репрезентативные примеры данных в соответствии с рекомендациями по отправке примеров.
  • Результаты теста соответствуют рекомендациям по отправке результатов теста.

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

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

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-файле, должно представлять собой короткую форму однозначно идентифицируемого предупреждающего сообщения. Это значение используется для игнорирования соответствующих предупреждающих сообщений в ходе автоматического тестирования.

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

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

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

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

    Syslog
    | where ProcessName == "named"

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

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

    Syslog
    | getschema

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

• Включите оба файла в pr в папку /Sample Data/ASIM. Если файл уже существует, добавьте дескриптор GitHub в имя, например: <EventVendor>_<EventProduct>_<EventSchema>_SchemaTest_<GitHubHanlde>.csv

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

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

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

• Запустите тесты синтаксического анализа и описанные в разделе тестов .

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

• Включите оба файла в pr в папку /Parsers/ASim<schema>/Tests.

Следующие шаги

В этой статье рассматривается разработка средств синтаксического анализа ASIM.

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

• Общие сведения о средствах синтаксического анализа ASIM
• Использование анализаторов ASIM
• Управление анализаторами ASIM
• Список средств синтаксического анализа ASIM

Дополнительные сведения об ASIM в общем см. в следующих материалах:

• Ознакомьтесь с подробным вебинаром по средствам синтаксического анализа для нормализации и нормализованному содержимому Microsoft Sentinel или просмотрите слайды
• Обзор расширенной информационной модели безопасности (ASIM)
• Схемы расширенной информационной модели безопасности (ASIM)
• Содержимое расширенной информационной модели безопасности (ASIM)