CodeQL モデル エディターの使用

CodeQL モデル エディターについて

CodeQL モデル パックを使用すると、CodeQL code scanning 分析を拡張して、既定ではサポートされていないコードベースで使用されるカスタム ライブラリとフレームワークを認識できるようになります。 CodeQL モデル エディターを使用すると、独自のモデル パックを作成できます。 モデル エディターは、アプリケーション内の外部依存関係の呼び出しをモデル化したり、外部依存関係のすべてのパブリック エントリポイントと終了ポイントを完全にモデル化したりする上でのガイドとなります。

モデル パックを使用して code scanning 分析をカスタマイズする方法については、「既定のセットアップの構成を編集する」と「コード スキャン用の高度なセットアップのカスタマイズ」を参照してください。

モデル エディターを開くと、現在選択されている CodeQL データベースが分析され、アプリケーションが外部 API とすべてのパブリック メソッドを使用する場所が識別されます。 外部 (またはサードパーティ) API は、選択した CodeQL データベースに含まれていない API を指します。

モデル エディターには、次の 2 つの異なるモードがあります。

• アプリケーション モード (既定のビュー): エディターには、選択した CodeQL データベースによって使用される各外部フレームワークが一覧表示されます。 フレームワークを拡張すると、外部 API との間のすべての呼び出しの一覧が表示され、各呼び出しを通じてデータフローをモデル化するオプションが使用可能になります。 このモードは、特定のコードベースの CodeQL の結果を改善するのに特に役立ちます。

• 依存関係モード: エディターは、選択した CodeQL データベース内のパブリックにアクセス可能なすべての API を識別します。 このビューは、コードベースで使用できる各パブリック API のモデリングを行う上でのガイドとなります。 API 全体のモデリングが完了したら、モデルを保存し、それを使用して、依存関係を使用するすべてのコードベースの CodeQL 分析を改善できます。

この記事の残りの部分では、CodeQL モデル エディターを使用したモデリング依存関係の実用的な側面について説明します。 技術情報については、「Java と Kotlin のライブラリ モデルのカスタマイズ」、「Python 用ライブラリ モデルのカスタマイズ」、「Ruby 用ライブラリ モデルのカスタマイズ」、「C# 用ライブラリ モデルのカスタマイズ」(CodeQL 言語ドキュメント) を参照してください。

CodeQL モデル エディターの表示

1. CodeQL ワークスペースを VS Code で開きます。 例: vscode-codeql-starter ワークスペース スターター ワークスペースを使用している場合は、モデル エディターのデータ収集に使用するクエリを確保するために ql サブモジュール main を更新します。

2. Visual Studio Code で、左サイドバーの [QL] をクリックして CodeQL 拡張機能を表示します。

3. [データベース] ビューで、モデル化する CodeQL データベースを選択します。

