Примечание: Эта статья была перенесена с веб-сайта документации CodeQL в январе 2023 г.
Сведения о выходных данных 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, обеспечивая следующее:
-
Поля, помеченные как всегда создаваемые, никогда не будут удалены.
-
Для полей, помеченных как не всегда создаваемые, обстоятельства, при которых создаются поля, могут измениться. Потребители выходных данных 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 | Нет |