Поделиться через

Выполнение анализа CodeQL в коде драйвера Windows

CodeQL — это мощный статический механизм анализа, который помогает разработчикам выявлять уязвимости безопасности и нарушения кода в исходном коде драйвера Windows. В этой статье объясняется, как с помощью анализа CodeQL создать файл проверки драйвера для сертификации программы совместимости оборудования Windows (WHCP).

В этой статье вы:

  • Установите соответствующую версию CodeQL.
  • Установите необходимые пакеты CodeQL и наборы запросов.
  • Запустите CodeQL, чтобы создать базу данных и проанализировать код.
  • Создайте файл проверки драйвера.

Выберите соответствующую версию CodeQL для драйвера

Замечание

Visual Studio (VS) 17.8 нарушает совместимость со старыми версиями CodeQL, используемыми в WHCP_21H2 и WHCP_22H2 ветвях. КодQL CLI версии 2.15.4 проверяется для использования с WHCP 21H2 и WHCP 22H2 при использовании Visual Studio 17.8 или более поздней версии. При использовании Visual Studio 17.7 или более ранней версии используйте версию 2.4.6 или версию 2.6.3. Для программы WHCP используйте версию Cli CodeQL и выпуск Windows, для который вы сертифицируются : версия 2.4.6, версия 2.6.3 или версия 2.15.4. Для общего использования с основной ветвью используйте CodeQL CLI версии 2.15.4.

Выберите вкладку для сценария:

Используйте эту матрицу для определения скачиваемых версий.

Релиз Windows Версия CLI CodeQL Версия пакета CodeQL для microsoft/windows-drivers codeql/cpp-queries версия пакета CodeQL Используемая ветвь
Windows Server 2022 2.4.6 или 2.15.4 1.0.13 (при использовании codeql 2.15.4) 0.9.0 (при использовании codeql 2.15.4) WHCP_21H2
Windows 11 2.4.6 или 2.15.4 1.0.13 (при использовании codeql 2.15.4) 0.9.0 (при использовании codeql 2.15.4) WHCP_21H2
Windows 11, версия 22H2 2.6.3 или 2.15.4 1.0.13 (при использовании codeql 2.15.4) 0.9.0 (при использовании codeql 2.15.4) WHCP_22H2
Windows 11 версии 23H2 2.6.3 или 2.15.4 1.0.13 (при использовании codeql 2.15.4) 0.9.0 (при использовании codeql 2.15.4) WHCP_22H2
Windows 11 версии 24H2 2.15.4 1.1.0 0.9.0 WHCP_24H2

Замечание

Версия пакета CodeQL не указана для CodeQL CLI 2.4.6 и 2.6.3, так как версии CodeQL позже версии 2.7.0 поддерживают пакеты CodeQL.

Скачивание и установка CodeQL

  1. Создайте каталог для хранения CodeQL. В этом примере используется C:\codeql-home\

    C:\> mkdir C:\codeql-home

  2. Ознакомьтесь с предыдущими таблицами, чтобы выбрать версию интерфейса командной строки CodeQL, используемую в соответствии с требуемой ветвью запросов драйвера Майкрософт. Если вы выполняете анализ в рамках программы WHCP, обратитесь к таблице для использования программы совместимости оборудования Windows, в противном случае используйте основную ветвь и 2.15.4. Использование другой версии может привести к несовместимости базы данных с библиотеками.

  3. Перейдите к выпуску двоичных файлов CLI CodeQL, связанному с предыдущими таблицами, и скачайте ZIP-файл в соответствии с архитектурой проекта. Например, для 64-разрядной версии Windowscodeql-win64.zip.

  4. Извлеките каталог CLI Codeql в только что созданный, например: *C:\codeql-home\codeql*.

  5. Убедитесь, что CodeQL установлен правильно, проверив версию:

     C:\codeql-home\codeql>codeql --version
 CodeQL command-line toolchain release 2.15.4.
 Copyright (C) 2019-2023 GitHub, Inc.
 Unpacked in: C:\codeql-home\codeql
     Analysis results depend critically on separately distributed query and
     extractor modules. To list modules that are visible to the toolchain,
     use 'codeql resolve qlpacks' and 'codeql resolve languages'.