4. CodeQL の [メソッド モデリング] ビューで、[モデリングの開始] をクリックしてモデル エディターを表示します。 または、VS Code Command Palette を使用して、[CodeQL: モデル エディターを開く (ベータ) コマンドを実行します。

5. CodeQL モデル エディターは、一連のテレメトリ クエリを実行してコード内の API を識別し、エディターが新しいタブに表示されます。

6. テレメトリ クエリが完了すると、特定された API がエディターに表示されます。

コードベースが外部 API に対して行う呼び出しをモデル化する

通常、この方法は、特定のコードベースを調べていて、CodeQL の結果の精度を向上させる場合に使用します。 これは、コードベースが CodeQL でサポートされていないフレームワークまたはライブラリを使用しており、フレームワークまたはライブラリのソース コードが分析に含まれていない場合に便利です。

このセクションでは、"sofa-jraft" という オープンソース Java プロジェクトを例として使用します。 他のコンパイル済み言語で記述された外部 API の呼び出しをモデル化するエクスペリエンスも同様です。

1. Visual Studio Code で、CodeQL のカバレッジを向上させる対象の CodeQL データベースを選択します。

2. CodeQL モデル エディターを表示します。 既定では、エディターはアプリケーション モードで実行され、選択したコードベースで使用される外部 API の一覧が表示されます。

   

3. 外部 API を展開し、コードベースから外部依存関係への呼び出しの一覧を表示します。

   

4. API 呼び出しまたはメソッドに関連付けられている [ビュー] をクリックして、コードベースで使用されている場所を表示します。

5. コードベースから API への最初の呼び出しを含むファイルが開き、CodeQL の [メソッドの使用方法] ビューが VS Code に表示されます (通常、[問題] ビューと [ターミナル] ビューが表示される場所です)。 CodeQL の [メソッドの使用方法] ビューでは、コードから API へのすべての呼び出しの一覧がメソッド別にグループ化されています。 各用途をクリックして、メソッドの使用方法をモデル化する方法を決定できます。

6. メソッドの使用方法をモデル化する方法を決定したら、別のモデルの種類を選択できます。 CodeQL 拡張機能の [CodeQL メソッドのモデリング] で、[モデルの種類] のドロップダウンをクリックします。 この変更は、メイン モデル エディターに自動的に反映されます。

7. その行の他のフィールドは、選択したモデルの種類で使用できるオプションで更新されます。

   • "Source": モデル化する "出力" 要素を選択します。
   • "Sink": モデル化する "入力" 要素を選択します。
   • "Flow summary": モデルに対する "入力" 要素と "出力" 要素を選択します。

8. モデルのデータフローの "種類" を定義します。

9. モデリングが完了したら、メイン モデル エディターを表示し、[すべて保存] または [保存] (展開された各メソッドの一覧の右下に表示) をクリックします。 エディターでモデル化されたメソッドの割合が更新されます。

モデルはワークスペースの .github/codeql/extensions/CODEQL-MODEl-PACK に格納されます。CODEQL-MODEL-PACK は、選択した CodeQL データベースの名前です。 つまり、リポジトリ名、ハイフン、CodeQL で分析された言語となっています。 詳しくは、「CodeQL パックの作成と操作」をご覧ください。

モデルは、外部 API ごとに 1 つずつ、一連の YAML データ拡張ファイルに格納されます。 次に例を示します。

.github/codeql/extensions/sofa-jraft-java # the model pack directory
    models
        jmh-core.model.yml                  # models calls to jmh-core@1.20
        rocksdbjni.model.yml                # models calls to rocksdbjni@7.7.3

コードベースのパブリック API のモデル化

通常、このメソッドは、組織が複数のコードベースで使用するフレームワークまたはライブラリをモデル化する場合に使用します。 モデルの作成とテストが完了したら、CodeQL モデル パックを GitHub Container registry に発行すると、組織全体で使用できるようになります。

このセクションでは、"sofa-jraft" という オープンソース Java プロジェクトを例として使用します。 他のコンパイル済み言語で記述された外部 API の呼び出しをモデル化するエクスペリエンスも同様です。

1. モデル化する CodeQL データベースを選択します。

2. CodeQL モデル エディターを表示します。 既定では、エディターはアプリケーション モードで実行されます。 依存関係モードを表示するには、[依存関係でモデル表示] をクリックします。 画面が変わり、フレームワークまたはライブラリのパブリック API が表示されます。

   

3. クリックしてパッケージを展開し、使用可能なメソッドの一覧を表示します。

4. メソッドに関連付けられている [ビュー] をクリックして、その定義を表示します。

   

5. メソッドのモデル化方法を決定したら、"モデル型" を定義します。

6. その行の他のフィールドは、選択したモデルの種類で使用できるオプションで更新されます。

   • "Source": モデル化する "出力" 要素を選択します。
   • "Sink": モデル化する "入力" 要素を選択します。
   • "Flow summary": モデルに対する "入力" 要素と "出力" 要素を選択します。

7. モデルのデータフローの "種類" を定義します。

8. モデリングが完了したら、[すべて保存] または [保存] (展開された各呼び出しの一覧の右下に表示) をクリックします。 エディターでモデル化された呼び出しの割合が更新されます。

モデルはワークスペースの .github/codeql/extensions/CODEQL-MODEL-PACK に格納されます。CODEQL-MODEL-PACK は、選択した CodeQL データベースの名前です。 つまり、リポジトリ名、ハイフン、CodeQL で分析された言語となっています。 詳しくは、「CodeQL パックの作成と操作」をご覧ください。

モデルは、パブリック メソッドごとに 1 つずつ、一連の YAML データ拡張ファイルに格納されます。 次に例を示します。

.github/codeql/extensions/sofa-jraft-java          # the model pack directory
    models
        com.alipay.sofa.jraft.option.model.yml # models public methods in package
        com.alipay.sofa.jraft.rhea.options.model.yml

エディターは、モデル化するパッケージごとに個別のモデル ファイルを作成します。

複数の潜在的なフローを持つモデリング メソッド

一部のメソッドでは、複数のデータ フローがサポートされています。 メソッドのすべてのデータ フローをモデル化することが重要です。そうしないと、メソッドの使用に関連するすべての潜在的な問題を検出できなくなります。 まず、メソッドの 1 つのデータ フローをモデル化し、次にメソッド行の + ボタンで 2 つ目のデータ フロー モデルを指定します。

VS Code で CodeQL モデル パックをテストする

VS Code で作成した CodeQL モデル パックは、[実行中のクエリ: 拡張機能パックを使用する] 設定でテストできます。 詳しくは、「設定のカスタマイズ」をご覧ください。 このメソッドは、データベースとバリアント分析リポジトリの両方で機能します。

• ワークスペースの .github/codeql/extensions ディレクトリ内に格納されているモデル パックを使用して CodeQL データベースに対してクエリを実行するには、次のコマンドを使用して settings.json ファイルを更新します。"codeQL.runningQueries.useExtensionPacks": "all",

• モデル パックを使用せずに CodeQL データベースに対してクエリを実行するには、次のコマンドを使用して settings.json ファイルを更新します。"codeQL.runningQueries.useExtensionPacks": "none",

モデルが正常に動作している場合は、2 つの別々の実行結果が異なったものとなります。 結果に違いがない場合は、既知のバグを導入して、モデルが期待どおりに動作することを確認する必要があります。

参考資料

• 既定のセットアップの構成を編集する
• コード スキャン用の高度なセットアップのカスタマイズ CodeQL パックを使った分析のカスタマイズ。