マルチリポジトリ バリアント分析を使用した大規模な CodeQL クエリの実行

マルチリポジトリバリアント分析 (MRVA) を使用すると、CodeQLからGitHub上の最大 1,000 個のリポジトリの一覧に対してVisual Studio Codeクエリを実行できます。

前提条件

• リポジトリを分析用の一覧に追加する前に、code scanningをGitHubで有効にし、CodeQLを使用する必要があります。既定のセットアップまたは高度なセットアップのいずれかを選択してください。 code scanningを使用してCodeQLを有効にする方法については、コード スキャンの既定セットアップの構成 を参照してください。

• 最初のマルチリポジトリ バリアント分析を実行する前に、コントローラー リポジトリを定義する必要があります。

• コントローラー リポジトリは空でもかまいませんが、少なくとも 1 つのコミットが必要です。

• コントローラー リポジトリは、MRVA を使用して分析するリポジトリと同じサイト ( GitHub.com または SUBDOMAIN.ghe.com) でホストされている必要があります。 データ所在地付き GitHub Enterprise Cloudで MRVA を実行する場合は、「拡張機能で使用されるGitHub URL の変更」を参照してください。

•         GitHub.comでは、パブリック リポジトリのみを分析する予定の場合は、コントローラー リポジトリの可視性を "パブリック" にすることができます。 バリアント分析は無料です。
  

•         GitHub.com上のプライベート リポジトリまたは内部リポジトリを分析する必要がある場合は、コントローラー リポジトリの可視性を "プライベート" にする必要があります。 
  

無料制限を超えるプライベート リポジトリまたは内部リポジトリでバリアント分析を実行するために使用するアクション (分) はすべて、リポジトリの所有者に課金されます。 無料分と課金の詳細については、 GitHub Actions の課金 を参照してください。

MRVA 用のコントローラー リポジトリの設定

1. [バリアント分析リポジトリ] ビューで、[コントローラー リポジトリの設定] をクリックして、コントローラー リポジトリのフィールドを表示します。

   

2. コントローラー リポジトリとして使用する GitHub に、リポジトリの所有者と名前を入力し、 Enter キーを押します。 このリポジトリは、分析するリポジトリと同じ GitHub インスタンス上にある必要があります。 拡張機能で使用される GitHub URL の変更を参照してください。

3.        GitHubで認証するように求められたら、指示に従ってアカウントにサインインします。 完了したら、GitHub認証から開く許可を求めるメッセージが表示される場合があります。Visual Studio Codeで「**開く**」をクリックしてください。
   

コントローラー リポジトリの名前は、 CodeQL 拡張機能の設定に保存されます。 コントローラー リポジトリを編集する方法については、「設定のカスタマイズ」を参照してください。

MRVA を使用した大規模なクエリの実行

1. 既定では、[バリアント分析リポジトリ] ビューには、分析する言語の GitHub.com の上位 10 個、上位 100 個、上位 1000 個のパブリック リポジトリの既定のリストが表示されます。 コントローラー リポジトリが SUBDOMAIN.ghe.com でホストされている場合、これらのリストは使用できません。

2. 必要に応じて、新しいリポジトリ、組織、リストを追加できます。

   1. [バリアント分析リポジトリ] ビューで、[+] をクリックして新しいデータベースを追加します。

   2. ドロップダウン メニュー から、 GitHub リポジトリ または 組織または所有者のすべてのリポジトリから GitHub 選択します。

   3. フィールドに、使用するリポジトリまたは組織の識別子を入力します。

3. クエリを実行する1つ以上のリポジトリを選択してください。

   

4. 実行するクエリを開き、クエリ ファイルを右クリックし、[ CodeQL: バリアント分析の実行 ] を選択してバリアント分析を開始します。

単一の GitHub リポジトリまたは組織を分析用に選択する

1. [バリアント分析リポジトリ] ビューで、[+] をクリックして新しいデータベースを追加します。

2. ドロップダウン メニュー から、 GitHub リポジトリ または 組織または所有者のすべてのリポジトリから GitHub 選択します。

3. フィールドに、使用するリポジトリまたは組織の識別子を入力します。

エラーと警告

MRVA を実行すると、エラーと警告が 2 つの主要な場所に表示されます。

•         Visual Studio Code errors: CodeQL パックの作成と GitHub への分析の送信に関する問題は、アプリケーションの右下隅に Visual Studio Code エラーとして報告されます。 情報は、[問題] ビューでも確認できます。
  

• バリアント分析結果: バリアント分析の実行に関する問題は、このビューで報告されます。

結果の検討

          GitHubでバリアント分析を実行するワークフローが実行されるとすぐに、[バリアント分析結果] ビューが開き、準備ができたら結果が表示されます。 このビューを使用すると、進行状況の監視、エラーの確認、コントローラー リポジトリ内のワークフロー ログへのアクセスを行うことができます。

バリアント分析の実行がスケジュールされている場合、[結果] ビューは自動的に開きます。 最初に、このビューには、分析用にスケジュールされたすべてのリポジトリの一覧が表示されます。 各リポジトリが分析されると、ビューが更新され、結果の数の概要が表示されます。 リポジトリの詳細な結果 (結果パスを含む) を表示するには、リポジトリ名をクリックします。

リポジトリごとに、次の情報が表示されます。

• クエリで見つかる結果の数

• リポジトリの表示範囲