Использование справки CodeQL

C:\codeql-home\codeql\>codeql --help
Usage: codeql <command> <argument>...
Create and query CodeQL databases, or work with the QL language.

GitHub makes this program freely available for the analysis of open-source software and certain other uses, but it is
not itself free software. Type codeql --license to see the license terms.

      --license              Show the license terms for the CodeQL toolchain.
Common options:
  -h, --help                 Show this help text.
  -v, --verbose              Incrementally increase the number of progress messages printed.
  -q, --quiet                Incrementally decrease the number of progress messages printed.
Some advanced options have been hidden; try --help -v for a fuller view.
Commands:
  query     Compile and execute QL code.
  bqrs      Get information from .bqrs files.
  database  Create, analyze and process CodeQL databases.
  dataset   [Plumbing] Work with raw QL datasets.
  test      Execute QL unit tests.
  resolve   [Deep plumbing] Helper commands to resolve disk locations etc.
  execute   [Deep plumbing] Low-level commands that need special JVM options.
  version   Show the version of the CodeQL toolchain.
  generate  Generate formatted QL documentation.

Для получения справки по определенной команде выполните команду< codeql >--help. Рассмотрим пример.

codeql create --help

Чтобы получить справку для вложенных команд, перечислите их иерархически, например

codeql create language --help

Установка пакетов CodeQL

Выберите вкладку для среды сборки:

Используйте эту процедуру, если вы используете Visual Studio 2022 17.8 или больше с WHCP_21H2 или WHCP_22H2 и CodeQL CLI версии 2.15.4.

Замечание

Если вы выполнили тесты CodeQL с более ранней версией CodeQL, удалите старый подмодул CodeQL, если у вас по-прежнему есть старая версия клонированного репозитория. CodeQL может попытаться использовать запросы в подмодуле по умолчанию, что может привести к ошибкам из-за несоответствия версий.

Скачивание пакетов запросов CodeQL

CodeQL представил пакеты CodeQL (пакеты CodeQL или пакеты запросов) в версии 2.7.0, устраняя необходимость клонировать репозиторий Windows-Driver-Developer-Supplemental-Tools для использования запросов для сертификации.

Замечание

Можно пропустить шаг 1, так как --download параметр скачивает все необходимые запросы позже при выполнении процесса анализа.

  1. Скачайте правильную версию пакета драйверов microsoft/windows из таблицы использования программы совместимости оборудования Windows . Укажите следующую @<version> команду.
C:\codeql-home\> codeql pack download microsoft/windows-drivers@<version>

Например, при использовании WHCP_24H2 выполните следующую команду, чтобы скачать пакет запросов windows-драйверов 1.1.0:

C:\codeql-home\> codeql pack download microsoft/windows-drivers@1.1.0

Используйте эту команду, чтобы скачать пакет запросов CodeQL cpp-querys версии 0.9.0.

C:\codeql-home\> codeql pack download codeql/cpp-queries@0.9.0

CodeQL устанавливает пакеты запросов в каталог по умолчанию:

C:\Users\<current user>\.codeql\packages\microsoft\windows-drivers\<downloaded version>\

Это важно

Не изменяйте каталог установки или не перемещайте установленный пакет запросов.

Скачивание наборов запросов драйвера Windows

Корпорация Майкрософт предоставляет два набора запросов для упрощения сквозного рабочего процесса разработчика драйвера. Набор windows_driver_recommended.qls — это супермножество всех запросов, которые корпорация Майкрософт считает ценными для разработчиков драйверов, а набор windows_driver_mustfix.qls содержит запросы, которые считаются "Must-Fix" для сертификации WHCP. windows_driver_mustfix.qls необходимо запустить и передать для передачи теста логотипа статических инструментов.

Скопируйте два файла набора запросов на https://github.com/microsoft/Windows-Driver-Developer-Supplemental-Tools/tree/main/suites локальный компьютер.

  • windows_driver_recommended.qls
  • windows_driver_mustfix.qls

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

Создание базы данных CodeQL

