CodeQL и проверка логотипа статических средств

Статья
04/03/2024

Безопасность CodeQL и драйвера

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

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

Использование CodeQL для целей тестирования WHCP допускается в рамках лицензионного соглашения о лицензировании аппаратного набора лабораторий (HLK). Для участников WHCP EULA HLK перезаписывает условия CodeQL GitHub, заявив, что CodeQL можно использовать во время автоматического анализа, CI или CD, в рамках обычных процессов проектирования для анализа драйверов, которые должны быть отправлены и сертифицированы в рамках WHCP.

Требование проанализировать исходный код драйвера и исправить все нарушения "Обязательно исправлять" будет применяться с помощью теста логотипа статических средств.

В этом разделе описываются следующие действия:

Используйте CodeQL для анализа исходного кода драйвера для известных проблем с безопасностью высокого влияния.
Убедитесь, что проверка логотипа статических средств может использовать результаты выполнения CodeQL.
Определите, какие запросы must-Fix должны выполняться для сертификации WHCP.

Внимание

Программа совместимости оборудования Windows требует проверки CodeQL для статических проверок логотипа средства (STL) на наших клиентских и серверных операционных системах. Мы будем продолжать поддерживать поддержку SDV и ЦС на старых продуктах. Партнерам настоятельно рекомендуется ознакомиться с требованиями CodeQL к статическому тесту логотипа средства.

HLK EULA и CodeQL

Использование CodeQL для сертификации для тестирования программы совместимости оборудования Windows допускается в соответствии с соглашением о лицензировании конечных пользователей пакета лабораторий оборудования (HLK ). Для участников WHCP EULA HLK перезаписывает условия GitHub CodeQL. EULA HLK указывает, что CodeQL можно использовать во время автоматического анализа, CI или CD в рамках обычных инженерных процессов для анализа драйверов, которые должны быть отправлены и сертифицированы в рамках программы совместимости оборудования Windows. Для тех, кто следует наряду с общим использованием, ознакомьтесь с условиями и/или контактом CodeQL GitHub CodeQL.

Основные понятия CodeQL

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

CodeQL также предоставляет возможность создания пользовательских запросов. Дополнительные сведения о написании пользовательских запросов см. в статье "Написание запросов " в документации CodeQL.

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

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

1. Настройка CodeQL

Использование программы совместимости оборудования Windows

Матрица версий выпуска программы совместимости оборудования Windows

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

Выпуск Windows	Версия CLI CodeQL	Версия пакета QL для microsoft/windows-drivers	версия пакета QL для codeql/cpp-queries	Ветвь для использования
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

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

Общие сведения об использовании

Для общего использования CodeQL с другими версиями Windows за пределами программы WHCP или для разработки и тестирования запросов в настоящее время рекомендуется использовать следующую версию и ветвь:

Версия CLI CodeQL	Версия qlpack для microsoft/windows-drivers	версия codeql/cpp-queries	Ветвь для использования
2.15.4	latest	latest	main

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

Примечание.

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

Создайте каталог для хранения CodeQL. В этом примере используется C:\codeql-home\
```
C:\> mkdir C:\codeql-home
```
Ознакомьтесь с таблицами выше, чтобы выбрать версию cli CodeQL, используемую в соответствии с требуемой ветвью запросов драйвера Майкрософт. Если вы выполняете анализ в рамках программы WHCP, обратитесь к таблице для программы совместимости оборудования Windows, в противном случае используйте главную ветвь и 2.15.4. Использование другой версии может привести к несовместимости базы данных с библиотеками.
Перейдите в двоичные файлы CodeQL CLI, связанные с таблицами выше, и скачайте ZIP-файл в соответствии с архитектурой проекта. Например, для 64-разрядной версии Windows "codeql-win64.zip".
Извлеките каталог Cli Codeql в только что созданный, например C:\codeql-home\codeql.

Убедитесь, что 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'.

Команда справки отображает сведения об использовании командной строки.

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

Для ветвей WHCP_21H2 и WHCP_22H2

При использовании Visual Studio 2022 17.8 или более поздней версии с WHCP_21H2 или WHCP_22H2 и CodeQL CLI версии 2.15.4:

Выполните действия, описанные в разделе "ВСЕ ДРУГИЕ ВЕТВИ".
Не забудьте удалить подмодул CodeQL, если у вас по-прежнему есть старая версия клонированного репозитория. CodeQL может попытаться использовать запросы в подмодуле по умолчанию, что приведет к ошибкам из-за несоответствия версий.

