Действия с парсерами

В TRON.ASOC реализован конструктор парсеров, с помощью которого можно создавать, редактировать, применять и удалять парсеры — пользовательские схемы разбора SARIF/JSON-отчетов для интеграции с системой.

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

Подробнее о JSONata см. в официальной документации.

Проверить выражения парсеров можно в стороннем инструменте проверки до их применения в системе. При сохранении парсеров система проверяет корректность введенного JSON и JSONata-выражений.

Поля маппинга и синтаксис JSONata

В JSON-схеме парсера разрешено использовать только предопределенный набор полей, соответствующих модели TRON.ASOC. При использовании полей также важен корректный регистр.

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

Поле TRON.ASOC	Поле в парсере	Назначение
Категория	category	Категория уязвимости
Критичность	severity	Уровень критичности уязвимости
CWE	cwe	Идентификатор CWE
CVE	cve	Идентификатор CVE
Исходный файл	source_file	Путь к файлу, содержащему уязвимость
Строка	line	Номер строки в коде
Название библиотеки	lib_name	Имя библиотеки (для SCA)
Версия библиотеки	lib_version	Версия библиотеки
Ветка/тег	source_branch_tag	Исходная ветка или тег
Объект	source_object	Объект, содержащий уязвимость
Код	matched_code	Фрагмент кода, содержащий уязвимость
CVSSv2	cvss_v2_score	Оценка CVSS v2
CVSSv3	cvss_v3_score	Оценка CVSS v3
CVSSv4	cvss_v4_score	Оценка CVSS v4
CVSS(?)	cvss_vu_score	Оценка CVSS(?)
Эксплуатируемость	exploitability	Оценка эксплуатируемости уязвимости
Описание	description	Информация об уязвимости
Элементы кода	code_elements	Структурированные элементы кода, содержащего уязвимость (см. примечание ниже)

info

Поле code_elements доступно только для инструментов безопасности, чьи кодовые адаптеры формируют это поле: ESLint, GitLab SAST, PT AI/SASTAV. Для остальных инструментов безопасности поле code_elements в пользовательском парсере недоступно.

Так как JSONata не позволяет напрямую собрать вложенный объект из скалярных значений, для заполнения этого поля используются специальные функции (по одной на каждый из перечисленных инструментов):

• eslintCodeElements(...);
• gitlabsastCodeElements(...);
• sastavCodeElements(...).

Эти функции принимают данные находки из SARIF-отчета соответствующего инструмента и возвращают готовую структуру code_elements для этого инструмента.

Каждое поле заполняется выражением JSONata, которое возвращает значение из SARIF-файла. Доступны следующие выражения:

• прямые пути — runs[0].results[0].level;
• fallback-выражения (логическое ИЛИ) — path1 or path2;
• маппинг значений — $lookup({...}, expr);
• фильтрация массива — array[field = "value"];
• частичный поиск — array[$ ~> /regex/].

Ограничения конструктора парсеров

Конфигурация парсера поддерживает поле sections, которое содержит список подконфигов с тем же набором полей, что и items_path, severity, category и т.д. В отличие от единственного режима на весь конфиг, секции внутри sections объединяются: находки, извлеченные по каждой секции, собираются вместе в результате разбора одного отчета.

Это снимает ограничение, при котором один парсер мог извлечь найденные артефакты только из одного массива отчета за раз. Для инструментов безопасности, отчет которых содержит несколько независимых массивов разных типов находок (например, отчет Trivy содержит уязвимости, мисконфигурации и секреты), можно описать все типы находок одним парсером, содержащим по одной секции на каждый тип:

{
  "sections": [
    { "items_path": "Results[].Vulnerabilities", "severity": "...", "category": "..." },
    { "items_path": "Results[].Misconfigurations", "severity": "...", "category": "..." },
    { "items_path": "Results[].Secrets", "severity": "...", "category": "..." }
  ]
}

Для полей, формируемых на основе описания правила SARIF (например, category, cwe), соответствие между найденной проблемой и описанием правила определяется по позиционному индексу правила (ruleIndex), если он присутствует в отчете. Кодовый парсер того же инструмента безопасности сопоставляет их по строковому идентификатору правила (ruleId).

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

Создание нового парсера

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

• Просмотр парсеров;
• Создание/редактирование парсеров;
• Удаление парсеров.

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

1. Перейдите в раздел Интеграции.
2. Нажмите кнопку Парсеры.
3. В открывшемся разделе Парсеры нажмите кнопку Добавить парсер.

4. В окне добавления нового парсера введите следующие данные:
   • название парсера;
   • описание парсера;
   • конфигурация парсера в формате JSON.
5. Нажмите кнопку Создать.

Новый парсер будет отображаться в списке парсеров в разделе Парсеры.

Пример парсера

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