В этих примерах предполагается использование среды разработки Windows и расположение установки — C:\codeql-home, но можно использовать настройку, которая подходит вам. Ознакомьтесь с поддерживаемыми языками и платформами CodeQL для списка поддерживаемых компиляторов .

  1. Создайте каталог CodeQL для размещения создаваемых баз данных. Например: C:\codeql-home\database

    mkdir C:\codeql-home\databases

  2. Используйте команду CodeQL для создания базы данных с этими параметрами:

    • Первый параметр — это ссылка на каталог базы данных. Например, C:\codeql-home\databases\MyDriverDatabase. (Эта команда завершается ошибкой, если каталог уже существует.)
    • --language или -l задает язык или языки, в котором находится исходный код. Это может быть разделенный запятыми список, например [cpp, javascript].
    • --source или -s задает путь к исходному коду.
    • --command или -c задает команду сборки или путь к файлу сборки.
    codeql database create <database directory> --language=<language> --source=<path to source code> --command=<build command or path to build file>

Примеры

Пример одного драйвера.

C:\codeql-home\codeql> codeql database create D:\DriverDatabase --language=cpp --source-root=D:\Drivers\SingleDriver --command="msbuild /t:rebuild D:\Drivers\SingleDriver\SingleDriver.sln"

Пример нескольких драйверов.

C:\codeql-home\codeql> codeql database create D:\SampleDriversDatabase --language=cpp --source-root=D:\AllMyDrivers\SampleDrivers --command=D:\AllMyDrivers\SampleDrivers\BuildAllSampleDrivers.cmd

Дополнительные сведения или справку по команде database create см. в статье "Создание баз данных CodeQL " или справка по использованию CodeQL.

Выполнение анализа

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

  1. Используйте команду CodeQL для анализа базы данных с помощью следующих параметров:

    • первый параметр — это ссылка на каталог базы данных. Например, C:\codeql-home\databases\MyDriverDatabase. (Примечание. Эта команда завершается ошибкой, если каталог не существует.)
    • --download флаг сообщает CodeQL скачать зависимости перед выполнением запросов.
    • --format — это тип файла вывода. Возможные варианты: SARIF и CSV. (Для пользователей WHCP используется формат SARIF.)
    • --output — это путь к нужному выходному файлу, не забудьте включить формат в имя файла. (Эта команда завершается с ошибкой, если каталог еще не существует.)
    • Параметр описателя запросов — это разделенный пробелом список аргументов, которые могут включать:
      • Путь к файлу запроса
      • Путь к каталогу с файлами запросов
      • Путь к файлу набора запросов
      • имя пакета запросов CodeQL
    codeql database analyze --download <path to database> <path to query suite .qls file> --format=sarifv2.1.0 --output=<outputname>.sarif

    Пример:

    codeql database analyze --download D:\DriverDatabase suites/windows\_driver_recommended.qls --format=sarifv2.1.0 --output=D:\DriverAnalysis1.sarif

    Дополнительную информацию или справку по использованию команды database analyze см. в статьях «Анализ баз данных с помощью интерфейса командной строки CodeQL», «Использование пакета CodeQL для анализа базы данных CodeQL» или «Справка CodeQL».

Просмотр и интерпретация результатов

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

Формат обмена статическими результатами анализа (SARIF) — это формат типа JSON, используемый для совместного использования результатов статического анализа. Дополнительные сведения о стандарте в формате обмена результатами статического анализа OASIS (SARIF), о том, как CodeQL использует выходные данные SARIF и json схемы.

Существует несколько методов интерпретации результатов анализа, включая сортировку по объектам вручную. Ниже приведены некоторые из них:

  • Средство Microsoft Sarif Viewer (Web) имеет функционал, позволяющий перетаскивать файл SARIF в средство, а затем отображает результаты, классифицированные по правилу. Это очень быстрый и простой способ увидеть количество нарушений или наличие нарушений запросов, но менее просто найти сведения о исходном коде в стороне от номера строки. Обратите внимание, что страница не будет обновляться, если нет нарушений.

  • Средство просмотра Microsoft SARIF для Visual Studio отлично подходит для отображения результатов в Visual Studio для простого перехода от результатов к исходному коду.

  • Расширение SARIF для Visual Studio Code открывает панель предварительного просмотра и отображает все ошибки, предупреждения или проблемы, сообщаемые CodeQL. Чтобы отобразить файл Sarif в доступном для чтения формате, откройте файл в Visual Studio Code и выберите SHIFT-ALT-F.

