VS CodeでCodeQLを使いこなす
1. はじめに
コードレビューでセキュリティ脆弱性を見逃していないか、不安を感じたことはありませんか。SQLインジェクションやXSS、パストラバーサルといった脆弱性は、手動レビューだけでは発見が難しいケースも少なくありません。
CodeQL for Visual Studio Codeは、こうした課題に対する実用的なソリューションです。GitHubが開発したこのツールを使うことで、コードを静的に解析し、データフローを追跡して潜在的な脆弱性を検出できます。本記事では、その具体的な使い方と、実務で活用するためのポイントを解説します。
2. CodeQL for VS Codeとは
CodeQLは、コードをデータベースとして扱い、クエリ言語を使って解析する静的解析ツールです。VS Code拡張機能として提供されており、開発環境から直接セキュリティ分析を実行できます。
2.1. 主要な特徴
- クエリベースの解析: SQLのようなクエリ言語でコードパターンを検索
- データフロー追跡: ソースからシンクまでのデータの流れを可視化
- 大規模分析: 最大1,000リポジトリに対して一度にクエリを実行
- カスタマイズ可能: 独自のクエリやモデルを作成して分析精度を向上
2.2. サポート言語
C/C++、C#、Go、Java/Kotlin、JavaScript/TypeScript、Python、Ruby、Swift、Rustに対応しています。
3. セットアップから実行まで
3.1. 環境構築
3.1.1. インストール方法
拡張機能のインストールには3つの方法があります：
- VS Code Marketplaceから：ブラウザで「CodeQL」を検索してインストール
- 拡張機能ビュー内で検索：VS Code内の拡張機能ビューから直接インストール
-
VSIXファイルから：
github/vscode-codeqlリポジトリからVSIXファイルをダウンロードして手動インストール
3.1.2. ワークスペースの準備
推奨される方法は、CodeQLスターターワークスペースを使用することです：
# スターターワークスペースのクローン（サブモジュールを含む）
git clone --recursive https://github.com/github/vscode-codeql-starter.git
# または、クローン後にサブモジュールを初期化
git submodule update --init --remote
ワークスペースを開くには、vscode-codeql-starter.code-workspaceファイルを開きます。このワークスペースには、各言語用のカスタムクエリディレクトリとサンプルクエリが含まれています。
3.2. データベースの管理
CodeQLでコードを解析するには、まずCodeQLデータベースが必要です。
3.2.1. データベースの入手方法
GitHubから直接ダウンロード
GitHub.comは、20万以上のオープンソースリポジトリのCodeQLデータベースを保持しています。REST APIを使用してダウンロードできます。
VS Code拡張機能から選択
- 「Databases」ビューのタイトルバーにカーソルを合わせる
- 適切なアイコンを選択：
- ローカルファイル（ZIPまたは展開済みフォルダ）
- 公開URL
- GitHubプロジェクトのURL
3.2.2. 言語フィルタの活用
「Language」ビューで言語フィルタを適用すると、特定の言語のデータベースとクエリのみが表示されます。大規模なワークスペースで作業する際に便利です。
3.3. クエリの実行
3.3.1. 単一クエリの実行
実行手順：
- サイドバーの「Queries」ビューを開きます
- 実行したいクエリにカーソルを合わせます
- 「Run local query」アイコンをクリックします
- 右下に進捗状況が表示されます
- 完了すると「Query Results」ビューに結果が表示されます
3.3.2. ディレクトリ内の全クエリ実行
複数のクエリを一度に実行したい場合：
- 「Queries」ビューでディレクトリにカーソルを合わせる
- 「Run local queries」アイコンをクリック
3.3.3. 複数ファイルの選択実行
- ファイルエクスプローラーで複数のファイル/フォルダを選択
- 右クリックして「CodeQL: Run Queries in Selected Files」を選択
3.3.4. クイッククエリの活用
新しいクエリを試す際、ファイルを保存せずに実行できます：
- コマンドパレットから「CodeQL: Quick Query」を実行
- クエリを記述
- 「CodeQL: Run Query on Selected Database」で実行
クイッククエリは「Query History」ビューで確認でき、正確なテキストを後から参照できます。満足のいく結果が得られたら、CodeQLパックとして保存することをお勧めします。
3.3.5. 部分的な評価（デバッグ用）
クエリやライブラリの特定部分のみを評価することで、デバッグが効率化できます：
-
.qlまたは.qllファイルで評価したい部分を選択 - コマンドパレットから「CodeQL: Quick Evaluation」を実行
評価対象として選択できるもの：
- CodeQLエンティティ（クラスや述語）の名前
- 自由変数を含む式や論理式
例：
predicate foo(string s) { s = "bar" }
このコードでは、述語名fooまたは式s = "bar"を選択して評価できます。
3.3.6. 複数データベースでの実行
クエリを複数のコードベースでテストしたり、複数のプロジェクトで脆弱性を探したりする場合に便利です：
- クエリ（
.ql）ファイルを開く - 右クリックして「CodeQL: Run Query on Multiple Databases」を選択
- ドロップダウンメニューから対象データベースを選択
3.4. クエリ履歴の管理
「Query History」ビューには、現在のセッションで実行したクエリが記録されます。
3.4.1. 表示される情報
- クエリの実行日時
- クエリ名
- 実行対象のデータベース
- 実行時間
3.4.2. カスタマイズ
- エントリを右クリックして「Rename」で表示情報を変更できます
- 言語セレクターで言語別にフィルタリングできます
- 不要なクエリは選択して右クリックから「Delete」で削除できます
3.4.3. クエリテキストの確認
エントリを右クリックして「View Query Text」を選択すると、そのクエリで実際に実行されたテキストが表示されます。これは、クエリファイルが後から変更された場合に、実際に実行された内容を確認するのに役立ちます。
3.5. 結果の理解と活用
3.5.1. 結果ビューの操作
「Query History」でクエリをクリックすると、「Results」ビューに結果が表示されます。
表示形式の選択
ドロップダウンメニューから以下の形式を選択できます：
- フォーマットされたアラートメッセージ
- 生の結果テーブル
- CSV形式
- CodeQL CLI SARIF出力
- DIL形式（右クリックして「View DIL」を選択）
結果の並び替え
列ヘッダーをクリックすると、その列でソートされます。
ソースコードへのジャンプ
結果がソースコード要素にリンクしている場合、クリックするとソースが表示されます。
3.5.2. コードナビゲーション機能
ソースコード内で要素を右クリックして、以下のコマンドが使用できます：
- Go to Definition：定義へジャンプ
- Go to References：参照箇所の表示
注意：これらのコマンドは、アクティブなファイルに対してCodeQLクエリを実行します。初回は数秒かかる場合がありますが、同じファイルからの追加の参照は高速です。
古いデータベースでこれらのコマンドが動作しない場合は、データベースを展開してCodeQL CLIでcodeql database cleanup <database>を実行し、再度VS Codeに追加してください。
3.5.3. 結果の比較
クエリを書いたりデバッグしたりする際、変更が結果にどう影響するかを確認することは重要です。
比較手順：
- 「Query History」ビューでクエリを右クリック
- 「Compare Results」を選択
- クイックピックメニューから比較対象のクエリを選択
- 「Compare」ビューで差分を確認
注意：比較するには、両方のクエリが同じデータベースで実行されている必要があります。
3.6. トラブルシューティング
3.6.1. クエリログの確認
クエリ実行時の詳細なログを確認するには：
- 「Query History」ビューでクエリを右クリック
- 「Show Query Log」を選択
ログファイルが大きすぎてVS Codeで開けない場合は、ファイルエクスプローラーで表示されるので、外部プログラムで開くことができます。
3.6.2. CodeQL Query Serverログ
クエリのコンパイルや実行の詳細、データベースアップグレードの情報は「CodeQL Query Server」ログで確認できます。「Output」ビューの「CodeQL Query Server」タブを参照してください。
3.6.3. クエリサーバーの再起動
外部からの変更（データベースの再生成など）が反映されない場合、コマンドパレットから「CodeQL: Restart Query Server」を実行します。これにより、セッション履歴に影響を与えることなくクエリサーバーが再起動されます。
次のような症状が見られる場合に有効です：
- コードハイライトのエラー
- 不正確な結果総数
- クエリ実行中の重複通知
4. データフロー解析：パスクエリの活用
パスクエリは、@kind path-problemプロパティを持つCodeQLクエリです。データがプログラム内をどのように流れるかを追跡し、潜在的なセキュリティ脆弱性を強調表示します。
4.1. パスクエリの実行
実行手順：
- VS Codeでパスクエリを開く
- ウィンドウ内で右クリックし、「CodeQL: Run Query on Selected Database」を選択
- クエリが完了すると、「Results」ビューに結果が表示される（ドロップダウンで
alertsを選択） - 結果を展開してデータが通るステップを確認
- 各ステップをクリックしてソースコードにジャンプし、問題を詳しく調査
4.2. データフロー解析の仕組み
CodeQLは、以下の要素を追跡します：
- ソース（Source）：機密データや外部入力の発生源
- シンク（Sink）：データが到達する危険な場所（データベースクエリ、ファイルシステム操作など）
- サニタイザー（Sanitizer）：データを安全にする処理
パスクエリは、ソースからシンクまでのすべての経路を列挙し、サニタイザーを通過していない危険な経路を報告します。
5. 大規模解析：Multi-Repository Variant Analysis（MRVA）
MRVAを使用すると、VS CodeからGitHub上の最大1,000のリポジトリに対してCodeQLクエリを実行できます。
5.1. MRVAの仕組み
5.2. 前提条件
5.2.1. コントローラーリポジトリの設定
MRVAを実行するには、コントローラーリポジトリが必要です：
- 最低1つのコミットが必要
- パブリックリポジトリのみを解析する場合は「public」でOK（無料）
- プライベート/インターナルリポジトリを解析する場合は「private」が必要
プライベート/インターナルリポジトリの解析に使用するActions分数は、無料枠を超えるとリポジトリオーナーに課金されます。
5.2.2. コントローラーリポジトリのセットアップ
- 「Variant Analysis Repositories」ビューで「Set up controller repository」をクリック
- GitHubのリポジトリのオーナーと名前を入力（形式：
owner/name） - 認証が必要な場合は、指示に従ってGitHubアカウントにサインイン
- GitHub Authenticationがポップアップ表示されたら「Open」をクリック
コントローラーリポジトリ名は拡張機能の設定に保存されます。
5.3. MRVAの実行
5.3.1. デフォルトリストの使用
「Variant Analysis Repositories」ビューには、デフォルトで以下のリストが表示されます：
- Top 10パブリックリポジトリ
- Top 100パブリックリポジトリ
- Top 1000パブリックリポジトリ
注意：コントローラーリポジトリがGitHub Enterprise Serverでホストされている場合、これらのリストは利用できません。
5.3.2. カスタムリストの追加
単一リポジトリまたは組織の追加
- 「Variant Analysis Repositories」ビューで
+をクリック - ドロップダウンから選択：
- 「From a GitHub repository」（単一リポジトリ）
- 「All repositories of GitHub org or owner」（組織のすべてのリポジトリ）
- リポジトリまたは組織の識別子を入力
クエリの実行
- 対象のリポジトリまたはリストを選択
- 実行したいクエリを開く
- クエリファイル内で右クリック
- 「CodeQL: Run Variant Analysis」を選択
解析を中断するには、「Variant Analysis Results」ビューで「Stop query」をクリックします。
5.4. カスタムリストの管理
5.4.1. 基本的な管理操作
カスタムリストは右クリックメニューから管理できます：
- リスト名を右クリック：リストの名前変更、削除
- リポジトリ名を右クリック：リポジトリの削除
5.4.2. databases.jsonファイルでの直接編集
より高度な管理が必要な場合は、databases.jsonファイルを直接編集できます：
- ビューヘッダーの
{ }アイコンをクリック - JSON形式でリストとリポジトリを編集
例：
{
"name": "新規リポジトリリスト",
"repositories": [
"tanaka-org/tanaka-repository"
]
}
5.4.3. 結果からリストを作成
「Variant Analysis Results」ビューで「Copy repository list」をクリックすると、結果があったリポジトリのみのリストがJSON形式でクリップボードにコピーされます。これをdatabases.jsonに貼り付けて新しいリストとして保存できます。
5.5. GitHub Code Searchの活用
GitHub Code Search APIを使用して、条件に合うリポジトリをカスタムリストに追加できます。
注意：レガシーコード検索構文を使用します。1回の検索で最大1,000リポジトリまで追加可能です。
手順：
- 「Variant Analysis Repositories」ビューで対象リストを選択（新規作成または既存リスト）
- リストを右クリックして「Add repositories with GitHub code search」を選択
- 検索バーの下のドロップダウンで言語を選択
- 検索クエリを入力してEnterキーを押す
例：org:railsと入力すると、rails組織のすべてのリポジトリが追加されます。
検索の進捗状況は右下に表示されます。完了すると、結果がリストに追加されます。
注意：結果の一部はCodeQLデータベースを持たない場合や、アクセスが許可されていない場合があります。解析実行時に「Variant Analysis Results」ビューで確認できます。
5.6. セルフホストランナーでの実行
セルフホストランナーでMRVAを実行するには：
- コントローラーリポジトリにセルフホストランナーを追加するか、組織/エンタープライズレベルのランナーへのアクセスを確保
- コントローラーリポジトリのActionsリポジトリ変数に
MRVA_RUNNER_OSを追加 - 変数の値としてJSON形式でランナーのラベルリストを設定
例：
["self-hosted", "macOS", "ARM64"]
注意：MRVA_RUNNER_OSは、コントローラーリポジトリの設定でActionsリポジトリ変数として設定する必要があります。環境変数やActionsシークレット、ワークフローの.ymlファイル内には設定できません。
5.7. 結果の確認
5.7.1. 進捗モニタリング
「Variant Analysis Results」ビューが自動的に開き、リアルタイムで進捗を確認できます：
- 各リポジトリの解析状況
- 発見された結果の数
- リポジトリの可視性
- スター数
5.7.2. 詳細結果の表示
リポジトリ名をクリックすると、各結果の詳細が表示されます。データフロークエリの場合、「Show paths」リンクも表示されます。
5.7.3. 結果のエクスポート
「Results」ビューで「Export results」をクリックすると、以下の形式でエクスポートできます：
- GitHubのシークレットgist
- ワークスペース内のMarkdownファイル
6. モデルエディタ：カスタム依存関係のモデリング
CodeQLモデルエディタを使用すると、デフォルトでサポートされていないカスタムライブラリやフレームワークをモデル化できます。
注意：現在パブリックプレビュー中で、C/C++、C#、Java/Kotlin、Python、Ruby、Rustに対応しています。モデルエディタはC#、Java/Kotlin、Python、Rubyの依存関係モデリングをサポートしています。
モデルエディタの概要
モデルエディタには2つのモードがあります：
アプリケーションモード（デフォルト）
選択したCodeQLデータベースが使用する外部フレームワークをリストアップし、外部APIへの/からのすべての呼び出しを表示します。特定のコードベースのCodeQL結果を改善するのに最適です。
6.1.2. 依存関係モード
選択したCodeQLデータベース内のすべての公開アクセス可能なAPIを識別します。各公開APIのモデリングをガイドし、完全にモデル化すると、その依存関係を使用するすべてのコードベースのCodeQL解析を改善できます。
6.2. モデルエディタの起動
手順：
- VS CodeでCodeQLワークスペースを開く（例：vscode-codeql-starterワークスペース）
- スターターワークスペースを使用している場合、
qlサブモジュールをmainから更新 - サイドバーの「QL」をクリックしてCodeQL拡張機能を表示
- 「Databases」ビューでモデル化元のCodeQLデータベースを選択
- 「Method Modeling」ビューで「Start modeling」をクリック（またはコマンドパレットから「CodeQL: Open Model Editor (Beta)」を実行）
テレメトリクエリが実行され、APIが識別されると、エディタに表示されます。
ヒント：「Method Modeling」ビューをプライマリサイドバーからセカンダリサイドバーに移動すると、モデリング時により多くのスペースを確保できます。
6.3. アプリケーションモード：外部API呼び出しのモデリング
特定のコードベースでCodeQL結果の精度を向上させたい場合に使用します。CodeQLでサポートされていないフレームワークやライブラリをコードベースが使用している場合に有効です。
例として、オープンソースJavaプロジェクト「sofa-jraft」を使用します。
6.3.1. モデリング手順
- VS Codeで改善したいCodeQLデータベースを選択
- CodeQLモデルエディタを表示（デフォルトでアプリケーションモード）
- 外部APIを展開して、コードベースから外部依存関係への呼び出しリストを表示
- API呼び出しまたはメソッドに関連付けられた「View」をクリックして、コードベースでの使用箇所を確認
- 「Methods Usage」ビューで各呼び出しをクリックして、モデル化方法を決定
- 「Method Modeling」ビューの「Model Type」ドロップダウンで適切なモデルタイプを選択
6.3.2. モデルタイプの選択
選択したモデルタイプに応じて、以下のフィールドが更新されます：
- Source（ソース）：「Output」要素を選択
- Sink（シンク）：「Input」要素を選択
- Flow summary（フロー要約）：「Input」と「Output」要素を選択
最後に、モデルの「Kind」（データフローの種類）を定義します。
6.3.3. モデルの保存
モデリングが完了したら、メインモデルエディタを表示して「Save all」または「Save」をクリックします。各拡張されたメソッドリストの右下に表示されます。モデル化されたメソッドのパーセンテージが更新されます。
モデルはワークスペースの.github/codeql/extensions/CODEQL-MODEL-PACKに保存されます（CODEQL-MODEL-PACKは選択したCodeQLデータベースの名前、つまり「リポジトリ名-言語」形式）。
モデルは外部APIごとに1つのYAMLデータ拡張ファイルとして保存されます。
例：
.github/codeql/extensions/sofa-jraft-java # モデルパックディレクトリ
models
jmh-core.model.yml # jmh-core@1.20への呼び出しをモデル化
rocksdbjni.model.yml # rocksdbjni@7.7.3への呼び出しをモデル化
6.4. 依存関係モード：公開APIのモデリング
組織内の複数のコードベースで使用されているフレームワークやライブラリをモデル化したい場合に使用します。モデルを作成してテストした後、GitHub Container registryにCodeQLモデルパックを公開して、組織全体で使用できます。
例として、オープンソースJavaプロジェクト「sofa-jraft」を使用します。
6.4.1. モデリング手順
- モデル化したいCodeQLデータベースを選択
- CodeQLモデルエディタを表示（デフォルトでアプリケーションモード）
- 「Model as dependency」をクリックして依存関係モードに切り替え
- パッケージを展開して利用可能なメソッドリストを表示
- メソッドに関連付けられた「View」をクリックして定義を確認
- モデル化方法を決定したら、「Model type」を定義
- 選択したモデルタイプに応じて残りのフィールドを設定（Source、Sink、Flow summary）
- データフローの「Kind」を定義
6.4.2. モデルの保存
モデリングが完了したら、「Save all」または「Save」をクリックします。モデル化された呼び出しのパーセンテージが更新されます。
モデルはワークスペースの.github/codeql/extensions/CODEQL-MODEL-PACKに保存されます。モデル化する各パッケージに対して個別のモデルファイルが作成されます。
例：
.github/codeql/extensions/sofa-jraft-java # モデルパックディレクトリ
models
com.alipay.sofa.jraft.option.model.yml # パッケージ内の公開メソッドをモデル化
com.alipay.sofa.jraft.rhea.options.model.yml
複数のフローを持つメソッドのモデリング
一部のメソッドは複数のデータフローをサポートしています。メソッドに関連するすべてのデータフローをモデル化することが重要です。そうしないと、メソッドの使用に関連するすべての潜在的な問題を検出できません。
手順：
- まず1つのデータフローをモデル化
- メソッド行の
+ボタンを使用して2つ目のデータフローモデルを指定
6.6. VS Codeでのモデルパックのテスト
作成したCodeQLモデルパックは、「Running Queries: Use Extension Packs」設定でテストできます。この方法はデータベースとvariant analysisリポジトリの両方で機能します。
6.6.1. 設定方法
ワークスペースの.github/codeql/extensionsディレクトリ内のモデルパックを使用してクエリを実行
settings.jsonを以下のように更新：
"codeQL.runningQueries.useExtensionPacks": "all"
モデルパックを使用せずにクエリを実行
settings.jsonを以下のように更新：
"codeQL.runningQueries.useExtensionPacks": "none"
6.6.2. 検証方法
モデルが正常に機能している場合、2つの異なる実行で結果に違いが見られるはずです。違いが見られない場合は、既知のバグを導入してモデルが期待どおりに動作することを確認する必要があるかもしれません。
7. CodeQLパックの管理
CodeQLパック（クエリパックとライブラリパック）を使用すると、クエリと依存関係を効率的に管理できます。
7.1. パック依存関係のインストール
- コマンドパレットから「CodeQL: Install Pack Dependencies」を実行
- 依存関係をインストールするパックを選択
7.2. CodeQLクエリパックのダウンロード
- コマンドパレットから「CodeQL: Download Packs」を実行
- すべてのコアクエリパックをダウンロードするか、特定のパックの完全な名前を入力
- 他のユーザーが作成したクエリパックもダウンロード可能
7.3. パックと依存関係の表示
- VS Codeで任意のCodeQLパックディレクトリのルートにある
qlpack.ymlファイルを開く -
dependenciesセクションで、パックが依存するライブラリを確認 - Intellisense機能を使用：要素にカーソルを合わせるとドキュメントが表示される
- 要素の完全な定義を表示：右クリックして「Go to Definition」を選択
- ライブラリパックが同じワークスペース内にある場合：ワークスペース内の定義に移動
- それ以外の場合：ダウンロードされた依存関係が保存されているパッケージキャッシュ内の定義が表示される
パッケージキャッシュは、デフォルトでホームディレクトリに保存される共有の場所です。
8. カスタムクエリの作成
注意：カスタムクエリの作成はオプションです。github/codeqlリポジトリには多数のサンプルクエリが含まれています。
8.1. クエリ作成の手順
- 拡張機能のサイドバーで「Queries」ビューを開く
- 「Create query」アイコンをクリック
- コマンドパレットでクエリのターゲット言語を選択
- 既存のディレクトリに作成しない場合、
codeql-custom-queries-LANGUAGEという名前のディレクトリが自動生成される（LANGUAGEは選択した言語名） -
example.qlというクエリテンプレートが既存または自動生成されたディレクトリに追加される - テンプレートでカスタムクエリを記述し、ファイルを保存
- クエリが完成したら、「Queries」ビューから実行
8.2. テンプレートの内容
クエリテンプレートには、選択した言語の標準ライブラリをインポートする記述が含まれています。これにより、すぐにその言語の解析を開始できます。
9. ソースコード構造の探索：AST Viewer
抽象構文木（AST）ビューアを使用すると、CodeQLデータベースのプログラム構造を視覚的に探索できます。
9.1. ASTについて
プログラムのASTは、プログラムの構文構造を表します。AST上のノードは、ステートメントや式などの要素を表します。CodeQLデータベースは、データベーススキーマを通じてこれらのプログラム要素と要素間の関係をエンコードします。
AST viewerはグラフ可視化ビューで構成され、CodeQLデータベース内のファイルのASTを探索できます。これにより、CodeQLクラスがソースファイルのどの部分に対応しているかを確認できます。
9.2. ASTの表示方法
注意：適切なクエリ（通常printAST.ql）がワークスペースにない場合、「CodeQL: View AST」コマンドは機能しません。これを修正するには、github/codeqlリポジトリのコピーをmainブランチから更新してください。この場合、クエリキャッシュが破棄される可能性があるため、次のクエリ実行が遅くなる場合があります。
手順：
- 拡張機能の「Databases」ビューを開く
- 探索したいデータベースを右クリック
- 「Add Database Source to Workspace」をクリック
- ファイルエクスプローラーでCodeQLデータベースのソースファイルに移動
- コマンドパレットから「CodeQL: View AST」を実行（これにより、アクティブなファイルに対してCodeQLクエリ（通常
printAST.ql）が実行されます。数秒かかる場合があります） - クエリが完了すると、ASTビューアにソースファイルの構造が表示される
- 矢印をクリックしてノードを展開し、ネストされた構造を確認
9.3. ASTビューアの操作
- ノードからソースへ：ASTビューアでノードをクリックすると、ソースコード内の対応する箇所にジャンプ
- ソースからノードへ：ソースコードのセクションをクリックすると、ASTビューアに対応するノードが表示される
10. クエリのテスト
クエリが期待した結果を生成することを確認するため、単体テストを実行できます。
10.1. テストビューの使用
CodeQL拡張機能は「Testing」ビューに自動的に登録されます。このビューは、現在のワークスペースで見つかったすべてのテストを表示し、ワークスペース内のテストを探索および実行するためのUIを提供します。
10.2. テストの実行手順
- VS Codeのサイドバーで「Testing」ビューを開く
- 特定のテストを実行：ファイル名またはフォルダ名にカーソルを合わせてプレイボタンをクリック
- ワークスペース内のすべてのテストを実行：ビュー上部のプレイボタンをクリック
- テストの実行に時間がかかりすぎる場合：ビュー上部のストップボタンをクリックしてキャンセル
10.3. 結果の確認
- アイコンがテストの合格/不合格を示す
- 失敗した場合：「Test Results」でテストをクリックして、期待される出力と実際の出力の違いを表示
- 実際の出力でテストを更新したい場合：「Testing」ビューでテストを右クリックして「Accept Test Output」を選択
10.4. クエリパフォーマンスの監視
大規模なデータベースや継続的インテグレーションシステムの一部としてクエリを実行する場合、クエリのパフォーマンスは重要です。
10.4.1. デバッグモードの有効化
クエリパフォーマンスを調査する場合、「Running Queries: Debug」設定を有効にして、タイミングとタプルカウントを含めます。これは「Output」ビューの「CodeQL Query Server」タブのログに表示されます。
タプルカウントは、クエリによって計算された述語のサイズを示すため有用です。
10.4.2. クエリサーバーキャッシュのクリア
クエリが評価されると、クエリサーバーは計算した述語をキャッシュします。2つの評価のパフォーマンスを比較する場合は、各実行前にコマンドパレットから「CodeQL: Clear Cache」を実行してクエリサーバーのキャッシュをクリアする必要があります。これにより、同等のデータを比較できるようになります。
10.5. テスト用の設定
10.5.1. スレッド数の増加
テスト実行時に使用するスレッド数を増やすには、「Running Tests: Number Of Threads」設定を更新します。
10.5.2. 追加の引数
テスト実行時にCodeQL CLIに追加の引数を渡すには、「Running Tests: Additional Test Arguments」設定を更新します。
11. 拡張機能の設定カスタマイズ
CodeQL for Visual Studio Code拡張機能の設定は、ニーズに合わせて編集できます。
11.1. 設定の編集方法
- 「Extensions」ビューを開く
- 「CodeQL」を右クリック
- 「Extension Settings」をクリック
- 設定ウィンドウで必要に応じて設定を編集（新しい設定は自動的に保存される）
または、コマンドパレットから「Preferences: Open User Settings (JSON)」を選択してJSON形式で編集することもできます。
11.2. 主要な設定項目
11.2.1. CodeQL CLIのバージョン
デフォルトの動作を上書きして特定のバージョンのCodeQL CLIを使用するには、拡張機能設定で「CodeQL CLI Executable Path」を指定し、既存のCodeQL CLIのコピーを指すようにします。ファイル名はcodeql（LinuxとmacOS）またはcodeql.exe（Windows）です。
11.2.2. クエリ履歴のフォーマット
クエリ履歴の「Format」設定は、拡張機能がクエリ履歴にクエリをどのようにリストするかを制御します。デフォルトでは、各アイテムに次の形式のラベルが付きます：
QUERY-NAME on DATABASE-NAME - QUERY-STATUS NUMBER-OF-RESULTS [QUERY-RUNTIME]
デフォルトのラベルを上書きするには、クエリ履歴アイテムに異なるフォーマットを指定できます。
11.2.3. クエリ履歴の保持期間
デフォルトでは、「Query History」ビューのアイテムは30日間保持されます。異なる有効期間（TTL）を設定するには、「Query History: Ttl」設定を変更します。アイテムを無期限に保持するには、値を0に設定します。
11.2.4. クエリ実行の設定
「Running Queries」の下には多数の設定があります。例えば：
メモリ設定
クエリの実行が遅すぎて頻繁にタイムアウトする場合、「Running Queries: Memory」設定を変更してメモリを増やすことができます。
デバッグモード
クエリのパフォーマンスを調査したい場合、「Running Queries: Debug」設定を有効にして、タイミングとタプルカウントを含めます。これは「Output」ビューの「CodeQL Query Server」タブのログに表示されます。
カスタムログディレクトリ
クエリサーバーログをカスタムの場所に保存するには、「Running Queries: Custom Log Directory」設定を編集します。カスタムログディレクトリを使用すると、拡張機能は各ワークスペースセッション後に自動的に削除するのではなく、ログを永続的に保存します。これは、クエリのパフォーマンスを改善するためにログを調査する場合に便利です。
11.2.5. Variant Analysisの設定
「Variant Analysis」の下には、GitHub リポジトリのリストを定義または編集したり、別のコントローラーリポジトリに変更したりするために使用できる多数の設定があります。
databases.jsonファイルを編集して、「Variant Analysis Repositories」ビューに表示されるアイテムを編集することもできます。このファイルには、ビューに表示されるすべてのアイテムのJSON表現が含まれています。
databases.jsonファイルを開くには：
- 「Variant Analysis Repositories」ビューの右上にある
{ }アイコンをクリック - リポジトリ、組織、リストの構造化された表現を確認
例：
{
"version": 1,
"databases": {
"variantAnalysis": {
"repositoryLists": [
{
"name": "お気に入りのJavaScriptリポジトリ",
"repositories": [
"facebook/react",
"babel/babel",
"angular/angular"
]
}
],
"owners": [
"microsoft"
],
"repositories": [
"apache/hadoop"
]
}
},
"selected": {
"kind": "variantAnalysisSystemDefinedList",
"listName": "top_10"
}
}
このファイルを直接編集して、ビューに表示されるアイテムを変更したり、新しいアイテムを追加したりできます。
11.2.6. データベース追加の設定
データベースのソースフォルダーをワークスペースに自動的に追加するには、「Adding Databases: Add Database Source to Workspace」設定を有効にできます。
この設定はデフォルトで無効になっています。データベースのソースコードを定期的に閲覧する場合（例えば、コードの抽象構文木を表示するため）、この設定を有効にすることをお勧めします。
注意：単一フォルダワークスペースでデータベースソースフォルダを追加すると、ワークスペースがマルチルートワークスペースとして再読み込みされます。これにより、クエリ履歴とデータベースリストがリセットされる可能性があります。
この設定を有効にする前に、ワークスペースをマルチルートワークスペースとして保存することをお勧めします。
12. ログへのアクセス
CodeQL for Visual Studio Codeで問題をトラブルシューティングする必要がある場合、アクセスできるログがいくつかあります。
12.1. 利用可能なログ
- CodeQL Extension：拡張機能のメインログ
- CodeQL Language Server：CodeQL言語メンテナ向けの高度なデバッグログ
- CodeQL Query Server：クエリのコンパイルと実行の詳細
- CodeQL Tests：テスト実行のログ
注意：CodeQL Language Serverログには、CodeQL言語メンテナ向けの高度なデバッグログが含まれています。通常、これはバグレポートで詳細を提供する場合にのみ必要です。
12.2. ログの表示方法
- VS Codeで「Output」ウィンドウを開く
- ドロップダウンを使用して必要なログビューを選択（例：「CodeQL Extension Log」）
12.3. 通知メッセージ
進捗状況とエラーメッセージは、VS Codeワークスペースの右下隅に通知として表示されます。これらは「Output」ウィンドウのより詳細なログとエラーメッセージにリンクしています。
13. テレメトリとデータ収集
VS Codeのテレメトリが有効になっている場合、GitHubはCodeQL for VS Code拡張機能を改善する目的で使用状況データとメトリクスを収集します。
注意：CodeQL for Visual Studio Codeのテレメトリ収集は、VS Codeのテレメトリ設定に従います。テレメトリ収集が無効になっている場合、GitHubサーバーにデータは送信されません。
13.1. 収集される理由
GitHubは、CodeQL for VS Codeを改善するために、集約された匿名の使用状況データとメトリクスを収集します。IPアドレスとインストールIDは、集約中に匿名データが重複しないようにするためにのみ収集されます。
13.2. 収集されるデータ
テレメトリが有効な場合、GitHubは拡張機能の使用に関連する以下の情報を収集します：
- 実行されたCodeQL関連のVS Codeコマンドの識別子（各コマンドのタイムスタンプ、所要時間、完了の成否）
- UI要素とのインタラクション（ボタン、リンク、その他の入力）。記録されないインタラクション：リンクターゲット、テキスト入力、マウス移動、マウスホバー
- 例外とエラーの発生（ファイルパスや非静的な例外メッセージの内容などの機密情報はアップロード前に削除）
- VS Code拡張機能のバージョン
- CodeQL拡張機能のインストールを一意に識別するランダムに生成されたGUID（集約前に破棄）
- テレメトリデータを送信するクライアントのIPアドレス（集約前に破棄）
- CodeQL for VS Code拡張機能の設定が構成されているかどうか
13.3. 保持期間
- IPアドレスとGUID：最大30日間保持
- 匿名の集約データ（コマンド識別子、実行時間、タイムスタンプを含む）：最大180日間保持
13.4. データへのアクセス
- IPアドレスとGUID：CodeQLのコア開発者のみが利用可能
- 集約データ：GitHub従業員が利用可能
13.5. 収集されないデータ
必要最小限のデータのみを収集します。以下の情報は収集されません：
- GitHub ユーザーID
- CodeQLデータベース名または内容
- CodeQLクエリの内容
- ファイルシステムパス
- ユーザー入力テキスト
- マウスのインタラクション（移動やホバー）
13.6. テレメトリの無効化
グローバルなtelemetry.telemetryLevel設定をoffに設定することで、テレメトリ収集を無効にできます。
14. まとめ
CodeQL for Visual Studio Codeは、セキュリティ分析を開発ワークフローに統合するための実用的なツールです。単一のコードベースに対するクエリ実行から、1,000のリポジトリに対する大規模解析まで、幅広いユースケースに対応しています。
特に注目すべき点は、以下の3つです：
- データフロー追跡：ソースからシンクまでの経路を視覚的に確認でき、複雑な脆弱性の発見が容易になります
- モデルエディタ：カスタムライブラリに対応することで、実際のプロジェクトで使用している依存関係も解析対象にできます
- MRVA：組織全体のコードベースに対して一度にクエリを実行し、横断的なセキュリティ課題を発見できます
セキュリティは後付けではなく、開発プロセスの一部として組み込むべきものです。CodeQL for VS Codeは、そのための実践的な選択肢となるでしょう。