CodeQL クエリの実行

CodeQL データベースに対してクエリを実行し、結果を Visual Studio Code で表示できます。

この記事の内容

CodeQL クエリの実行について

github/codeql リポジトリには、多数のクエリ例が含まれています。 ワークスペース内の既存のクエリには、[クエリ] ビューを使用してアクセスできます。

前提条件

コードベースを分析するには、コードから抽出された CodeQL データベースに対してクエリを実行するため、拡張機能で機能するデータベースを選択する必要があります。 データベースは、ローカルで (ZIP アーカイブまたはアーカイブされていないフォルダーから)、パブリック URL から、または GitHub.com のプロジェクトの URL から選択できます。 詳しくは、「CodeQL データベースの管理」を参照してください。

単一クエリの実行

  1. サイドバーで、[クエリ] ビューを開きます。

  2. 選択したデータベースに対してクエリを実行するには、目的のクエリにカーソルを合わせ、[ローカル クエリの実行] アイコンをクリックします。

[ローカル クエリの実行] ボタンが濃いオレンジ色で囲まれた [クエリ] ビューのスクリーンショット。

CodeQL 拡張機能は、現在のデータベースに対してクエリを実行し、アプリケーションの右下隅で進行状況を報告します。 結果の準備ができたら、CodeQL [クエリ結果] ビューに表示されます。

クエリの実行に問題がある場合は、アプリケーションの右下隅に通知が表示されます。 この通知には、エラー メッセージに加えて、問題を解決する方法の詳細が含まれています。

ディレクトリ内のすべてのクエリの実行

ディレクトリ内のすべてのクエリを実行できます。

  1. サイドバーで、[クエリ] ビューを開きます。

  2. クエリの目的のディレクトリにカーソルを合わせ、[ローカル クエリの実行] アイコンをクリックします。

選択したクエリの実行

1 つのコマンドで複数のクエリを実行できます。

  1. [エクスプローラー] に移動します。

  2. クエリを含む複数のファイルまたはフォルダーを選択します。

  3. 右クリックして、[CodeQL: 選択したファイルでクエリを実行する] を選択します。

セットアップなしでクエリを実行する

新しいクエリで作業する場合は、[クイック クエリ] タブを開くと、ワークスペースに .ql ファイルを保存しなくても、コードを簡単に実行して結果を表示できます。 VS Code Command Palette から [CodeQL: クイック クエリ] を実行し、次に [CodeQL: 選択したデータベースに対してクエリを実行する] を使用してクエリを実行します。

現在のセッションで実行したすべてのクイック クエリは、[クエリ履歴] ビューで確認できます。 エントリをクリックすると、結果を生成したクイック クエリの正確なテキストが表示されます。 詳細については、「クエリ履歴の表示」を参照してください。

クイック クエリに問題がなければ、後でアクセスできるように、CodeQL パックに保存する必要があります。 詳しくは、「CodeQL パックを使った分析のカスタマイズ」を参照してください。

クエリまたはライブラリの特定の部分を実行する

これは、クエリまたはライブラリをデバッグしていて、間違っている部分を見つけたい場合に役立ちます。

[CodeQL: 選択したデータベースに対してクエリを実行する] を使用してクエリ全体 (select 句とクエリ述語) を実行する代わりに、[CodeQL: 簡単な評価] を使用して、.ql または .qll のファイルの特定の部分を実行できます。

[CodeQL: 簡単な評価] では、クエリ全体ではなく、選択したコード スニペットが評価され、その選択結果が [結果] ビューに表示されます。

簡単な評価に使用できるターゲットは次のとおりです。

  • CodeQL エンティティの名前 (クラスや述語など) を選択して、そのエンティティを評価します。

  • 自由変数を含む数式または式を選択して、その数式または式を評価する。

たとえば、次のスニペットでは、簡単な評価のために述語名 foo または数式 s = "bar" を選択できます。

predicate foo(string s) { s = "bar" }

複数のデータベースに対するクエリの実行

これは、複数のコードベースでクエリをテストしたり、複数のプロジェクトで脆弱性を見つけたりする場合に役立ちます。

  1. クエリ (.ql) ファイルを開きます。

  2. 右クリックして、[CodeQL: 複数のデータベースに対してクエリを実行する] を選択します。

  3. ドロップダウン メニューから、クエリを実行する対象のデータベースを選択します。

クエリ履歴の表示

現在のセッションで実行したクエリを表示するには、[クエリ履歴] ビューを開きます。