Наиболее важным разделом файла SARIF является свойство Results в объекте Run. Каждый запрос будет иметь свойство Results со сведениями о обнаруженных нарушениях и местах его возникновения. Если нарушения не найдены, значение свойства будет пустым.

Запросы классифицируются с помощью таких состояний, как ошибка, предупреждение и проблема. Однако эта классификация отличается от того, как программа совместимости оборудования Windows и тест логотипа статических инструментов оценивают результаты. Любой драйвер с дефектами из любого запроса в наборе Must-Fix не пройдет тест логотипа статических инструментов и не пройдет сертификацию, независимо от классификации запросов в необработанном файле запроса (например, предупреждение).

Преобразование SARIF в формат журнала проверки драйвера (DVL)

Статическое средство проверки логотипа анализирует журнал проверки драйвера (DVL), который является скомпилированный результатом статического анализа CodeQL, выполняемого в исходном коде драйвера. Существует три способа преобразования ФАЙЛА SARIF в формат DVL: Visual Studio, MSBuild или из командной строки с помощью средства dvl.exe . Инструкции см. в разделе "Создание журнала проверки драйвера".

Дополнительные указания по тесту Static Tools Logo HLK и рекомендациям, где разместить файл DVL, можно найти в "Запуск теста Static Tools Logo".

Устранение неполадок

Если вы проходите сертификацию через WHCP, сначала убедитесь, что вы используете версию HLK, связанную с целевым релизом Windows, соответствующую ветвь в репозитории дополнительных средств разработчика драйверов Windows и соответствующую версию CodeQL CLI. Для матрицы совместимости выпусков HLK/Windows см. Windows Hardware Lab Kit, а для ветки репозитория дополнительных средств для разработчиков драйверов Windows/CodeQL CLI см. таблицу WHCP в разделе "Выбор версии CodeQL".

Ошибки и обходные пути

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

Используйте команду codeql version, чтобы отобразить версию exe-файла codeql.

C:\codeql-home\codeql\>codeql version
CodeQL command-line toolchain release 2.4.0.
Copyright (C) 2019-2020 GitHub, Inc.
Unpacked in: C:\codeql-home\codeql\
   Analysis results depend critically on separately distributed query and
   extractor modules. To list modules that are visible to the toolchain,
   use 'codeql resolve qlpacks' and 'codeql resolve languages'.

Команда обновления базы данных обновит базу данных. Имейте в виду, что это один способ обновления и не является обратимым. Дополнительные сведения см. в разделе об обновлении базы данных.

Необязательные процедуры

При необходимости можно отключить результаты CodeQL или запустить процедуры сборки и анализа в качестве события после сборки в Visual Studio.

Скрытие результатов CodeQL

CodeQL для драйверов поддерживает подавление результатов. Подавления в настоящее время предоставляются как удобство, чтобы помочь разработчикам упорядочивать проблемы и уменьшить шум, а не как способ обойти проверки Must-Fix. Они в настоящее время не влияют на создание журнала проверки драйвера или прохождение теста логотипа статических инструментов. Чтобы использовать подавление, необходимо запустить запрос DriverAlertSuppression.ql одновременно с другими запросами или наборами, которые вы хотите запустить. По умолчанию этот запрос включен при запуске наборов из ветки main/development на GitHub.

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

  • Known limitation: На данный момент нельзя совмещать #pragma(деактивировать) и #pragma(подавить) в одной строке.