• 分析がまだ実行中か完了しているか

• リポジトリが持つ星の数 GitHub

リポジトリの結果の表示

1. リポジトリ名をクリックすると、各結果の概要が表示されます。

2.        GitHubのソース ファイルへのリンクを使用して、各結果で使用可能な情報を確認します。 データ フロー クエリの場合は、[パスの表示] リンクもあります。
   

   

結果をエクスポートする

結果をエクスポートしてさらに分析したり、コラボレーターと検討したりすることができます。 [結果] ビューで、[結果の エクスポート ] をクリックして、結果を GitHub のシークレット gist またはワークスペース内の Markdown ファイルにエクスポートします。

リポジトリのカスタム リストの作成

          CodeQL 分析には、クエリを実行する CodeQL データベースが常に必要です。 リポジトリの一覧に対してバリアント分析を実行すると、クエリは現在、 CodeQL データベースをダウンロードできるリポジトリに対してのみ実行されます。 リポジトリをバリアント分析に使用できるようにする最善の方法は、code scanningでCodeQLを有効にすることです。 

          code scanningを使用してCodeQLを有効にする方法については、[AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning/configuring-default-setup-for-code-scanning) を参照してください。

1. [バリアント分析リポジトリ] ビューで、[リストの追加] アイコンをクリックします。

   

2. 新しいリストの名前を入力し、Enterキーを押します。

3. ビューでリストを選択し、[+] をクリックしてリポジトリをリストに追加します。

リポジトリのカスタム リストの管理

リスト名またはリスト内のリポジトリ名を右クリックし、コンテキスト メニューからオプションを選択することで、カスタム リストを管理および編集できます。

カスタム リストは、ワークスペース内の databases.json ファイルに格納されます。 このファイルを Visual Studio Codeで直接編集する場合は、ビュー ヘッダーで {} をクリックして開くことができます。

たとえば、クエリの結果を含むリポジトリのセットを引き続き分析する場合は、[バリアント分析結果] ビューの [リポジトリ リストのコピー] をクリックして、結果を含むリポジトリのみの一覧を JSON としてクリップボードに追加します。

次のスニペットの例では、my-organization/my-repository にクエリの結果が含まれています。

{
    "name": "new-repo-list",
    "repositories": [
        "my-organization/my-repository"
    ]
}

その後、[バリアント分析リポジトリ] ビューで簡単にアクセスできるように、new-repo-list へリポジトリの databases.json を挿入します。

          GitHubコード検索を使用してリポジトリをカスタム リストに追加する

          CodeQL拡張機能でコード検索を直接使用して、GitHubのリポジトリのサブセットをカスタム リストに追加できます。

たとえば、railsにGitHub組織内のすべてのリポジトリを追加するには、org:railsを検索します。

検索を行うごとに、最大 1,000 個のリポジトリをカスタム リストに追加できます。

1. [バリアント分析リポジトリ] ビューで、リポジトリを追加するリストを選択します。 新しいリストを作成することも、リポジトリが既に含まれている既存のリストを選択することもできます。

2. 選択した一覧を右クリックし、[コード検索を使用して リポジトリ GitHub 追加] をクリックします。

3. アプリケーションの上部に表示されるポップアップで、検索バーの下にあるドロップダウンの選択肢から検索する言語を選択します。

4. 検索バーに、使用する検索クエリを入力し、Enter キーを押します。

テキスト Searching for repositories... が表示されたボックスで、アプリケーションの右下隅に検索の進行状況を表示できます。 [キャンセル] をクリックすると、リポジトリは一覧に追加されません。 完了すると、結果のリポジトリが [バリアント分析リポジトリ] ビューのカスタム リストの下のドロップダウンに表示されます。

結果として得られるリポジトリの中には、CodeQLデータベースを持たないものもあれば、CodeQLのVisual Studio Code拡張機能によるアクセスを許可しないものもあります。 一覧で分析を実行すると、[バリアント分析結果] ビューに、分析されたリポジトリ、アクセスが拒否されたリポジトリ、 CodeQL データベースがなかったリポジトリが表示されます。

セルフホステッド ランナーに対する複数リポジトリバリアント分析を使用した CodeQL クエリの実行

セルフホステッド ランナーに対して複数リポジトリバリアント分析を使用して CodeQL クエリを実行するには、まず、コントローラー リポジトリにセルフホステッド ランナーが追加されていることを確認するか、コントローラー リポジトリが組織レベルまたはエンタープライズ レベルのランナーにアクセスできることを確認する必要があります。

次に、使うセルフホステッド ランナーの JSON 形式のラベル一覧を含め、MRVA_RUNNER_OS という新しいアクション リポジトリ変数をコントローラー リポジトリに追加する必要があります。 例えば次が挙げられます。

["self-hosted", "macOS", "ARM64"]

詳細については、「自己ホストランナーの追加」および「グループを使用してセルフホストランナーへのアクセスを管理する」を参照してください。

セルフホステッド ランナー上でマルチリポジトリ バリアント分析を含むクエリを実行した場合、分析は完全にセルフホステッド ランナー上で実行されます。 新しいワークフローを作成する必要はありませんが、CodeQL拡張機能のVisual Studio Codeがコントローラー リポジトリとして使用するリポジトリを指定する必要があります。 各リポジトリの分析が完了すると、結果が VS Code に送信され、表示されます。