[クエリ履歴] ビューには、クエリが実行された日時、クエリの名前、実行されたデータベース、クエリの実行にかかった時間などの情報が含まれます。

  • 表示される情報をカスタマイズするには、エントリを右クリックし、[名前の変更] を選択します。

  • 必要に応じて、言語セレクターを使用して言語でビューをフィルター処理します。 詳細については、「言語によるデータベースとクエリのフィルター処理」を参照してください。

  • エントリをクリックして対応する結果を表示し、ダブルクリックしてクエリ自体をエディターに表示します (または、右クリックして [クエリの表示] を選択します)。

  • 特定のエントリの結果を生成した正確なテキストを表示するには、そのエントリを右クリックし、[クエリ テキストの表示] を選択します。 クエリ ファイルは前回実行してから変更されている可能性があるため、これは [クエリの表示] とは異なる場合があります。

  • ビューからクエリを削除するには、削除するすべてのクエリを選択し、右クリックして [削除] を選択します。

クエリ結果を理解する

  1. [クエリ履歴] ビューでクエリをクリックすると、その結果が [結果] ビューに表示されます。

    注: クエリに応じて、CSV、CodeQL CLI SARIF 出力、DIL 形式など、さまざまなビューを選択することもできます。 たとえば、DIL 形式を表示するには、結果を右クリックし、[DIL の表示] を選択します。 使用可能な出力ビューは、クエリの形式とメタデータによって決まります。 詳しくは、「CodeQL クエリ」を参照してください。

  2. [結果] ビューのドロップダウン メニューを使用して、表示する結果、および表示するフォーム (書式設定された警告メッセージや生の結果のテーブルなど) を選択します。

  3. 特定の列のエントリで結果を並べ替えるには、列ヘッダーをクリックします。

結果がソース コード要素にリンクされている場合は、それをクリックしてソースに表示できます。

ソース コードで標準コード ナビゲーション機能を使用するには、要素を右クリックし、[定義に移動] または [参照に移動] コマンドを使用します。 これにより、アクティブ ファイルに対して CodeQL クエリが実行されます。これには数秒かかる場合があります。 このクエリはファイルごとに 1 回実行する必要があるため、同じファイルからの追加の参照は高速になります。

注: 古いデータベースを使用している場合、[定義に移動] や [参照に移動] などのコード ナビゲーション コマンドが機能しない場合があります。 コード ナビゲーションを使用するには、CodeQL CLI を使用して、データベースを解凍し、解凍したデータベースで codeql database cleanup <database> を実行してみてください。 次に、データベースを Visual Studio Code 再度追加します。 詳しくは、「database cleanup」を参照してください。

クエリ結果の比較

クエリを記述またはデバッグするときは、変更が結果にどのように影響するかを確認すると便利です。 2 つの結果セットを比較して、変更された内容を正確に確認できます。 結果を比較するには、2 つのクエリを同じデータベースで実行する必要があります。

  1. [クエリ履歴] ビューでクエリを右クリックし、[結果の比較] を選択します。

  2. [クイック ピック] メニューには、比較対象のすべての有効なクエリが表示されます。 クエリを選択します。

  3. [比較] ビューには、2 つのクエリの結果の違いが表示されます。

トラブルシューティング

特定のクエリを実行したログを表示するには、[クエリ履歴] ビューでクエリを右クリックし、[クエリ ログの表示] を選択 します。 拡張子を VS Code で開くのにログ ファイルが大きすぎる場合は、ファイルがエクスプローラーに表示されるため、外部プログラムで開くことができます。

クエリのコンパイルと実行の詳細、およびデータベースのアップグレードに関する情報については、CodeQL クエリ サーバー ログをチェックします。 詳しくは、「ログへのアクセス」を参照してください。

既定では、拡張機能は各ワークスペース セッションの後にログを削除します。 この動作をオーバーライドするには、クエリ サーバー ログのカスタム ディレクトリを指定します。 詳しくは、「設定のカスタマイズ」を参照してください。

CodeQL: クエリ サーバーの再起動コマンドを使用して、クエリ サーバーを再起動できます。 これにより、CodeQL セッション履歴に影響を与えずにサーバーが再起動されます。 拡張機能が使用しているファイルに対して外部変更を行う場合は、クエリ サーバーを再起動する必要がある可能性が最も高くなります。 たとえば、VS Code で開いている CodeQL データベースを再生成します。 ログの問題に加えて、コードの強調表示のエラー、正しくない結果の合計、またはクエリが実行されているという重複する通知も表示される場合があります。

次のステップ

必要に応じて、拡張機能を使用して独自のカスタム クエリを作成できます。 詳しくは、「カスタム クエリの作成」を参照してください。

多数の CodeQL データベースで大規模に分析を実行する方法については、「マルチリポジトリ バリアント分析を使用した大規模な CodeQL クエリの実行」を参照してください。