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

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

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

モデル パックを使用した code scanning 分析のカスタマイズの詳細については、「 既定設定の構成を編集する 」および 「AUTOTITLE」を参照してください。

モデル エディターを開くと、現在選択されている 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` ワークスペース](https://github.com/github/vscode-codeql-starter)。 スターター ワークスペースを使用している場合は、モデル エディターのデータ収集に使用するクエリを確保するために `ql` サブモジュール `main` を更新します。
   

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

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

4.        CodeQLの [メソッド モデリング] ビューで、[**モデリングの開始**] をクリックしてモデル エディターを表示します。 または、 VS Code Command Palette を使用して **CodeQL: Open Model Editor (Beta)** コマンドを実行します。 <!-- markdownlint-disable-line outdated-release-phase-terminology --> <!-- "Beta" is in the name of the command in the VS Code extension -->
   

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

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

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

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

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

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

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

   

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

   

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

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

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

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

   • "ソース": モデル化する "出力" 要素を選択します。
   • "シンク": モデル化する "入力" 要素を選択します。
   • "制御フロー": モデルに対する "入力" 要素と "出力" 要素を選択します。

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 モデル パックを GitHubContainer registry に発行できます。

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

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

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

   

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

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

   

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

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

   • "ソース": モデル化する "出力" 要素を選択します。
   • "シンク": モデル化する "入力" 要素を選択します。
   • "制御フロー": モデルに対する "入力" 要素と "出力" 要素を選択します。

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 つ目のデータ フロー モデルを指定します。

          CodeQLにおけるモデルパックVS Codeのテスト

          CodeQLで作成したVS Code モデル パックは、[実行中のクエリ: 拡張パックを使用する] 設定でテストできます。 詳細については、「[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings)」を参照してください。 このメソッドは、データベースとバリアント分析リポジトリの両方で機能します。

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

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

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

詳細については、次を参照してください。

• 既定設定の構成を編集する
• コード スキャンのワークフロー構成オプションCodeQL パックを使った分析のカスタマイズ。