{
  "severity": "$lookup({\"error\": \"4\", \"warning\": \"2\", \"note\": \"1\", \"none\": \"-1\"}, runs[0].results[0].level)",
  "source_file": "runs[0].results[0].locations[0].physicalLocation.artifactLocation.uri"
}

Создание нового парсера на основе имеющегося

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

1. Перейдите в раздел Интеграции.
2. Нажмите кнопку Парсеры.
3. Нажмите кнопку дополнительных действий () возле необходимого парсера.
4. Выберите вариант Использовать как шаблон.
5. В окне добавления нового парсера введите следующие данные:
   • название парсера;
   • описание парсера;
   • конфигурация парсера в формате JSON.
6. Нажмите кнопку Создать.

Новый парсер будет отображаться в списке парсеров в разделе Парсеры.

info

При создании парсера на основе имеющегося копируется JSON-схема исходного парсера в текущем виде.

Если за основу взять один из предустановленных SARIF-парсеров (например, SARIF: General), учитывайте, то для инструмента безопасности с предустановленным SARIF-парсером обычно применяется его кодовый (Go) аналог, а не JSONata-конфиг. Соответствие между ними подтверждается автотестами эквивалентности, но это не гарантирует, что скопированная схема покрывает все нюансы поведения кодового парсера.

Создание парсера для инструмента безопасности, не поддерживаемого TRON.ASOC

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

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

1. Получите пример отчета от подключаемого инструмента в формате JSON или SARIF.
2. Составьте конфигурацию парсера (маппинг полей отчета в формате JSONata).
3. Создайте новый парсер (подробнее см. раздел Создание нового парсера).
4. Создайте новую интеграцию с инструментом безопасности для импорта результатов. Подробнее об этом см. в разделе Подключение интеграции с пользовательским инструментом безопасности (кастомной интеграции).
5. При настройке новой интеграции выберите парсер, созданный на шаге 3.
6. Перейдите в необходимый проект в разделе Проекты.
7. Выберите слой, в котором будет выполняться проверка, либо создайте новый (подробнее см. в разделах Создание слоя с нуля и Создание слоя по шаблону).
8. Создайте новую проверку безопасности в слое (подробнее см. в разделе Создание проверки безопасности).
9. Выберите инструмент, созданный на шаге 4.
10. Выберите источник сканирования или создайте новую интеграцию с источником (подробнее см. в разделе Подключение интеграции с источником сканирования).
11. Импортируйте пример отчета от подключаемого инструмента безопасности (подробнее см. в разделе Импорт отчетов из инструментов безопасности).
12. Дождитесь завершения обработки отчета.

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

Назначение парсера на инструмент безопасности

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

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

1. Создайте новую интеграцию с инструментом безопасности. Подробнее см. в разделе Подключение интеграции с инструментом безопасности.
2. Выберите необходимый парсер из выпадающего списка Парсер.
3. Нажмите кнопку Создать.

Кроме того, можно перейти к назначению парсера на инструмент безопасности и при создании новой проверки безопасности:

1. Создайте новую проверку безопасности. Подробнее см. в разделе Создание новой проверки безопасности.
2. Нажмите иконку информации () возле выпадающего списка Парсер.
3. Нажмите кнопку Редактировать инструмент.
4. В открывшемся окне отредактируйте инструмент безопасности.
5. Нажмите кнопку Сохранить.

После назначения пользовательского парсера разбор отчетов полностью выполняется через назначенный JSONata-парсер.

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

warning

Предустановленные системные парсеры (отмечены тегом System во вкладке Парсеры) недоступны для редактирования и удаления. Пользователю доступен просмотр конфигурации системных парсеров или использование их в качестве шаблонов для создания своих парсеров.

Чтобы отредактировать парсер, выполните следующие шаги:

1. Перейдите в раздел Интеграции.
2. Нажмите кнопку Парсеры.
3. Нажмите кнопку дополнительных действий () возле необходимого парсера.
4. Выберите вариант Редактировать.
5. Измените данные парсера.
6. Нажмите кнопку Создать.

Внесенные изменения будут применены к парсеру.

Удаление одного или нескольких парсеров

Чтобы удалить один парсер, выполните следующие шаги:

1. Перейдите в раздел Интеграции.
2. Нажмите кнопку Парсеры.
3. Нажмите кнопку дополнительных действий () возле необходимого парсера.
4. Выберите вариант Удалить.
5. В открывшемся модальном окне подтвердите удаление парсера.

Парсер будет удален из системы и перестанет отображаться в списке парсеров в разделе Парсеры.

Чтобы удалить несколько парсеров, выполните следующие шаги:

1. Перейдите в раздел Интеграции.
2. Нажмите кнопку Парсеры.
3. Выберите необходимые парсеры с помощью чекбоксов ().
4. Нажмите кнопку удаления () над таблицей парсеров.
5. В открывшемся модальном окне подтвердите удаление парсеров.

Парсеры будут удалены из системы и перестанут отображаться в списке парсеров в разделе Парсеры.