はじめに
デジタルイノベーション推進室の(ほ)です。数年ぶりの投稿で、以前はブロックチェーンを触っていたのですが、最近は生成AIによる業務効率化に関わっています。
私は1年に1度くらいのペースで CodeQL を触ってみているのですが、いつも Query のカスタマイズが難しいため、実際に導入するのは諦めてしまっています。
しかし、近年の生成 AI の進歩から、生成 AI のサポートを受ければ Query のカスタマイズも容易に行えるのではないかと思い、再度試してみることにしました。
本記事では、手始めとしてローカル環境の構築と CodeQL の実行方法について記載します。
目次
1. CodeQLとは
2. CodeQLが選択される理由
3. 実際に使ってみる(Terminal編)
4. 実際に使ってみる(VS Code拡張編)
5. CodeQL C++ Queryディレクトリ別一覧表
まとめ
1. CodeQL とは
CodeQL は、GitHub が提供する静的解析ツールで、下記の仕組みとなっています。
- ビルド時の情報(コンパイルコマンドや依存関係)を活用して、実際のビルド環境に即した正確なデータベースを生成する
- 作成したデータベースに対して、専用のQuery言語で柔軟に解析を行う
この特徴により依存関係が複雑なソースコードでも、より正確な解析が可能で、かつユーザが自由にQueryを記述・実行することでプロジェクトに適した実装パターンの検出をすることができます。
- データベース : ビルド時に収集したソースコードの詳細な構造情報
- Query言語:論理的に「このようなコードパターンを探せ」と定義する DSL(ドメイン固有言語)
2. CodeQL が選択される理由
GitHub Actions と連携することで、Pull Request のタイミングで自動解析が可能です。 また、検出された問題は GitHub の Security タブで Issue のように管理されます。
標準の脆弱性検出だけでなく、自社・チーム独自のルールに基づくQueryを記述・共有可能で 自動化されたセキュリティガードレールを構築できます。
CI/CD パイプラインに組み込むことで、セキュリティを開発の初期段階から担保(シフトレフト)できます。
3. 実際に使ってみる(Terminal編)
ここでは、下記のローカル環境で CodeQL CLI を使用して、C/C++プロジェクトを解析してみます。
実行環境
- Ubuntu 24.04(WSL2)
解析対象
- zlib v1.3.1: CodeQLは下記のライセンス文に記載のようにOSI承認されているオープンソースライセンスのコードの場合に無料で使用できます。そのため、今回の評価は OSI承認されているライセンスのzlibを使用します。それ以外のコードで使用する際には、GitHub Advanced Security の有料ライセンスが必要です。
License By downloading, you agree to the GitHub CodeQL Terms & Conditions. GitHub CodeQL can only be used on codebases that are released under an OSI-approved open source license, or to perform academic research. It can't be used to generate CodeQL databases for or during automated analysis, continuous integration or continuous delivery, whether as part of normal software engineering processes or otherwise. For these uses, contact the sales team. |
GitHub のCodeQL CLI のリリースページから最新のバイナリをダウンロードし、パスを通します。
$ mkdir codeql-cli |
$ wget https://github.com/github/codeql-cli-binaries/releases/download/v2.21.2/codeql-linux64.zip |
codeql-linux64.zip |
$ cd codeql-cli |
$ echo export PATH=$PATH:`(pwd)` >> ~/.bashrc |
$ source ~/.bashrc |
$ cd .. |
zlib 自体のビルドのために下記のライブラリをインストールします。 他の環境や他のコードの場合は、対象のライブラリのビルド手順などを確認してインストールしてください。
$ sudo apt install -y \ |
git \ |
build-essential \ |
gcc \ |
make |
下記のコマンドで zlib を取得してビルドの確認をします。
$ git clone --branch v1.3.1 --depth 1 https://github.com/madler/zlib.git |
$ cd zlib |
# 下記の./configure, make は zlibのビルド手順のため、他のライブラリを使用する場合は、そのライブラリのビルド手順を参照 |
$ ./configure |
$ make -j8 |
# ビルドが正常に実行できることを確認できたなら |
# この後の手順でビルド成果物が存在するとデータベースを作成できないため削除 |
$ make clean |
ビルドが問題なくできれば、下記のコマンドでデータベースを作成します。
$ codeql database create zlib-db-v1.3.1 --language=cpp --source-root=. --command="make -j8" |
上記コマンドで指定したオプションは下記です。
- codeql database create zlib-db-v1.3.1
- 「zlib-db-v1.3.1」という名前のデータベースを新規作成します。
- --language=cpp
- C/C++言語として解析します。
- --source-root=.
- 現在のディレクトリ(.)をソースコードのルートとして指定します。
- --command="make -j8"
- ビルドコマンドを指定します。今回はデータベース作成時に「make -j8」(8 並列でビルド)を実行し、そのビルド過程を CodeQL が監視・解析します。
これにより、上記のコマンドで指定した zlib-db-v1.3.1 ディレクトリに、解析用の CodeQL データベースが作成されます。
下記のようなログが出力された場合は、既にビルド成果物が存在していることを示しています。前述したように、CodeQL のデータベース作成はビルド時の情報が必要なので、ビルドが不要な状態で実行した場合はデータベースを作成できません。zlib のビルド確認のコマンドのように make clean などで成果物を一度削除してから再度データベース作成のコマンドを試してみてください。
CodeQL detected code written in C/C++ but could not process any of it. For more information, review our troubleshooting guide at https://gh.io/troubleshooting-code-scanning/no-source-code-seen-during-build. |
CodeQL のリポジトリには多くの既成Queryがあり、それを使って簡単に脆弱性を検出できます。
# 適当なディレクトリに移動。今回はzlibディレクトリ内から、その親ディレクトリに移動 |
$ cd .. |
# CodeQLと同じバージョンのQueryの取得 |
$ git clone --branch codeql-cli-2.21.2 --depth 1 https://github.com/github/codeql.git |
# サンプルにコード行数取得のQueryの実行 |
$ codeql query run codeql/cpp/ql/src/Summary/LinesOfCode.ql --database=zlib/zlib-db-v1.3.1 |
実行後、下記のようなログが出力されれば成功です。今回は 26,468 行であったことが示されています。
Compiling query plan for /home/codeql/workspace/query/codeql/cpp/ql/src/Summary/LinesOfCode.ql. |
[1/1] Found in cache: /home/codeql/workspace/query/codeql/cpp/ql/src/Summary/LinesOfCode.ql. |
LinesOfCode.ql: Evaluation completed (107ms). |
| col0 | |
+-------+ |
| 26468 | |
Shutting down query evaluator. |
4. 実際に使ってみる(VS Code拡張編)
コード行数を表示する程度であればTerminalからの実行で良いのですが、問題のある個所を特定するには、VS CodeのCodeQL拡張機能を用いるのが簡単です。
今回はQueryが確実に問題を見つけられるように意図的にコードに不具合を追加します。
Free後のHeapメモリの使用を検出するQuery(codeql/cpp/ql/src/Critical/UseAfterFree.ql) を試すため、zlib/inflate.c に下記の1463行目の修正を追加します。

