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

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

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

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

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

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

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

Бег codeql database analyze

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

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

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

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

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

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

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

Базовый пример анализа базы данных 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=sarifv2.1.0 --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 Server для отображения на Страница состояния средства для 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=sarifv2.1.0 \
    --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".

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

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

Например, чтобы выполнить все запросы 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".

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

Модели угроз можно настроить в анализе 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 Server даже в случае сбоя анализа CodeQL . Дополнительные сведения см. в разделе Отправка результатов анализа CodeQL в GitHub.

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

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