Windows ドライバー コードで CodeQL 分析を実行する

CodeQL は、開発者が Windows ドライバーのソース コードでセキュリティの脆弱性とコード違反を特定するのに役立つ強力な静的分析エンジンです。 この記事では、CodeQL 分析を使用して、Windows ハードウェア互換性プログラム (WHCP) 認定用のドライバー検証ファイルを作成する方法について説明します。

この記事では、次のことを行います：

• 適切な CodeQL バージョンをインストールします。
• 必要な CodeQL パッケージとクエリ スイートをインストールします。
• CodeQL を実行してデータベースを構築し、コードを分析します。
• ドライバー検証ファイルをビルドします。

ドライバーに適した CodeQL バージョンを選択する

シナリオのタブを選択します。

CodeQL をダウンロードしてインストールする

1. CodeQL を含むディレクトリを作成します。 この例では、 C:\codeql-home\

   C:\> mkdir C:\codeql-home
   

2. 前の表を参照して、Microsoft のドライバー クエリの目的のブランチに従って使用する CodeQL CLI のバージョンを選択します。 WHCP プログラムの一部として分析を実行する場合は、「 Windows ハードウェア互換性プログラムの使用」の表を参照してください。それ以外の場合は Main Branch と 2.15.4 を使用します。 別のバージョンを使用すると、データベースがライブラリと互換性がない可能性があります。

3. 前のテーブルに関連付けられている CodeQL CLI バイナリ リリースに移動し、プロジェクトのアーキテクチャに従って zip ファイルをダウンロードします。 たとえば、64 ビット Windows codeql-win64.zipの場合です。

4. 先ほど作成したディレクトリに Codeql CLI ディレクトリを抽出します (例: *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 <command> --help を実行します。 例えば次が挙げられます。

codeql create --help

サブコマンドのヘルプを表示するには、次に例を示します。

codeql create language --help

CodeQL パッケージをインストールする

ビルド環境のタブを選択します。

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

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

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

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

結果の表示と解釈

このセクションでは、次の手順に必要な SARIF 形式に焦点を当てますが、必要に応じて CSV 形式を使用することもできます。

静的分析結果交換形式 (SARIF) は、静的分析結果を共有するために使用される JSON 型の形式です。 OASIS 静的分析結果交換形式 (SARIF) の標準、CodeQL での SARIF 出力の使用方法、およびスキーマ json の詳細を確認します。

分析結果を解釈するには、オブジェクトを手動で並べ替える方法など、いくつかの方法があります。 ここでは、いくつかの方法を使用します。

• Microsoft Sarif Viewer (Web) には、SARIF ファイルをビューアーにドラッグ アンド ドロップし、ルール別に分類された結果を表示できる機能があります。 これは、違反の数や違反のあるクエリを確認する非常に迅速かつ簡単な方法ですが、行番号以外のソース コード情報を見つけるのは簡単ではありません。 違反がない場合、ページは更新されないことに注意してください。

• Microsoft SARIF Viewer for Visual Studio は、結果からソース コードにシームレスに移行するために、Visual Studio 内で結果を表示するのに最適です。

• Visual Studio Code の SARIF 拡張機能によってプレビュー ウィンドウが開き、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 ツールを使用したコマンド ラインの 3 つの方法があります。 完全な手順については、「 ドライバー検証ログの作成」を参照してください。

静的ツール ロゴ HLK テストの詳細な手順と、DVL ファイルを配置する場所に関するガイダンスについては、 静的ツール ロゴ テストの実行に関する記事を参照してください。

トラブルシューティング

WHCP で認定する場合は、まず、対象とする Windows リリースに関連付けられている HLK バージョン、Windows Driver Developer Supplemental Tools リポジトリ内の関連ブランチ、およびそれ以降の CodeQL CLI バージョンを使用していることを確認します。 HLK/Windows リリースの互換性マトリックスについては、「 Windows Hardware Lab Kit」 および「Windows リリース/Windows Driver Developer Supplemental Tools リポジトリ ブランチ/CodeQL CLI バージョン」の「 CodeQL バージョンの選択 」セクションの WHCP テーブルを参照してください。

エラーと回避策

データベースのバージョンの不一致の問題については、次のツールが役立つ場合があります。

codeql version コマンドを使用して、codeql exe のバージョンを表示します。

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 では、結果の抑制がサポートされています。 抑制は現在、開発者が問題をトリアージし、ノイズを減らすのに役立つ便利な機能として提供されています。 これは、必ず修正する チェックをバイパスする方法ではありません。 現時点では、ドライバー検証ログの生成や静的ツール ロゴ テストの合格に影響はありません。 抑制を使用するには、DriverAlertSuppression.ql クエリを、実行する他のクエリまたはスイートと同時に実行する必要があります。 既定では、このクエリは githubs main/development ブランチからスイートを実行するときに有効になります。

コード分析から移植されたチェックでは、既存のコード分析抑制が受け入れられます。 詳細については、「 C++ 警告プラグマ」を参照してください。

• Known limitation: 現時点では、同じ行に #pragma(disable) と #pragma(suppress) を組み合わせることはできません。

CodeQL を初めて使用するチェックの場合は、次の 2 つのいずれかを実行してそれらを抑制します。

• コード分析の場合と同様に、違反の上の行に #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/編集オプションは、Visual Studio の既存のインスタンスで SARIF 結果ファイルを開くためにバッチ ファイルで使用されます。 SARIF の結果を表示するには、 Microsoft SARIF Viewer for Visual Studio をインストールし、詳細については、その手順を参照してください。

3. ドライバー プロジェクトで、プロジェクトのプロパティに移動します。 [構成] プルダウンで、CodeQL で確認するビルド構成を選択します。リリースをお勧めします。 CodeQL データベースの作成とクエリの実行には数分かかるため、プロジェクトのデバッグ構成で CodeQL を実行することはお勧めしません。

4. ドライバー プロジェクトのプロパティで [ ビルド イベント ] と [ ビルド後イベント ] を選択します。

5. バッチ ファイルへのパスとビルド後イベントの説明を指定します。

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

関連コンテンツ

• CodeQL FAQ
• CodeQL の概要
• CodeQL クエリとスイート