Для проверок, которые являются новыми для CodeQL, подавляйте их, выполнив одно из двух действий:

  • Напишите заметку #pragma(suppress:the-rule-id-here) (без кавычки) в строке над нарушением, как и для анализа кода. Замените "the-rule-id-here" @id значением в метаданных запроса, которое можно просмотреть в верхней части файла.

  • Напишите комментарий на приведенной выше строке, состоящей из текста "lgtm[the-rule-id-here]" (минус кавычки). Вам потребуется выполнить стандартный запрос подавления оповещений C/C++ вместо запроса подавления оповещений драйвера.

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

Событие после сборки Visual Studio

Если вы создаете драйвер с помощью Visual Studio, можно настроить запросы CodeQL для запуска в качестве события после сборки.

В этом примере небольшой пакетный файл создается в целевом расположении и вызывается как событие после сборки. Дополнительные сведения о событиях сборки Visual Studio C++ см. в разделе "Указание событий сборки".

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

    ECHO ">>> Running CodeQL Security Rule V 1.0 <<<"
ECHO ">>> Removing previously created rules database <<<"
rmdir /s/q C:\codeql-home\databases\kmdf
CALL C:\codeql-home\codeql\codeql\codeql.cmd database create -l=cpp -s="C:\codeql-home\drivers\kmdf" -c "msbuild /p:Configuration=Release /p:Platform=x64 C:\codeql-home\drivers\kmdf\kmdfecho.sln /t:rebuild /p:PostBuildEventUseInBuild=false " "C:\codeql-home\databases\kmdf" -j 0
CALL C:\codeql-home\codeql\codeql\codeql database analyze "C:\codeql-home\databases\kmdf" "<path to query suite .qls file>" --format=sarifv2.1.0 --output=C:\codeql-home\databases\kmdf.sarif -j 0 --rerun
ECHO ">>> Loading SARIF Results in Visual Studio <<<"
CALL devenv /Edit C:\codeql-home\databases\kmdf.sarif
SET ERRORLEVEL = 0

  2. Параметрdevenv.exe /Edit используется в пакетном файле для открытия файла результатов SARIF в существующем экземпляре Visual Studio. Чтобы просмотреть результаты SARIF, установите средство просмотра Microsoft SARIF для Visual Studio и ознакомьтесь с инструкциями, приведенными в этой статье.

  3. В проекте драйвера перейдите к свойствам проекта. В раскрывающемся списке "Конфигурация" выберите конфигурацию сборки, которую вы хотите проверить с помощью CodeQL. Рекомендуется Release. Создание базы данных CodeQL и выполнение запросов занимает несколько минут, поэтому не рекомендуется запускать CodeQL в конфигурации отладки проекта.

  4. Выберите "События сборки " и "Событие после сборки " в свойствах проекта драйвера.

  5. Укажите путь к пакетном файлу и описание события после сборки.

Конфигурация события после сборки Visual Studio, показывающая пакетный файл, настроенный в качестве параметра командной строки.

  1. Результаты пакетного файла отображаются в конце выходных данных сборки.

    1>Starting evaluation of codeql-cpp\Likely Bugs\Underspecified Functions\MistypedFunctionArguments.ql.
1>Starting evaluation of codeql-cpp\Likely Bugs\Underspecified Functions\TooManyArguments.ql.
1>Starting evaluation of codeql-cpp\Likely Bugs\Underspecified Functions\TooFewArguments.ql.
1>Starting evaluation of codeql-cpp\Likely Bugs\Underspecified Functions\ImplicitFunctionDeclaration.ql.
1>[1/4 eval 4.4s] Evaluation done; writing results to codeql-cpp\Likely Bugs\Underspecified Functions\TooManyArguments.bqrs.
1>[2/4 eval 4.4s] Evaluation done; writing results to codeql-cpp\Likely Bugs\Underspecified Functions\TooFewArguments.bqrs.
1>[3/4 eval 4.5s] Evaluation done; writing results to codeql-cpp\Likely Bugs\Underspecified Functions\ImplicitFunctionDeclaration.bqrs.
1>[4/4 eval 5.2s] Evaluation done; writing results to codeql-cpp\Likely Bugs\Underspecified Functions\MistypedFunctionArguments.bqrs.
1>Shutting down query evaluator.
1>Interpreting results.
1>">>> Loading SARIF Results in Visual Studio <<<"

Связанный контент