Если используется Visual Studio версии 17.7 или ниже , WHCP_21H2 или WHCP_22H2 AND CodeQL CLI версии 2.4.6 или 2.6.3:

Следуйте инструкциям по WHCP_21H2 и WHCP_22H2 с помощью VS17.7 или более ранней версии .

ВСЕ ОСТАЛЬНЫЕ ВЕТВИ

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

Для использования запросов для сертификации больше не требуется клонировать репозиторий Windows-Driver-Developer-Supplemental-Tools. Теперь используются пакеты CodeQL ("пакеты QL" или "пакеты запросов").

Скачайте правильную версию пакета драйверов microsoft/windows из матрицы версий выпуска программы совместимости оборудования Windows. Укажите приведенную @<version> ниже команду.

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

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

C:\codeql-home\> codeql pack download microsoft/[email protected]

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

C:\codeql-home\> codeql pack download codeql/[email protected]

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

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

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

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

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

Найдите и скопируйте на локальный компьютер два основных файла набора запросов.

windows-driver-recommended.qls
windows-driver-mustfix.qls

Их содержимое показано ниже в запросах и наборах. Два файла находятся в https://github.com/microsoft/Windows-Driver-Developer-Supplemental-Tools/tree/main/suites

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

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

Создайте каталог CodeQL для размещения создаваемых баз данных. Например: C:\codeql-home\database
```
mkdir C:\codeql-home\databases
```
Используйте команду CodeQL для создания базы данных с помощью следующих параметров:
- первый параметр — это ссылка на каталог базы данных. Например: C:\codeql-home\database\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" или используйте следующую команду:

C:\codeql-home\codeql> codeql database create --help

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

Примечание.

Если вы используете Visual Studio версии 17.7 или ниже , WHCP_21H2 или WHCP_22H2 AND CodeQL VLI версии 2.4.6 или 2.6.3, следуйте специальным инструкциям по WHCP_21H2 и WHCP_22H2 с помощью VS17.7 или более ранней версии.

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

Используйте команду 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 
```
Дополнительные сведения или помощь с помощью команды см. в описании анализа баз данных с помощью интерфейса командной строки CodeQL и использования database analyze пакета CodeQL для анализа базы данных CodeQL.

Для командной строки воспользуйтесь следующей командой:
```
C:\codeql-home\codeql> codeql database analyze --help
```

Специальные инструкции по WHCP_21H2 и WHCP_22H2 с помощью VS17.7 или более ранней версии

Эти инструкции применяются только при использовании Visual Studio 17.7 или более ранней версии, а также CodeQL 2.6.3 или 2.4.6

Установите версию CodeQL, как указано выше.
Клонируйте и установите репозиторий дополнительных средств разработчика драйверов Windows, содержащий запросы CodeQL, относящиеся к драйверам:

git clone https://github.com/microsoft/Windows-Driver-Developer-Supplemental-Tools.git --recurse-submodules
См. матрицу версий выпуска программы совместимости оборудования Windows, чтобы определить правильную ветвь для версии Windows, для которой вы хотите сертифицировать.
git checkout Используйте команду, чтобы извлечь идентифицированную ветвь.
Убедитесь, что подмодулы присутствуют в каталоге codeql-home.
```
 D:/codeql-home
     |--- codeql
     |--- Windows-Driver-Developer-Supplemental-Tools
