Анализ кода с помощью запросов CodeQL

Сведения об анализе баз данных с помощью CodeQL CLI

Для анализа базы кода выполняется запросы к базе данных CodeQL, извлеченной из кода. Анализ CodeQL создает результаты, которые можно отправить в GitHub Enterprise Cloud для создания оповещений сканирования кода.

Необходимые компоненты

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

Настройте CodeQL CLI для локального выполнения команд.
Создайте базу данных CodeQL для исходного кода, который требуется проанализировать.

Самый простой способ выполнения codeql database analyze — использовать стандартные запросы, включенные в пакет CodeQL CLI.

Бег `codeql database analyze`

При выполнении выполните следующие действия database analyze:

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

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

codeql database analyze <database> --format=<format> --output=<output> <query-specifiers>...

Примечание. Если вы анализируете более одной базы данных CodeQL для одной фиксации, необходимо указать категорию SARIF для каждого набора результатов, создаваемых этой командой. При отправке результатов в GitHub Enterprise Cloud code scanning использует эту категорию для хранения результатов для каждого языка отдельно. Если вы забыли это сделать, то при каждой отправке будут перезаписаны предыдущие результаты.

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <packs,queries>

Необходимо указать <database>, --formatи --output. Можно указать дополнительные параметры в зависимости от того, какой анализ необходимо выполнить.

Вариант	Обязательное поле	Использование
`<database>`		Укажите путь к каталогу, содержащему базу данных CodeQL для анализа.
`<packs,queries>`		Укажите пакеты или запросы CodeQL для выполнения. Чтобы выполнить стандартные запросы, используемые для code scanning, опустите этот параметр. Чтобы просмотреть другие наборы запросов, включенные в пакет CodeQL CLI, выполните поиск в `/<extraction-root>/qlpacks/codeql/<language>-queries/codeql-suites`. Сведения о создании собственного набора запросов см. в документации по CodeQL CLI.
`--format`		Укажите формат файла результатов, созданного во время анализа. Поддерживаются несколько различных форматов, включая форматы CSV, SARIF и графа. Для отправки в GitHub это должно быть: `sarif-latest`. Дополнительные сведения см. в разделе Поддержка SARIF для проверки кода.
`--output`		Укажите расположение, в котором нужно сохранить файл результатов SARIF, включая требуемое имя файла с расширением `.sarif` .
`--sarif-category`		Необязательно для анализа отдельных баз данных. Требуется для определения языка при анализе нескольких баз данных для одной фиксации в репозитории. Укажите категорию для включения в файл результатов SARIF для этого анализа. Категория используется для различения нескольких анализов для одного и того же средства и фиксации, но для разных языков или различных частей кода.
`--sarif-add-baseline-file-info`		Рекомендуется. Используется для отправки сведений о охвате файла в Страница состояния средства. Дополнительные сведения см. в разделе Сведения о странице состояния средства для сканирования кода.
`--sarif-include-query-help`		Укажите, следует ли включать справку запроса в выходные данные SARIF. Одно из следующих. `always`Включение справки по запросу для всех запросов. `custom_queries_only` (по умолчанию): включите справку запроса только для пользовательских запросов, то есть запросов в пакетах запросов, которые не относятся к форме `codeql/<lang>-queries`. `never`: не включать справку по запросу для каких-либо запросов. Любая справка по запросу для пользовательских запросов, включенных в выходные данные SARIF, будет отображаться в любом оповещении сканирования кода для запроса. Дополнительные сведения см. в разделе Использование пользовательских запросов с интерфейсом командной строки CodeQL.
`<packs>`		Используйте, если вы хотите включить в анализ пакеты запросов CodeQL. Дополнительные сведения см. в разделе Скачивание и использование пакетов данных CodeQL.
`--download`		Используйте, если некоторые из ваших пакетов запросов CodeQL еще не находятся на диске и необходимо скачать перед выполнением запросов.
`--threads`		Используйте, если требуется использовать более одного потока для выполнения запросов. Значение по умолчанию — `1`. Можно указать больше потоков для ускорения выполнения запросов. Чтобы задать число потоков, равное числу логических процессоров, укажите `0`.
`--verbose`		Используйте для получения более подробных сведений о процессе анализа и диагностических данных из процесса создания базы данных.
`--threat-model`		(Public preview) Используйте для добавления моделей угроз для настройки дополнительных источников в анализе CodeQL . Во время public previewмодели угроз поддерживаются только анализом Java. Дополнительные сведения см. в разделе анализ базы данных.

Обновление баз данных

Для баз данных, созданных CodeQL CLI версии 2.3.3 или более ранних версий, необходимо явно обновить базу данных, прежде чем можно будет выполнить анализ с более новой версией CodeQL CLI. Если этот шаг необходим, вы увидите сообщение о необходимости обновления базы данных при запуске database analyze.

