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

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

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

Предпосылки

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

        [Настройте CodeQL CLI](/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli) для локального запуска команд.

        [Создайте CodeQL базу](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis) данных для исходного кода, который хотите проанализировать.

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

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

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

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

Вариант	Обязательно	Usage
`<database>`		Укажите путь к каталогу, в котором находится CodeQL база данных для анализа.
`<packs,queries>`		Укажите CodeQL пакеты или запросы для запуска. Чтобы выполнить стандартные запросы, используемые для code scanning, опустите этот параметр. Чтобы увидеть другие наборы запросов, включённые в CodeQL CLI пакет, запустите `codeql resolve queries`. Перечисленные наборы могут быть предоставлены с расширением или без нее `.qls` . Для получения информации о создании собственного набора запросов см. Создание наборов запросов CodeQL в документации для CodeQL CLI.
`--format`		Укажите формат файла результатов, созданного во время анализа. Поддерживаются несколько различных форматов, включая форматы CSV, SARIF и графа. Для загрузки в GitHub это должно быть следующее:`sarifv2.1.0` . Дополнительные сведения см. в разделе Поддержка SARIF для проверки кода.
`--output`		Укажите расположение, в котором нужно сохранить файл результатов SARIF, включая требуемое имя файла с расширением `.sarif` .
`--sarif-category`		Необязательно для анализа отдельных баз данных. Требуется для определения языка при анализе нескольких баз данных для одной фиксации в репозитории. Укажите категорию для включения в файл результатов SARIF для этого анализа. Категория используется для различения нескольких анализов для одного и того же средства и фиксации, но для разных языков или различных частей кода.
`--sarif-add-baseline-file-info`

          **Рекомендуется**. Используйте для отправки информации о покрытии файла в Страница состояния средства. Дополнительные сведения см. в разделе [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page#how-codeql-defines-scanned-files). |

| --sarif-include-query-help | | Укажите, следует ли включать справку запроса в выходные данные SARIF. Одно из следующих. alwaysВключение справки по запросу для всех запросов. custom_queries_only (по умолчанию): включите справку запроса только для пользовательских запросов, то есть запросов в пакетах запросов, которые не относятся к форме codeql/<lang>-queries. never: не включать справку по запросу для каких-либо запросов. Любая справка по запросу для пользовательских запросов, включенных в выходные данные SARIF, будет отображаться в любом оповещении сканирования кода для запроса. Дополнительные сведения см. в разделе Написание пользовательских запросов для CodeQL CLI. | | <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 или более поздней, CLI будет неявно выполнять все необходимые обновления. Явное выполнение команды обновления не требуется.

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

Базовый пример анализа 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 для отображения на Страница состояния средства для 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 пакет запросов из GitHubContainer 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 необязателен. С его помощью пакет запросов будет скачан, если он еще недоступен локально.

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

Чтобы выполнить один запрос по 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 CLI.

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

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

Внимание

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

Например, чтобы выполнить все 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`
        [— это диапазон](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges) semver.

        `path` — это путь к одному запросу, каталогу с запросами или файлу набора запросов.

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

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

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

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

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

Чтобы выполнить RedundantNullCheckParam.ql запрос в наборе codeql/cpp-queriesCodeQL , используйте следующее:

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

Для анализа вашей базы данных с помощью cpp-security-and-quality.qls пакета запросов из версии codeql/cpp-queriesCodeQL пакета >= 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-queriesCodeQL пакет запросов, запускает анализ и генерирует файл в формате SARIF версии 2.1.0, поддерживаемый всеми версиями .GitHub Этот файл можно загрузить GitHub с помощью запуска codeql github upload-results или API сканирования кода. Дополнительные сведения см. в разделе [AUTOTITLE или Загрузка результатов анализа CodeQL на GitHub](/rest/code-scanning/code-scanning).

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

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

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

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

Примечание.

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

Вы можете настроить модели угроз в 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 при рассмотрении данных из локальных источников (например, файловых систем, аргументов командной строки, баз данных и переменных среды), чтобы быть потенциальными источниками ненамерованных данных для базы кода.

Results

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

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

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

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

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

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

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

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

Дальнейшие шаги

Чтобы узнать, как загрузить результаты анализа CodeQL в GitHub, смотрите Загрузка результатов анализа CodeQL на GitHub.