コード修正後に再度データベースを作成しますが、下記のように前回とは異なる名前でデータベースを作成します。
$ codeql database create zlib-db-v1.3.1-free --language=cpp --source-root=. --command="make -j8" |
前回と同じデータベース名で作成すると下記のようなエラーメッセージが出力されます。
そのため、上記のようにデータベースを異なる名前にするか、最初に作成したデータベースを他の場所に移動させる、 --overwrite フラグを使用するなどの対処が必要です。
A fatal error occurred: Refusing to create database: 'zlib-db-v1.3.1' exists and is not an empty directory. |
Please specify a different location, or use the --overwrite flag to overwrite existing CodeQL databases. |
VS Codeを起動し、拡張機能から「CodeQL」を検索しインストールします。
Identifierは github.vscode-codeql なので、下記のコマンドでもインストール可能です。
$ code --install-extension github.vscode-codeql |
CodeQL拡張を開くと下記のようなサイドパネルが開きますので、適当な設定をします。
- LANGUAGE: 今回はC/C++ (QueryがC/C++のもののみ表示されるようになります)
- DATABASES: From a folderから先ほど作成したzlib-db-v1.3.1-freeを選択
- QUERIES: Terminal編でCloneしたQueryのあるディレクトリを指定

CodeQL拡張の設定が正しくできると、下記のようにデータベースとQueryが表示されます。
ここで codeql/cpp/ql/src/Critical/UseAfterFree.ql の横の三角アイコンをクリックすると、該当のQueryを実行できます。