```
Анализ базы данных CodeQL.

Обновите эту примерную команду, чтобы соответствовать вашей среде. Задайте параметры, путь к новой базе данных, формату, выходному файлу sarif, пути к запросу CodeQL или набору запросов для использования в анализе.

codeql database analyze <path to database> --format=sarifv2.1.0 --output=<"path to output file".sarif> <path to query/suite to run>

Пример:

codeql database analyze D:\DriverDatabase --format=sarifv2.1.0 --output=D:\DriverAnalysis1.sarif D:\codeql-home\Windows-driver-developer-supplemental-tools\src\suites\windows_driver_mustfix.qls

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

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

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

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

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

Средство просмотра Microsoft Sarif (Web) имеет функциональные возможности, позволяющие перетаскивать ФАЙЛ SARIF в средство просмотра, а затем отображать результаты, классифицированные по правилу. Это очень быстрый и простой способ увидеть количество нарушений или наличие нарушений запросов, но менее просто найти сведения о исходном коде в стороне от номера строки. Обратите внимание, что страница не будет обновляться, если нет нарушений.
Средство просмотра Microsoft SARIF для Visual Studio отлично подходит для отображения результатов в Visual Studio для простого перехода от результатов к исходному коду.
Расширение SARIF для Visual Studio Code

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

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

5. Подавление результатов CodeQL (необязательно)

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

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

Known limitation: В настоящее время нельзя объединить #pragma(отключить) и #pragma(подавление) в одной строке.

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

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

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

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

Проверка логотипа статических инструментов анализирует журнал проверки драйвера (DVL), который является скомпилированных результатов из нескольких статических обработчиков анализа, которые выполняются в исходном коде драйвера. Существует три способа преобразования SARIF-файла в формат DVL, который лучше всего подходит для настройки.

Использование Visual Studio (предварительная версия сборки WDK 20190 и более полной версии)

Поместите файл результатов SARIF в тот же каталог, что и файл .vcxproj.
В меню расширения "Драйвер" выберите "Создать журнал проверки драйвера".
Убедитесь, что пользовательский интерфейс DVL обнаруживает файл SARIF.
- Примечание. При перемещении ФАЙЛА SARIF в каталог .vcxproj с помощью пользовательского интерфейса Visual Studio можно создать ссылку на ФАЙЛ SARIF вместо фактического перемещения. Попробуйте открыть каталог за пределами Visual Studio, чтобы убедиться, что он действительно существует там.
Нажмите кнопку создания.

Использование MSBuild

Поместите файл результатов SARIF в тот же каталог, что и файл .vcxproj.
Откройте командную строку Visual Studio, командную строку Visual Studio Native Tools или комплект драйверов Для Корпоративных Windows (EWDK).
Используйте команду msbuild со следующими параметрами:
- путь к файлу проекта vcx
- /target:dvl
- /p:Configuration="Release"
- /P:Platform=<platform> (Используйте только одну из следующих строк: x86, x64, arm, arm64)
msbuild.exe <vcxprojectfile> /target:dvl /p:Configuration="Release" /P:Platform=<platform>

Использование CMD

Найдите dvl.exe из WDK или подключенного eWDK.
Используйте exe со следующими параметрами:
- /manualCreate
- driver name (Не включайте формат файла .sys)
- driver architecture (Используйте только одну из следующих строк: x86, x64, arm, arm64)
"C:\Program Files (x86)\Windows Kits\10\Tools\dvl\dvl.exe" /manualCreate <driver name> <driver architecture>

Дополнительные инструкции по тестированию HLK статических инструментов и инструкциям по расположению DVL-файла можно найти в разделе "Выполнение теста".

7. Событие после сборки Visual Studio (необязательно)

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

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

Создайте небольшой пакетный файл, который повторно создает базу данных 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" "C:\codeql-home\Windows-Driver-Developer-Supplemental-Tools\codeql\codeql-queries\cpp\ql\src\Likely Bugs\Underspecified Functions" --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

Параметр devenv.exe / Edit используется в пакетном файле для открытия файла результатов SARIF в существующем экземпляре Visual Studio. Чтобы просмотреть результаты SARIF, установите средство просмотра Microsoft SARIF для Visual Studio и ознакомьтесь с инструкциями, приведенными в этой статье.
В проекте драйвера перейдите к свойствам проекта. В раскрывающемся списке "Конфигурация" выберите конфигурацию сборки, которую вы хотите проверить с помощью CodeQL, рекомендуется "Выпуск". Создание базы данных CodeQL и выполнение запросов занимает несколько минут, поэтому не рекомендуется запускать CodeQL в конфигурации отладки проекта.
Выберите "События сборки" и "Событие после сборки" в свойствах проекта драйвера.
Укажите путь к пакетном файлу и описание события после сборки.

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

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

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 <<<"

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

При сертификации с помощью WHCP сначала убедитесь, что вы используете версию HLK, связанную с целевым выпуском Windows, связанную ветвь в репозитории дополнительных средств разработчика драйверов Windows и следующую версию CLI CodeQL. Матрица совместимости выпусков HLK/Windows см . в комплекте лабораторий оборудования Windows и репозитории дополнительных средств для разработчиков драйверов 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'.

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

Запросы и наборы

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

Запросы, необходимые для исправления

Подмножество приведенных ниже запросов — Must-Fix для сертификации WHCP, а также входит в набор рекомендуемых исправлений.

Этот набор правил включен в windows_driver_mustfix.qls.

Идентификатор	Расположение	Общее перечисление слабых мест
cpp/bad-addition-overflow-check	codeql/cpp-queries/`<Version>`/Likely Bugs/Arithmetic/BadAdditionOverflowCheck.ql	CWE-190, CWE-192
cpp/pointer-overflow-check	codeql/cpp-queries//Likely Bugs/`<Version>`Memory Management/PointerOverflow.ql	Н/П
cpp/too-few-arguments	codeql/cpp-queries//Likely Bugs/`<Version>`Underspecified Functions/TooFewArguments.ql	Н/П
cpp/comparison-with-wider-type	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-190/ComparisonWithWiderType.ql	CWE-190, CWE-197, CWE-835
cpp/hresult-boolean-conversion	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-253/HResultBooleanConversion.ql	CWE-253

Файл windows_driver_mustfix.qls содержит эти файлы, которые должны исправить запросы кода.

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT license.

- description: Security queries required to fix when certifying Windows Drivers
- queries: . 
  from: codeql/cpp-queries
  version: 0.9.0
- include:
    query path: 
      - Likely Bugs/Arithmetic/BadAdditionOverflowCheck.ql
      - Likely Bugs/Memory Management/PointerOverflow.ql
      - Likely Bugs/Underspecified Functions/TooFewArguments.ql
      - Security/CWE/CWE-190/ComparisonWithWiderType.ql
      - Security/CWE/CWE-253/HResultBooleanConversion.ql
- import: windows-driver-suites/windows_mustfix_partial.qls
  from: microsoft/windows-drivers

Этот набор правил включен в windows-driver-suite/windows_mustfix_partial.qls.

Идентификатор	Расположение	Общее перечисление слабых мест
cpp/windows/wdk/deprecated-api	/microsoft/windows-drivers/drivers/`<Version>`drivers/general/queries/WdkDeprecatedApis/wdk-deprecated-api.ql	Н/П
microsoft/Security/CWE/CWE-704/WcharCharConversionLimited	/microsoft/windows-drivers/`<Version>`/microsoft/Security/CWE/CWE-704/WcharCharConversionLimited.ql	CWE-704

Файл windows_mustfix_partial.qls содержит эти файлы, которые должны исправить запросы кода.

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT license.

- description: Security queries required to fix when certifying Windows Drivers
- queries: .
  from: microsoft/windows-drivers
- include:
    query path: 
      - drivers/general/queries/WdkDeprecatedApis/wdk-deprecated-api.ql
      - microsoft/Security/CWE/CWE-704/WcharCharConversionLimited.ql

Идентификатор	Расположение	Общее перечисление слабых мест
cpp/offset-use-before-range-check	codeql/cpp-queries//Best Practices/`<Version>`Likely Errors/OffsetUseBeforeRangeCheck.ql	Н/П

Идентификатор	Расположение	Общее перечисление слабых мест
cpp/условно-неинициализированная переменная	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-457/ConditionallyUninitializedVariable.ql.	CWE-457
cpp/unterminated-variadic-call	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-121/UnterminatedVarargsCall.ql	CWE-121
cpp/suspicious-pointer-scaling	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-468/IncorrectPointerScaling.ql	CWE-468
cpp/suspicious-pointer-scaling-void	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-468/IncorrectPointerScalingVoid.ql	CWE-468
cpp/потенциально опасные функции	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-676/PotentiallyDangerousFunction.ql	CWE-676
cpp/incorrect-string-type-conversion	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-704/WcharCharConversion.ql	CWE-704
cpp/comparison-with-wider-type	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-190/ComparisonWithWiderType.ql	CWE-190, CWE-197, CWE-835
cpp/hresult-boolean-conversion	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-253/HResultBooleanConversion.ql	CWE-253
cpp/suspicious-add-sizeof	codeql/cpp-queries/`<Version>`/Security/CWE/CWE-468/CWE-468/SuspiciousAddWithSizeof.ql	CWE-468

Идентификатор	Расположение	Общее перечисление слабых мест
cpp/paddingbyteinformationdisclosure	microsoft/windows-drivers/`<Version>`/microsoft/Likely Bugs/Boundary Violations/PaddingByteInformationDisclosure.ql	Н/П
cpp/badoverflowguard	microsoft/windows-drivers/`<Version>`/microsoft/Likely Bugs/Conversion/BadOverflowGuard.ql	Н/П
cpp/infiniteloop	microsoft/windows-drivers/`<Version>`/microsoft/Likely Bugs/Conversion/InfiniteLoop.ql	Н/П
cpp/uninitializedptrfield	microsoft/windows-drivers/`<Version>`/microsoft/Likely Bugs/UninitializedPtrField.ql	Н/П
cpp/use-after-free	microsoft/windows-drivers/`<Version>`/microsoft/Likely Bugs/Memory Management/UseAfterFree/UseAfterFree.ql	Н/П

Идентификатор	Расположение	Предупреждение анализа кода
cpp/weak-crypto/cng/hardcoded-iv	/microsoft/windows-drivers/`<Version>`/microsoft/Security/Crytpography/HardcodedIVCNG.ql	Н/П

Идентификатор	Расположение	Предупреждение анализа кода
cpp/drivers/ke-set-event-pageable	/microsoft/windows-drivers/`<Version>`general/queries/KeSetEventPageable/KeSetEventPageable.ql	Нет связанной проверки ЦС
cpp/drivers/role-type-correctly-used	/microsoft/windows-drivers//drivers/`<Version>`general/queries/RoleTypeCorrectlyUsed/RoleTypeCorrectlyUsed.ql	Нет связанной проверки ЦС
cpp/drivers/extended-deprecated-apis	/microsoft/windows-drivers/drivers/drivers/`<Version>`general/queries/ExtendedDeprecatedApis.ql	Предупреждение C28719, предупреждение C28726, предупреждение C28735, предупреждение C28750
cpp/drivers/irql-not-saved	/microsoft/windows-drivers/drivers/`<Version>`drivers/general/queries/IrqlNotSaved/IrqlNotSaved.ql	Предупреждение C28158
cpp/drivers/irql-not-used	/microsoft/windows-drivers//drivers/`<Version>`general/queries/IrqlNotUsed/IrqlNotUsed.ql	Предупреждение C28157
cpp/drivers/irql-set-too-high	/microsoft/windows-drivers//drivers/`<Version>`general/queries/IrqlTooHigh/IrqlTooHigh.ql	Предупреждение C28150
cpp/drivers/irql-too-low	/microsoft/windows-drivers/drivers/`<Version>`drivers/general/queries/IrqlTooLow/IrqlTooLow.ql	Предупреждение C28120
cpp/drivers/irql-set-too-high	/microsoft/windows-drivers/drivers/`<Version>`drivers/general/queries/IrqlSetTooHigh/IrqlTooHigh.ql	Предупреждение C28121
cpp/drivers/irql-set-too-low	/microsoft/windows-drivers/drivers/`<Version>`drivers/general/queries/IrqlSetTooLow/IrqlSetTooLow.ql	Предупреждение C28124
cpp/drivers/pool-tag-integral	/microsoft/windows-drivers/drivers/drivers/`<Version>`general/queries/PoolTagIntegral/PoolTagIntegral.ql	Предупреждение C28134
cpp/drivers/str-safe	/microsoft/windows-drivers//drivers/`<Version>`general/queries/StrSafe/StrSafe.ql	Предупреждение C28146

Идентификатор	Расположение	Предупреждение анализа кода
cpp/drivers/illegal-field-access	/microsoft/windows-drivers/`<Version>`/drivers/wdm/queries/IllegalFieldAccess/IllegalFieldAccess.ql	Предупреждение C28128
cpp/drivers/illegal-field-access2	/microsoft/windows-drivers/`<Version>`/drivers/wdm/queries/IllegalFieldAccess2/IllegalFieldAccess2.ql	Предупреждение C28175
cpp/drivers/illegal-field-write	/microsoft/windows-drivers/`<Version>`/drivers/wdm/queries/IllegalFieldWrite/IllegalFieldWrite.ql	Предупреждение C28176
cpp/drivers/opaque-mdl-use	/microsoft/windows-drivers/`<Version>`/drivers/wdm/queries/OpaqueMdlUse/OpaqueMdlUse.ql	(Нет связанной проверки ЦС)
cpp/drivers/opaque-mdl-write	/microsoft/windows-drivers/`<Version>`/drivers/wdm/queries/OpaqueMdlUse/OpaqueMdlWrite.ql	Предупреждение C28145
cpp/drivers/pending-status-error	/microsoft/windows-drivers/`<Version>`/drivers/wdm/queries/PendingStatusError/PendingStatusError.ql	Предупреждение C28143
cpp/drivers/wrong-dispatch-table-assignment	/microsoft/windows-drivers/`<Version>`/drivers/wdm/queries/WrongDispatchTableAssignment/WrongDispatchTableAssignment.ql	Предупреждение C28169

Сведения о требованиях см. в процессе сертификации программы совместимости оборудования Windows.

Какова мотивация, связанная с требованием запуска CodeQL в исходном коде драйвера?

Мотивация для выполнения CodeQL в исходном коде драйвера может быть обобщена двумя основными причинами:

Безопасность Windows имеет первостепенное значение и требуется, чтобы CodeQL выполнялся в исходном коде драйвера, является одним из этапов, помогающих повысить безопасность компонентов, сертифицированных корпорацией Майкрософт.
Запросы CodeQL активно разрабатываются инженерами по безопасности корпорации Майкрософт, так как корпорация Майкрософт стремится обеспечить преимущества экосистемы оборудования от того же высококачественного инструмента, используемого в Корпорации Майкрософт.

К каким типам драйверов применяются кодQL и тест на логотип статических средств?

В настоящее время для проверки логотипа статических инструментов требуется запустить CodeQL и набор запросов "Must-Fix" для всех драйверов в режиме ядра, за исключением графических драйверов. Обратите внимание, что выполнение CodeQL на графических драйверах настоятельно рекомендуется, хотя в настоящее время оно не требуется. Некоторые запросы также могут найти полезные дефекты в компонентах пользовательского режима.

Мы ожидаем, что расширение теста и его запросов требует результатов для графических драйверов, драйверов пользовательского режима и компонентов драйверов и других компонентов пакета драйверов в будущем. Если вы столкнулись с непредвиденным поведением или ложными срабатываниями, работающими под управлением CodeQL на графических драйверах или драйверах пользовательского режима, отправьте проблему в репозитории Windows-Driver-Developer-Supplemental-Tools.

Какая лицензия управляет использованием CodeQL для разработчиков драйверов?

Использование CodeQL для целей тестирования WHCP допускается в рамках лицензионного соглашения о лицензировании аппаратного набора лабораторий (HLK). Для участников WHCP EULA HLK перезаписывает условия GitHub CodeQL. EULA HLK указывает, что CodeQL можно использовать во время автоматического анализа, CI или CD в рамках обычных инженерных процессов для анализа драйверов, которые должны быть отправлены и сертифицированы в рамках WHCP.

Нужно ли использовать Visual Studio или msbuild для запуска CodeQL?

CodeQL не требует использования MSBuild или Visual Studio. См . поддерживаемые языки и платформы для списка поддерживаемых компиляторов .

Как HLK проверяет, что мой драйвер был сканирован CodeQL?

Проверка логотипа статических средств в HLK — это тест, который применяет это требование. Сведения о проверке логотипа статических инструментов см. на странице ms Docs.

Отображаются ли все дефекты, сообщаемые CodeQL истинными дефектами?

Каждый запрос CodeQL имеет различные уровни точности. Наша цель заключается в том, чтобы свести к минимуму ложные срабатывания, но иногда они будут возникать. Наш набор запросов "Must-Fix" был разработан и выбран для использования с программой WHCP, так как наше обширное тестирование приводит к почти нулю ложных срабатываний. Если вы видите ложные срабатывания из запроса в наборе запросов "Необходимо исправить", немедленно или [email protected] отправьте проблему в репозитории Windows-Driver-Developer-Supplemental-Tools, и мы будем работать, чтобы устранить ее как можно скорее.

Имеет ли запрос классификация "предупреждение" или "ошибка" в целях проверки логотипа статических средств?

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

Можно ли создать DVL в решениях Visual Studio?

Нет, поколение DVL должно выполняться на уровне проекта и не может выполняться в решениях Visual Studio. Инструкции по созданию DVL см. в статье "Создание журнала проверки драйвера".

Можно ли создать журнал проверки драйвера (DVL) вне контекста msbuild или Visual Studio?

В составе комплекта драйверов Windows (WDK) и Enterprise WDK (eWDK) корпорация Майкрософт поставляет компонент с именем dvl.exe который можно использовать для создания журналов проверки драйверов (DVLS). Начиная с предварительной версии WDK/eWDK версии 21342 и выше, можно создать DVL из командной строки вне контекста msbuild или Visual Studio, передав имя драйвера и архитектуру. Дополнительные сведения см. в статье о создании журнала проверки драйвера.

У меня есть комментарии или вопросы о том, как использовать CodeQL на моем драйвере, где я отправляю отзыв?

Отправка отзывов и вопросов [email protected]в .

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