Выходные данные SARIF codeQL CLI

Сведения о выходных данных SARIF

SARIF предназначен для представления выходных данных широкого спектра средств статического анализа, и в спецификации SARIF есть много функций, которые считаются необязательными. В этом документе подробно описаны выходные данные, полученные при использовании типа sarifv2.1.0формата , который соответствует спецификации SARIF версии 2.1.0.csd1. Дополнительные сведения о выборе формата файла для результатов анализа см. в разделе Команда анализа базы данных в документации по CodeQL.

Спецификация и схема SARIF

Эта статья предназначена для ознакомления с подробной спецификацией SARIF. Дополнительные сведения о спецификации и схеме SARIF см. в документации по спецификации SARIF.

Заметки об изменениях

Изменения между версиями

Версия CodeQL	Тип формата	Изменения
2.0.0	sarifv2.1.0	Первая версия этого формата.

Будущие изменения выходных данных

Выходные данные, созданные для определенного типа формата (например, sarifv2.1.0), могут измениться в будущих выпусках CodeQL. Мы будем стремиться поддерживать обратную совместимость с потребителями созданного SARIF, обеспечивая следующее:

• Поле, помеченное как "Всегда", не будет удалено.

• Условия, при которых создаются поля Optional, могут измениться. Потребители выходных данных CodeQL SARIF должны быть устойчивыми к наличию или отсутствию этих полей.

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

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

Созданные объекты SARIF

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

Объект sarifLog.

Имя свойства JSON	Когда он создается?	Примечания
$schema	Всегда	Предоставляет ссылку на схему SARIF.
version	Всегда	Версия SARIF, используемая для создания выходных данных.
runs	Всегда	Массив, содержащий один объект запуска для одного языка.

Объект run.

Имя свойства JSON	Когда он создается?	Примечания
tool	Всегда	–
originalUriBaseIds	Всегда	Словарь uriBaseIds для artifactLocations, представляющий исходные расположения на компьютере для анализа. Как минимум он будет содержать %SRCROOT% uriBaseId, который представляет корневое расположение на компьютере анализа исходного кода для проанализированного проекта. Каждый из них artifactLocation будет содержать uri свойства и description .
artifacts	Всегда	Массив, содержащий по крайней мере один объект артефакта для каждого файла, на который ссылается результат.
results	Всегда	–
newLineSequences	Всегда	–
columnKind	Всегда	–
properties	Всегда	Словарь свойств будет содержать semmle.formatSpecifier, который определяет описатель формата, переданный в CodeQL CLI.

Объект tool.

Имя свойства JSON	Когда он создается?	Примечания
driver	Всегда	–

Объект toolComponent.

Имя свойства JSON	Когда он создается?	Примечания
name	Всегда	Задайте для параметра CodeQL цепочку инструментов командной строки для выходных данных средств CodeQL CLI. Обратите внимание, что если выходные данные были созданы с помощью другого средства, отображается другой name формат, а формат может отличаться от описанного здесь.
organization	Всегда	Задайте значение GitHub.
version	Всегда	Задайте версию выпуска CodeQL, например 2.0.0.
rules	Всегда	Массив объектов reportingDescriptor, представляющих правила. Этот массив будет содержать как минимум все правила, которые были запущены во время этого анализа, но может содержать правила, которые были доступны, но не были запущены. Дополнительные сведения о включении запросов см. в разделе defaultConfiguration.

reportingDescriptor object (для правила)

reportingDescriptor Объекты могут использоваться в нескольких местах в спецификации SARIF. reportingDescriptor При включении в массив toolComponent правил объекта он имеет следующие свойства.

Имя свойства JSON	Когда он создается?	Примечания
id	Всегда	Будет содержать свойство, указанное @id в запросе, определяющее правило, которое обычно имеет формат language/rule-name (например cpp/unsafe-format-string, ). Если ваша организация определяет @opaqueid свойство в запросе, оно будет использоваться вместо него.
name	Всегда	Будет содержать свойство, @id указанное в запросе. Пример см. в описании id свойства выше.
shortDescription	Всегда	Будет содержать свойство, @name указанное в запросе, определяющем правило.
fullDescription	Всегда	Будет содержать свойство, @description указанное в запросе, определяющем правило.
defaultConfiguration	Всегда	Объект reportingConfiguration с включенным свойством true или false и свойством уровня, заданным в соответствии со @severity свойством, указанным в запросе, определяющем правило. Опущен, если @severity свойство не указано.

