CodeQL и проверка логотипа статических средств
Безопасность 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 VLI версии 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/windows-drivers@1.1.0
Используйте эту команду, чтобы скачать пакет запросов CodeQL cpp-querys версии 0.9.0.
C:\codeql-home\> codeql pack download codeql/cpp-queries@0.9.0
(Обратите внимание, что можно пропустить приведенный выше шаг, так как --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 и пример необработанных выходных данных SARIF.
Существует несколько методов интерпретации результатов анализа, включая сортировку по объектам вручную. Ниже приведены некоторые из них:
Средство просмотра Microsoft Sarif (Web) имеет функциональные возможности, позволяющие перетаскивать ФАЙЛ SARIF в средство просмотра, а затем отображать результаты, классифицированные по правилу. Это очень быстрый и простой способ увидеть количество нарушений или наличие нарушений запросов, но менее просто найти сведения о исходном коде в стороне от номера строки. Обратите внимание, что страница не будет обновляться, если нет нарушений.
Средство просмотра Microsoft SARIF для Visual Studio отлично подходит для отображения результатов в Visual Studio для простого перехода от результатов к исходному коду.
Наиболее важным разделом ФАЙЛА 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 со следующими параметрами:
/manualCreatedriver 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 в конфигурации отладки проекта.
Выберите "События сборки" и "Событие после сборки" в свойствах проекта драйвера.
Укажите путь к пакетном файлу и описание события после сборки.
Результаты выполнения пакетного файла будут отображаться в конце выходных данных сборки.
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-проверка | codeql/cpp-queries/<Version>/Likely Bugs/Arithmetic/BadAdditionOverflowCheck.ql |
CWE-190, CWE-192 |
| cpp/pointer-overflow-проверка | 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
Рекомендуемые запросы исправлений
Эти запросы являются частью набора запросов windows_driver_recommended.qls в репозитории Microsoft GitHub CodeQL. Столбец "Общее перечисление слабых мест" (CWE) указывает, какие виды проблем безопасности выполняет поиск заданного запроса. Дополнительные сведения о CWEs см . на странице Mitre в CWE .
Рекомендации
| Идентификатор | Расположение | Общее перечисление слабых мест |
|---|---|---|
| cpp/offset-use-before-range-проверка | codeql/cpp-queries//Best Practices/<Version>Likely Errors/OffsetUseBeforeRangeCheck.ql |
Н/П |
Вероятные ошибки
| Идентификатор | Расположение | Общее перечисление слабых мест |
|---|---|---|
| cpp/bad-addition-overflow-проверка | codeql/cpp-queries/<Version>/Likely Bugs/Arithmetic/BadAdditionOverflowCheck.ql |
CWE-190, CWE-192 |
| cpp/integer-умножение-cast-to-long | codeql/cpp-queries/<Version>/Likely Bugs/Arithmetic/IntMultToLong.ql |
CWE-190, CWE-192, CWE-197, CWE-681 |
| cpp/signed-overflow-проверка | codeql/cpp-queries/<Version>/Likely Bugs/Arithmetic/SignedOverflowCheck.ql |
Н/П |
| cpp/upcast-array-pointer-arithmetic | codeql/cpp-queries/<Version>/Likely Bugs/Conversion/CastArrayPointerArithmetic.ql |
CWE-119, CWE-843 |
| cpp/pointer-overflow-проверка | 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/incorrect-not-operator-usage | codeql/cpp-queries//Likely Bugs/<Version>Likely Typos/IncorrectNotOperatorUsage.ql |
CWE-480 |
| cpp/suspicious-add-sizeof | codeql/cpp-queries//Likely Bugs/<Version>Memory Management/SuspiciousSizeof.ql |
CWE-468 |
| cpp/uninitialized-local | codeql/cpp-queries/<Version>/Likely Bugs/Memory Management/UninitializedLocal.ql |
CWE-457, CWE-665 |
Безопасность
| Идентификатор | Расположение | Общее перечисление слабых мест |
|---|---|---|
| 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 |
Файл windows_driver_recommended.qls содержит эти рекомендуемые запросы кода.
# Copyright (c) Microsoft Corporation.
# Licensed under the MIT license.
- description: Recommended and required queries for Windows Drivers.
- import: windows-driver-suites/windows_mustfix_partial.qls
from: microsoft/windows-drivers
- import: windows-driver-suites/windows_recommended_partial.qls
from: microsoft/windows-drivers
- queries: .
from: codeql/cpp-queries
version: 0.9.0
- include:
query path:
- Best Practices/Likely Errors/OffsetUseBeforeRangeCheck.ql
- Likely Bugs/Arithmetic/IntMultToLong.ql
- Likely Bugs/Arithmetic/SignedOverflowCheck.ql
- Likely Bugs/Conversion/CastArrayPointerArithmetic.ql
- Likely Bugs/Likely Typos/IncorrectNotOperatorUsage.ql
- Likely Bugs/Memory Management/SuspiciousSizeof.ql
- Likely Bugs/Memory Management/UninitializedLocal.ql
- Security/CWE/CWE-121/UnterminatedVarargsCall.ql
- Security/CWE/CWE-457/ConditionallyUninitializedVariable.ql
- Security/CWE/CWE-468/IncorrectPointerScaling.ql
- Security/CWE/CWE-468/IncorrectPointerScalingVoid.ql
- Security/CWE/CWE-468/SuspiciousAddWithSizeof.ql
- Security/CWE/CWE-676/PotentiallyDangerousFunction.ql
- Security/CWE/CWE-704/WcharCharConversion.ql
- 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
Эти запросы являются частью windows_recommended_partial.qls.
Вероятные ошибки — windows_recommended_partial.qls
| Идентификатор | Расположение | Общее перечисление слабых мест |
|---|---|---|
| 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 |
Н/П |
Безопасность — windows_recommended_partial.qls
| Идентификатор | Расположение | Предупреждение анализа кода |
|---|---|---|
| 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>drivers/general/queries/Str Сейф/Str Сейф.ql |
Предупреждение C28146 |
Драйверы — WDM
| Идентификатор | Расположение | Предупреждение анализа кода |
|---|---|---|
| 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-driver-suite/windows_recommended_partial.qls содержит эти рекомендуемые запросы кода.
# Copyright (c) Microsoft Corporation.
# Licensed under the MIT license.
- description: Recommended and required queries for Windows Drivers.
- import: windows-driver-suites/windows_mustfix_partial.qls
- queries: .
from: microsoft/windows-drivers
- include:
query path:
- microsoft/Likely Bugs/Boundary Violations/PaddingByteInformationDisclosure.ql
- microsoft/Likely Bugs/Conversion/BadOverflowGuard.ql
- microsoft/Likely Bugs/Conversion/InfiniteLoop.ql
- microsoft/Likely Bugs/Memory Management/UseAfterFree/UseAfterFree.ql
- microsoft/Likely Bugs/UninitializedPtrField.ql
- microsoft/Security/Crytpography/HardcodedIVCNG.ql
- drivers/general/queries/KeSetEventPageable/KeSetEventPageable.ql
- drivers/general/queries/RoleTypeCorrectlyUsed/RoleTypeCorrectlyUsed.ql
- drivers/general/queries/DefaultPoolTag/DefaultPoolTag.ql
- drivers/general/queries/ExaminedValue/ExaminedValue.ql
- drivers/general/queries/ExtendedDeprecatedApis/ExtendedDeprecatedApis.ql
- drivers/general/queries/IrqlNotSaved/IrqlNotSaved.ql
- drivers/general/queries/IrqlNotUsed/IrqlNotUsed.ql
- drivers/general/queries/IrqlTooHigh/IrqlTooHigh.ql
- drivers/general/queries/IrqlTooLow/IrqlTooLow.ql
- drivers/general/queries/IrqlSetTooHigh/IrqlTooHigh.ql
- drivers/general/queries/IrqlSetTooLow/IrqlSetTooLow.ql
- drivers/general/queries/PoolTagIntegral/PoolTagIntegral.ql
- drivers/general/queries/StrSafe/StrSafe.ql
- drivers/wdm/queries/IllegalFieldAccess/IllegalFieldAccess.ql
- drivers/wdm/queries/IllegalFieldAccess2/IllegalFieldAccess2.ql
- drivers/wdm/queries/IllegalFieldWrite/IllegalFieldWrite.ql
- drivers/wdm/queries/OpaqueMdlUse/OpaqueMdlUse.ql
- drivers/wdm/queries/OpaqueMdlUse/OpaqueMdlWrite.ql
- drivers/wdm/queries/PendingStatusError/PendingStatusError.ql
- drivers/wdm/queries/WrongDispatchTableAssignment/WrongDispatchTableAssignment.ql
Часто задаваемые вопросы (FAQ)
Когда это потребуется для сертификации устройств?
Сведения о требованиях см. в процессе сертификации программы совместимости оборудования 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, так как наше обширное тестирование приводит к почти 0 ложных срабатываний. Если вы видите ложные срабатывания из запроса в наборе запросов "Необходимо исправить", немедленно или stlogohelp@microsoft.com отправьте проблему в репозитории 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 на моем драйвере, где я отправляю отзыв?
Отправка отзывов и вопросов stlogohelp@microsoft.comв .
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по