実行完了すると、下記の画像の左側のような結果が表示されます。
問題の指摘部分をクリックすると、該当箇所へジャンプします(下記画像右側)。

事前準備で追加した不具合を見つけられたことを確認できました。
5. CodeQL C++ Query ディレクトリ別一覧表
上記で実行したQuery以外にも、codeql/cpp/ql/src 以下には下記のような Queryがあります。
ディレクトリ |
代表的なQuery例 |
説明・カテゴリ例 |
Architecture |
FeatureEnvy.ql |
アーキテクチャ品質の分析 |
Best Practices |
RuleOfThree.ql, GuardedFree.ql |
コーディングベストプラクティス |
Critical |
DoubleFree.ql, UseAfterFree.ql |
重大な問題の検出 |
Diagnostics |
DiagnosticQuery.ql |
診断情報の取得 |
Documentation |
Extractors/Extractor.ql |
ドキュメント生成関連 |
Header Cleanup |
Cleanup-DuplicateIncludeGuard.ql |
ヘッダ整理関連 |
JPL_C |
Recursion.ql, CheckingReturnValues.ql |
JPL C コーディング標準 |
Likely Bugs |
NestedLoopSameVar.ql |
バグの可能性が高い箇所の検出 |
Metrics |
FunCyclomaticComplexity.ql |
関数レベルのメトリクス計測 |
Microsoft |
InconsistentSAL.ql |
Microsoft SAL 関連 |
PointsTo |
- |
ポインタ解析 |
Power of 10 |
UseOfGoto.ql |
NASA/JPL Power of 10 ルール |
Security |
UntrustedDataToExternalAPI.ql |
セキュリティ脆弱性の検出(CWE 等) |
Summary |
LinesOfCode.ql, LinesOfUserCode.ql |
コードサマリ・集計 |
Telemetry |
DatabaseQuality.ql |
データベース品質の分析 |
experimental |
cryptography/WeakAsymmetricKeyGen.ql |
実験的Query |
external |
DefectFilter.qll |
外部連携・フィルタ |
filters |
ClassifyFiles.ql |
ファイル分類 |
jsf |
4.04 Environment/ など |
JSF コーディング標準 |
主要な検出カテゴリ
- セキュリティ関連
- CWE(Common Weakness Enumeration)に基づく脆弱性検出
- SQL インジェクション、バッファオーバーフロー、暗号化関連など
- メモリ管理
- メモリリーク、二重解放、解放後使用など
- コーディング標準
- JPL C コーディング標準
- NASA Power of 10 ルール
- Microsoft SAL
- 品質指標
- 循環的複雑度、コード行数、関数パラメータ数など
- 設計品質
-
- クラス設計、依存関係、アーキテクチャパターン
また、今回はC/C++を試していますが、他にもC#, Go, Java(Kotlin), JavaScript(TypeScript), Python, Ruby, Rust, Swift, Github Actions と多くの言語をサポートしています。
まとめ
今回の記事では、CodeQL の概要と、実際にローカル環境構築とQueryを実行するところまでをご紹介しました。
CodeQL は、標準Queryだけでなく独自のQueryを作成することで、プロジェクト固有のコーディングルールやセキュリティ要件にも柔軟に対応できます。
次回は、CI/CD パイプラインや GitHub Actions との連携のために GitHub での CodeQL 設定について確認したいと思います。