Объект artifact.

Имя свойства JSON	Когда он создается?	Примечания
location	Всегда	Объект artifactLocation.
index	Всегда	Индекс объекта artifact.
contents	Дополнительно	Если результаты создаются с помощью флага --sarif-add-file-contents и исходный код доступен во время создания ФАЙЛА SARIF, свойство contents заполняется объектом с заданным свойством artifactContent text .

Объект artifactLocation.

Имя свойства JSON	Когда это создается?	Примечания
uri	Всегда	–
index	Всегда	–
uriBaseId	Дополнительно	Если файл относится к известному абстрактному расположению, например корневому исходному расположению на компьютере для анализа, он будет задан.

Объект result.

Состав результатов зависит от параметров, предоставляемых CodeQL. По умолчанию результаты группируются по уникальной строке сообщения и основному расположению. Таким образом, два результата, которые происходят в одном расположении с одним и тем же базовым сообщением, будут отображаться в виде одного результата в выходных данных. Это поведение можно отключить с помощью флага --ungroup-results, в этом случае результаты не группируются.

Имя свойства JSON	Когда это создается?	Примечания
ruleId	Всегда	См. описание свойства в reportingDescriptor объекте id (для правила).
ruleIndex	Всегда	–
message	Всегда	Сообщение с описанием проблем, возникающих в этом расположении. Это сообщение может быть сообщением SARIF "Сообщение с заполнителем", содержащим ссылки, ссылающиеся на расположения в свойстве relatedLocations .
locations	Всегда	Массив, содержащий один location объект.
partialFingerprints	Всегда	Словарь от именованных типов отпечатков до отпечатка. Он будет содержать как минимум значение для primaryLocationLineHash, которое предоставляет отпечаток на основе контекста основного расположения.
codeFlows	Дополнительно	Этот массив может быть заполнен одним или несколькими codeFlow объектами, если запрос, определяющий правило для этого результата, имеет значение @kind path-problem.
relatedLocations	Дополнительно	Этот массив будет заполнен, если запрос, определяющий правило для этого результата, содержит сообщение с параметрами заполнителей. Каждое уникальное расположение включается один раз.
suppressions	Дополнительно	Если результат подавляется, он будет содержать один suppression объект со свойством @kind , равным IN_SOURCE. Если этот результат не подавляется, но есть хотя бы один результат с подавлением, то для него будет задан пустой массив, в противном случае он не будет задан.

Объект location.

Имя свойства JSON	Когда это создается?	Примечания
physicalLocation	Всегда	–
id	Дополнительно	location Объекты, которые отображаются в массиве relatedLocations result объекта , могут содержать id свойство .
message	Дополнительно	location Объекты могут содержать свойство , message если: — Они отображаются в массиве relatedLocations result объекта , могут содержать message свойство . — Они отображаются в свойстве threadFlowLocation.location .

Объект physicalLocation.

Имя свойства JSON	Когда это создается?	Примечания
artifactLocation	Всегда	–
region	Дополнительно	Если данный объект physicalLocation существует в текстовом файле, например в файле исходного region кода, свойство может присутствовать.
contextRegion	Дополнительно	Может присутствовать, если в этом расположении есть связанный snippetобъект .

Объект region.

Существует два типа объектов, создаваемых region CodeQL:

• Области смещения строк и столбцов

• Области смещения и длины символов

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

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

Имя свойства JSON	Когда это создается?	Примечания
startLine	Всегда	–
startColumn	Дополнительно	Не включается, если равно значению по умолчанию 1.
endLine	Дополнительно	Не включается, если он идентичен startLine.
endColumn	Всегда	–
snippet	Дополнительно	–

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

Имя свойства JSON	Когда это создается?	Примечания
charOffset	Дополнительно	Предоставляется, если startLineне заполнены , startColumn, endLine, и endColumn .
charLength	Дополнительно	Предоставляется, если startLineне заполнены , startColumn, endLine, и endColumn .
snippet	Дополнительно	–

Объект codeFlow.

Имя свойства JSON	Когда это создается?	Примечания
threadFlows	Всегда	–

Объект threadFlow.

Имя свойства JSON	Когда это создается?	Примечания
locations	Всегда	–

Объект threadFlowLocation.

Имя свойства JSON	Когда это создается?	Примечания
location	Всегда	–