CodeQL クエリの実行

          CodeQL クエリの実行について

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

前提条件

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

単一クエリの実行

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

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

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

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

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

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

サイドバーで、[クエリ] ビューを開きます。
クエリの目的のディレクトリにカーソルを合わせ、[ローカルクエリの実行] アイコンをクリックします。

選択したクエリの実行

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

ファイルエクスプローラーに移動します。
クエリを含む複数のファイルまたはフォルダーを選択します。
右クリックし、[ CodeQL: 選択したファイルでクエリを実行する] を選択します。

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

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

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

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

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

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

          **
          CodeQL: 選択したデータベースに対してクエリを実行**してクエリ全体 ([select 句](https://codeql.github.com/docs/ql-language-reference/queries/#select-clauses)と[クエリ述語](https://codeql.github.com/docs/ql-language-reference/queries/#query-predicates)) を実行する代わりに、**CodeQL: クイック評価**を使用して、`.ql`または`.qll` ファイルの特定の部分を実行できます。

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

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

        CodeQL エンティティの名前 ([クラス](https://codeql.github.com/docs/ql-language-reference/types/#classes)や[述語](https://codeql.github.com/docs/ql-language-reference/predicates/#predicates)など) を選択して、そのエンティティを評価します。

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

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

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

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

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

クエリ (.ql) ファイルを開きます。
右クリックし、[ CodeQL: 複数のデータベースに対するクエリの実行] を選択します。
ドロップダウンメニューから、クエリを実行する対象のデータベースを選択します。

クエリ履歴の表示

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

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

表示される情報をカスタマイズするには、エントリを右クリックし、[名前の変更] を選択します。
必要に応じて、言語セレクターを使用して言語でビューをフィルター処理します。詳しくは、「言語によるデータベースとクエリのフィルター処理」を参照してください。
エントリをクリックして対応する結果を表示し、ダブルクリックしてクエリ自体をエディターに表示します (または、右クリックして [クエリの表示] を選択します)。
特定のエントリの結果を生成した正確なテキストを表示するには、そのエントリを右クリックし、[クエリテキストの表示] を選択します。クエリファイルは前回実行してから変更されている可能性があるため、これは [クエリの表示] とは異なる場合があります。
ビューからクエリを削除するには、削除するすべてのクエリを選択し、右クリックして [削除] を選択します。

クエリ結果を理解する

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

メモ

クエリに応じて、CSV、CodeQL CLI SARIF 出力、DIL 形式など、異なるビューを選択することもできます。たとえば、DIL 形式を表示するには、結果を右クリックし、[DIL の表示] を選択します。使用可能な出力ビューは、クエリの形式とメタデータによって決まります。詳細については、「 CodeQL クエリ」を参照してください。
[結果] ビューのドロップダウンメニューを使用して、表示する結果、および表示するフォーム (書式設定された警告メッセージや生の結果のテーブルなど) を選択します。
特定の列のエントリで結果を並べ替えるには、列ヘッダーをクリックします。

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

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

メモ

古いデータベースを使用している場合、[Go to Definition] や [Go to References] などのコードナビゲーションコマンドが機能しない場合があります。コードナビゲーションを使用するには、codeql database cleanup <database>を使用して、データベースを解凍し、解凍したデータベースでCodeQL CLIを実行してみてください。次に、データベースを Visual Studio Codeに再追加します。詳細については、「データベースのクリーンアップ」を参照してください。

クエリ結果の比較

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

[クエリ履歴] ビューでクエリを右クリックし、[結果の比較] を選択します。
[クイックピック] メニューには、比較対象のすべての有効なクエリが表示されます。クエリを選択します。
[比較] ビューには、2 つのクエリの結果の違いが表示されます。

Troubleshooting

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

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

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

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

次のステップ

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

この記事で