Для баз данных, созданных CodeQL CLI версии 2.3.4 или более поздней версии, интерфейс командной строки неявно выполнит все необходимые обновления. Явное выполнение команды обновления не требуется.

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

Базовый пример анализа базы данных CodeQL

В этом примере анализируется база данных CodeQL, хранящаяся в папке /codeql-dbs/example-repo, и результаты сохраняются в виде файла SARIF: /temp/example-repo-js.sarif. Он использует --sarif-category, чтобы включить в файл SARIF дополнительные сведения, определяющие результаты в виде JavaScript. Это критически важно при наличии нескольких баз данных CodeQL для анализа отдельной фиксации в репозитории.

$ codeql database analyze /codeql-dbs/example-repo \
    javascript-code-scanning.qls --sarif-category=javascript-typescript \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Running queries.
> Compiling query plan for /codeql-home/codeql/qlpacks/codeql-javascript/AngularJS/DisablingSce.ql.
...
> Shutting down query evaluator.
> Interpreting results.

Добавление сведений о охвате файлов в результаты мониторинга

При необходимости можно отправить сведения о охвате файла в GitHub Enterprise Cloud для отображения на Страница состояния средства для code scanning. Дополнительные сведения о охвате файлов см. в разделе "Сведения о странице состояния средства для сканирования кода".

Чтобы включить сведения о охвате файлов с результатами code scanning, добавьте --sarif-add-baseline-file-info флаг в codeql database analyze вызов в систему CI, например:

$ codeql database analyze /codeql-dbs/example-repo \
    javascript-code-scanning.qls --sarif-category=javascript-typescript \
    --sarif-add-baseline-file-info \ --format=sarif-latest \
    --output=/temp/example-repo-js.sarif

Примеры выполнения анализа базы данных

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

Выполнение пакета запросов CodeQL

Чтобы запустить существующий пакет запросов CodeQL из GitHub Container registry, можно указать одно или несколько имен пакетов:

codeql database analyze <database> microsoft/coding-standards@1.0.0 github/security-queries --format=sarifv2.1.0 --output=query-results.sarif --download

Эта команда запускает набор запросов по умолчанию из двух пакетов запросов CodeQL: microsoft/coding-standards версии 1.0.0 и последней версии указанной github/security-queries базы данных. Дополнительные сведения о наборах по умолчанию см. в разделе "Публикация и использование пакетов CodeQL".

Флаг --download необязателен. С его помощью пакет запросов будет скачан, если он еще недоступен локально.

Выполнение одного запроса

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

codeql database analyze --download <javascript-database> codeql/javascript-queries:Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv

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

Анализ создает CSV-файл (js-results.csv) в новом каталоге (js-analysis).

Кроме того, если у вас есть репозиторий CodeQL , можно выполнить те же запросы, указав путь к запросу напрямую:

codeql database analyze <javascript-database> ../ql/javascript/ql/src/Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv

Вы также можете выполнять собственные пользовательские запросы с database analyze помощью команды. Дополнительные сведения о подготовке запросов к использованию с CodeQL CLIсм. в разделе "Использование пользовательских запросов с интерфейсом командной строки CodeQL".

Выполнение всех запросов в каталоге

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

Важно!

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

Например, чтобы выполнить все запросы Python, содержащиеся в каталоге Functions в пакете codeql/python-queries запросов, выполните следующее:

codeql database analyze <python-database> codeql/python-queries:Functions --format=sarif-latest --output=python-analysis/python-results.sarif --download

Кроме того, если у вас есть репозиторий CodeQL, можно выполнить те же запросы, указав путь к каталогу напрямую:

codeql database analyze <python-database> ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif

По завершении анализа создается файл результатов SARIF. Указание --format=sarif-latest гарантирует форматирование результатов в соответствии с последней спецификацией SARIF, поддерживаемой CodeQL.

Выполнение подмножества запросов в пакете CodeQL

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

Полный способ указать набор запросов находится в форме scope/name@range:path, где:

scope/name — это полное имя пакета CodeQL.
range— это диапазон semver.
path — это путь к одному запросу, каталогу с запросами или файлу набора запросов.

При указании scope/nameзначения range и path необязательными. Если опущена range последняя версия указанного пакета, используется. Если не указано, path используется набор запросов по умолчанию указанного пакета.

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

Если указать и scope/name path, то path не может быть абсолютным. Он считается относительным к корню пакета CodeQL .

Для анализа базы данных с помощью всех запросов в папке experimental/Security в пакете codeql/cpp-queries CodeQL можно использовать следующее:

codeql database analyze --format=sarif-latest --output=results <db> \
    codeql/cpp-queries:experimental/Security

Для выполнения RedundantNullCheckParam.ql запроса в пакете codeql/cpp-queries CodeQL используется:

codeql database analyze --format=sarif-latest --output=results <db> \
    'codeql/cpp-queries:experimental/Likely Bugs/RedundantNullCheckParam.ql'

Для анализа базы данных с помощью cpp-security-and-quality.qls набора запросов из версии codeql/cpp-queries пакета CodeQL >= 0.0.3 и < 0.1.0 (будет выбрана самая совместимая версия) можно использовать:

codeql database analyze --format=sarif-latest --output=results <db> \
   'codeql/cpp-queries@~0.0.3:codeql-suites/cpp-security-and-quality.qls'

Если вам нужно ссылаться на файл запроса, каталог или набор, путь которого содержит литерал @ или :можно префиксировать спецификацию запроса следующим path: образом:

codeql database analyze --format=sarif-latest --output=results <db> \
    path:C:/Users/ci/workspace@2/security/query.ql

Дополнительные сведения о пакетах CodeQL см. в разделе Настройка анализа с помощью пакетов CodeQL.

Выполнение наборов запросов

Чтобы запустить набор запросов в базе данных CodeQL для базы кода C/C++, можно использовать следующую команду из каталога, содержащего базу данных:

codeql database analyze <cpp-database> codeql/cpp-queries:codeql-suites/cpp-code-scanning.qls --format=sarifv2.1.0 --output=cpp-results.sarif --download

Эта команда скачивает codeql/cpp-queries пакет запросов CodeQL, запускает анализ и создает файл в формате SARIF версии 2.1.0, который поддерживается всеми версиями GitHub. Этот файл можно отправить в GitHub путем codeql github upload-results выполнения или API сканирования кода. Дополнительные сведения см. в разделе "[AUTOTITLE" илиОтправка результатов анализа CodeQL в GitHub](/rest/code-scanning)".

Наборы запросов CodeQL — это .qls файлы, использующие директивы для выбора запросов для выполнения на основе определенных свойств метаданных. Стандартные пакеты данных CodeQL имеют метаданные, которые указывают расположение наборов запросов, используемых сканированием кода, поэтому CodeQL CLI знает, где находить эти файлы набора автоматически, и вам не нужно указывать полный путь в командной строке. Дополнительные сведения см. в разделе Создание наборов запросов CodeQL.

Сведения о создании пользовательских наборов запросов см. в разделе "Создание наборов запросов CodeQL".

Включение пакетов моделей для добавления потенциальных источников запятнаемых данных

Примечание. Модели угроз в настоящее время находятся в public preview и подвергаются изменению. Во время public previewмодели угроз поддерживаются только анализом для Java/Kotlin.

Модели угроз можно настроить в анализе code scanning. Дополнительные сведения см. в статьях "Модели угроз для Java и Kotlin" и "Модели угроз для C#" в документации по CodeQL.

$ codeql database analyze /codeql-dbs/my-company --format=sarif-latest \
  --threat-model=local \
  --output=/temp/my-company.sarif codeql/java-queries

В этом примере соответствующие запросы в стандартном пакете codeql/java-queries запросов будут использовать local модель угроз, а также модель угроз по умолчанию для remote источников потока данных. Модель угроз следует использовать local при рассмотрении данных из локальных источников (например, файловых систем, аргументов командной строки, баз данных и переменных среды), чтобы быть потенциальными источниками ненамерованных данных для базы кода.

Результаты

Результаты анализа можно сохранить в нескольких различных форматах, включая SARIF и CSV.

Формат SARIF предназначен для представления выходных данных широкого спектра статических средств анализа. Дополнительные сведения см. в разделе Выходные данные CODEQL CLI SARIF.

Дополнительные сведения о том, как выглядят результаты в формате CSV, см. в разделе "Выходные данные CLI CLI CodeQL".

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

Просмотр журналов и сведений по диагностике

При анализе базы данных CodeQL с помощью набора запросов code scanning в дополнение к созданию подробной информации об оповещениях интерфейс командной строки сообщает диагностические данные с этапа создания базы данных и сводные метрики. Если вы решили создать выходные данные SARIF, дополнительные данные также включаются в ФАЙЛ SARIF. Для репозиториев с небольшим количеством предупреждений эта информация может оказаться полезной для определения того, действительно ли в коде мало проблем или возникали ли ошибки при создании базы данных CodeQL. Для более подробного вывода из codeql database analyze используйте параметр --verbose.

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

Вы можете экспортировать и отправить диагностические сведения в GitHub Enterprise Cloud даже в случае сбоя анализа CodeQL . Дополнительные сведения см. в разделе Отправка результатов анализа CodeQL в GitHub.

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

Сведения о передаче результатов анализа CodeQL в GitHub Enterprise Cloud, см. в разделе "Отправка результатов анализа CodeQL в GitHub".