Действия с парсерами
Конструктор парсеров в TRON.ASOC позволяет создавать, редактировать, применять и удалять парсеры — пользовательские схемы разбора SARIF/JSON-отчетов для интеграции с системой.
Конструктор основан на языке запросов и трансформации данных JSONata. Синтаксис JSONata поддерживает логические операторы, поиск по массивам, маппинг значений и частичные совпадения.
Движок TRON.ASOC реализует ограниченное подмножество JSONata, а семантика части операторов отличается от эталонной реализации языка. Перечень поддерживаемых выражений, доступных функций и расхождений с эталонной реализацией приведен в разделе Конфигурация пользовательского парсера.
Подробнее о JSONata см. в официальной документации.
Сторонний инструмент проверки можно использовать, чтобы проверить пути к полям на примере отчета. Логику выражений проверяйте средствами TRON.ASOC: результат в стороннем инструменте не гарантирует такого же результата в системе.
При сохранении парсера система проверяет корректность введенного JSON и синтаксис JSONata-выражений. Успешное сохранение парсера не означает, что выражения вернут ожидаемые значения на конкретном отчете.
Для работы с парсерами пользователь должен иметь следующие права доступа:
- Просмотр парсеров;
- Создание/редактирование парсеров;
- Удаление парсеров.
Поля маппинга
В JSON-схеме парсера разрешено использовать только предопределенный набор полей, соответствующих модели TRON.ASOC. При использовании полей важен корректный регистр. Поля, отсутствующие в таблице, игнорируются.
Каждое поле заполняется выражением JSONata, которое возвращает значение из отчета. Значения всех полей передаются строками.
| Поле TRON.ASOC | Поле в парсере | Назначение и особенности заполнения |
|---|---|---|
| Категория | category | Категория уязвимости |
| Критичность | severity | Уровень критичности — число от -1 до 4.Инструмент безопасности может передавать уровень критичности в любом виде: задача конфигурации — привести его к этой шкале. Значения critical, high, medium и low приводятся к шкале без маппинга. Остальные значения (в том числе info, none, note, warning, error) следует приводить к шкале через $lookup. Значение уровня, отсутствующее в таблице $lookup, оставляет поле пустым |
| CWE | cwe | Идентификатор CWE в формате CWE-XX.В одной находке может быть несколько идентификаторов CWE |
| CVE | cve | Идентификатор CVE в формате CVE-ГГГГ-ЧЧЧЧ.В одной находке может быть только один идентификатор CVE |
| Исходный файл | source_file | Путь к файлу, содержащему уязвимость |
| Строка | line | Номер строки в коде |
| Название библиотеки | lib_name | Имя библиотеки (для SCA) |
| Версия библиотеки | lib_version | Версия библиотеки |
| Объект | 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 | Оценка эксплуатируемости уязвимости |
| Элементы кода | code_elements | Структурированные элементы кода. Формируется кодовым адаптером на стороне сервера для ESLint, GitLab SAST и PT AI/SASTAV, из пользовательского парсера не заполняется. Для остальных инструментов безопасности недоступно |
| Описание | description | Данные находки, которым нет соответствия в полях выше, размещаются во вложенном объекте description.details — см. строки ниже |
| — | description.details.info | Краткое описание находки |
| — | description.details.detailedInfo | Полное описание уязвимости |
| — | description.details.recommendations | Рекомендации по устранению |
| — | description.details.refs | Ссылки на источники |
| — | description.details.ratings | Оценки и векторы CVSS в виде JSON-строки |
| — | description.details.message | Классификации инструмента безопасности (OWASP, SANS, PCI DSS, NIST) |
| — | description.details.path | Трасса распространения данных |
| — | description.details.query | Имя правила или функции, в которой обнаружена уязвимость |
| — | description.details.matchDetails | Дополнительные условия срабатывания правила |
| — | description.details.platform | Язык или платформа уязвимого кода |
| — | description.details.hash | Собственный идентификатор находки в отчете инструмента безопасности |
Поле code_elements формируется кодовым адаптером на стороне сервера для инструментов безопасности ESLint, GitLab SAST и PT AI/SASTAV. Из пользовательского парсера это поле не заполняется: выражение JSONata, возвращающее вложенную структуру элементов кода, составить нельзя.
Для остальных инструментов безопасности поле code_elements недоступно. Если отчет содержит данные об элементах кода, их можно передать текстом в одно из полей description.details.
Каждое поле заполняется выражением JSONata, которое возвращает значение из отчета. Доступные выражения представлены в таблице ниже.
| Тип выражения | Синтаксис | Пример |
|---|---|---|
| Прямой путь | a.b.c | locations[0].physicalLocation.artifactLocation.uri |
| Индекс элемента | a[0] | cvss[0].score |
| Разворот массива | a[].b | Results[].Vulnerabilities |
| Фильтр по значению | a[field = "value"] | cvss[version = "CVSS_V3"].score |
| Частичное совпадение | a[$ ~> /regex/] | tags[$ ~> /CWE/] |
| Fallback-выражение | expr1 or expr2 | numberLine or beginLine |
| Тернарный оператор | cond ? expr1 : expr2 | cweId != "" ? (\"CWE-\" & cweId) : \"\" |
| Конкатенация | expr1 & expr2 | type.displayName & ": " & summary |
| Маппинг значений | $lookup({...}, expr) | $lookup({\"high\":\"3\"}, severity) |
Оператор or в конструкторе парсеров работает не как логическое ИЛИ, а как fallback-выражение: он возвращает первое непустое значение, а не true. Это отличается от поведения оператора в эталонной реализации JSONata и в стороннем инструменте проверки.
Тернарный оператор не применяет ветку «иначе», если поля из условия нет в находке, в результате поле останется пустым. Для необязательных полей используйте fallback-выражение or.
Полный перечень отличий приведен в разделе Конфигурация пользовательского парсера.
Секции парсера
Конфигурация парсера поддерживает поле 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": "..." }
]
}
items_path — путь к массиву находок в отчете. Остальные выражения секции вычисляются относительно отдельного элемента этого массива, а не относительно корня отчета. Правила записи пути, доступ к полям родительского объекта и другие особенности секций описаны в разделе Конфигурация пользовательского парсера.
Ограничения конструктора парсеров
Для полей, формируемых на основе описания правила SARIF (например, category, cwe), соответствие между найденной проблемой и описанием правила определяется по позиционному индексу правила (ruleIndex), если он присутствует в отчете. Кодовый парсер того же инструмента безопасности сопоставляет их по строковому идентификатору правила (ruleId).
На корректно сформированных отчетах оба способа дают одинаковый результат. Если в отчете ruleIndex указывает не на то правило (ошибка конкретного инструмента), пользовательский парсер и предустановленный кодовый парсер того же инструмента могут вернуть разные данные для одной и той же находки.
Прочие ограничения конструктора — неподдерживаемые конструкции языка, ограничения на длину значений полей, схлопывание находок по составному ключу — описаны в разделе Конфигурация пользовательского парсера.
Создание нового парсера
Чтобы создать новый парсер, выполните следующие шаги:
-
Перейдите в раздел Интеграции.
-
Нажмите кнопку Парсеры.
-
В открывшемся разделе Парсеры нажмите кнопку Добавить парсер.
Рисунок 1 — Список парсеров
-
В окне добавления нового парсера введите следующие данные:
- название парсера;
- описание парсера;
- конфигурация парсера в формате JSON.
-
Нажмите кнопку Создать.
Рисунок 2 — Создание нового парсера
Новый парсер будет отображаться в списке парсеров в разделе Парсеры.
Пример парсера
Ниже представлен пример минимального парсера, предназначенного для извлечения уровня критичности уязвимости и пути к файлу с уязвимостью:
{
"items_path": "runs[0].results",
"severity": "$lookup({\"error\": \"4\", \"warning\": \"2\", \"note\": \"1\", \"none\": \"-1\"}, level)",
"source_file": "locations[0].physicalLocation.artifactLocation.uri"
}
items_path задает массив находок, а выражения полей вычисляются относительно отдельной находки этого массива. Выражения вида runs[0].results[0].level обращаются только к первой находке отчета и для пользовательских парсеров не применяются.
Создание нового парсера на основе имеющегося
Чтобы создать новый парсер на основе имеющегося, выполните следующие шаги:
- Перейдите в раздел Интеграции.
- Нажмите кнопку Парсеры.
- Нажмите кнопку дополнительных действий (
) возле необходимого парсера. - Выберите вариант Использовать как шаблон.
- В окне добавления нового парсера введите следующие данные:
- название парсера;
- описание парсера;
- конфигурация парсера в формате JSON.
- Нажмите кнопку Создать.
Новый парсер будет отображаться в списке парсеров в разделе Парсеры.
При создании парсера на основе имеющегося копируется JSON-схема исходного парсера в текущем виде.
Если за основу взять один из предустановленных SARIF-парсеров (например, SARIF: General), учитывайте, что пока на инструменте безопасности оставлен предустановленный парсер, разбор выполняется его кодовым (Go) аналогом, а не JSONata-конфигом. Соответствие между ними подтверждается автотестами эквивалентности, но это не гарантирует, что скопированная схема покрывает все нюансы поведения кодового парсера. После назначения пользовательского парсера разбор выполняется по его конфигурации.
Создание парсера для инструмента безопасности, не поддерживаемого TRON.ASOC
Если инструмент безопасности не поддерживается системой, результаты сканирования этим инструментом все равно можно загрузить и обработать системой. Для этого создайте парсер с маппингом полей отчета в формате JSONata. После настройки отчеты такого инструмента обрабатываются так же, как отчеты поддерживаемых инструментов, а уязвимости отображаются в результатах проверки безопасности.
Чтобы создать парсер для неподдерживаемого инструмента безопасности, выполните следующие шаги:
- Получите пример отчета от подключаемого инструмента в формате JSON или SARIF.
- Составьте конфигурацию парсера (маппинг полей отчета в формате JSONata). Подробнее о синтаксисе конфигурации, доступных функциях и ограничениях см. раздел Конфигурация пользовательского парсера.
- Создайте новый парсер (подробнее см. раздел Создание нового парсера).
- Создайте новую интеграцию с инструментом безопасности для импорта результатов. Подробнее об этом см. раздел Подключение интеграции с пользовательским инструментом безопасности (кастомной интеграции).
- При настройке новой интеграции выберите парсер, созданный на шаге 3.
- Перейдите в необходимый проект в разделе Проекты.
- Выберите слой, в котором будет выполняться проверка, либо создайте новый (подробнее см. в разделах Создание слоя с нуля и Создание слоя по шаблону).
- Создайте новую проверку безопасности в слое (подробнее см. раздел Создание проверки безопасности).
- Выберите инструмент, созданный на шаге 4.
- Выберите источник сканирования или создайте новую интеграцию с источником (подробнее см. раздел Подключение интеграции с источником сканирования).
- Импортируйте пример отчета от подключаемого инструмента безопасности (подробнее см. раздел Импорт отчетов из инструментов безопасности).
- Дождитесь завершения обработки отчета.
После завершения обработки статус проверки безопасности изменится на Выполнено, а найденные уязвимости будут отображаться в результатах сканирования.
Эта же последовательность действий используется для проверки конфигурации парсера: отдельного режима проверки конфигурации на образце отчета в системе нет. Результат разбора виден после импорта отчета — по составу найденных уязвимостей и заполненности их полей.
Чтобы не смешивать проверочные запуски с рабочими данными, выполняйте проверку в отдельном слое или отдельной проверке безопасности.
Назначение парсера на инструмент безопасности
При создании новой интеграции на выбранный инструмент безопасности назначается системный парсер, соответствующий типу инструмента, однако при создании или редактировании инструмента безопасности можно назначить и другой парсер (системный или пользовательский).
Чтобы назначить парсер на инструмент безопасности, выполните следующие шаги:
- Создайте новую интеграцию с инструментом безопасности. Подробнее см. раздел Подключение интеграции с инструментом безопасности.
- Выберите необходимый парсер из раскрывающегося списка Парсер.
- Нажмите кнопку Создать.
Кроме того, можно перейти к назначению парсера на инструмент безопасности и при создании новой проверки безопасности:
- Создайте новую проверку безопасности. Подробнее см. раздел Создание новой проверки безопасности.
- Нажмите иконку информации (
) возле раскрывающегося списка Парсер. - Нажмите кнопку Редактировать инструмент.
- В открывшемся окне отредактируйте инструмент безопасности.
- Нажмите кнопку Сохранить.
Назначенный пользовательский парсер имеет приоритет над предустановленным парсером инструмента безопасности: если на инструмент назначен пользовательский парсер, разбор отчетов выполняется через него. Это относится и к инструментам с предустановленным SARIF-парсером — для них также можно создать и назначить пользовательский SARIF-парсер.
Если инструмент безопасности возвращает 0 уязвимостей при заведомо непустом отчете, проверьте, какой парсер назначен инструменту в его настройках. Отчет разбирается назначенным парсером независимо от того, какой парсер редактировался последним.
Редактирование парсера
Предустановленные системные парсеры (отмечены тегом System во вкладке Парсеры) недоступны для редактирования и удаления. Пользователю доступен просмотр конфигурации системных парсеров или использование их в качестве шаблонов для создания своих парсеров.
Чтобы отредактировать парсер, выполните следующие шаги:
- Перейдите в раздел Интеграции.
- Нажмите кнопку Парсеры.
- Нажмите кнопку дополнительных действий () возле необходимого парсера.
- Выберите вариант Редактировать.
- Измените данные парсера.
- Нажмите кнопку Сохранить.
Внесенные изменения будут применены к парсеру.
Изменение конфигурации парсера наследуется во все инструменты безопасности и проверки безопасности, где этот парсер используется, но применяется только к отчетам, обработанным после изменения. Ранее найденные уязвимости не пересчитываются: новые поля у них не появятся, а изменившиеся значения не обновятся.
Чтобы результаты разбора соответствовали новой конфигурации, обработайте отчет повторно. При повторной обработке уязвимости, которые обновленный парсер не находит, закрываются, а найденные заново объединяются с ранее найденными по совпадающему хешу.
Из этого следует, что некорректная конфигурация парсера приводит не только к отсутствию новых уязвимостей, но и к закрытию ранее найденных. Проверяйте конфигурацию на отдельном слое или отдельной проверке безопасности, прежде чем назначать парсер на инструмент безопасности с рабочими данными.
Удаление одного или нескольких парсеров
Чтобы удалить один парсер, выполните следующие шаги:
- Перейдите в раздел Интеграции.
- Нажмите кнопку Парсеры.
- Нажмите кнопку дополнительных действий () возле необходимого парсера.
- Выберите вариант Удалить.
- В открывшемся модальном окне подтвердите удаление парсера.
Рисунок 3 — Окно подтверждения удаления парсера
Парсер будет удален из системы и перестанет отображаться в списке парсеров в разделе Парсеры.
Чтобы удалить несколько парсеров, выполните следующие шаги:
- Перейдите в раздел Интеграции.
- Нажмите кнопку Парсеры.
- Выберите необходимые парсеры с помощью флажков (
). - Нажмите кнопку удаления (
) над таблицей парсеров. - В открывшемся модальном окне подтвердите удаление парсеров.
Рисунок 4 — Окно подтверждения удаления парсеров
Парсеры будут удалены из системы и перестанут отображаться в списке парсеров в разделе Парсеры.
Если удаляемый парсер назначен на инструмент безопасности, инструменту назначается предустановленный парсер, соответствующий его типу. Обработка отчетов такого инструмента продолжается по конфигурации предустановленного парсера.
Парсеры удаляются безвозвратно: восстановить удаленный парсер средствами системы нельзя.