CodeQLをローカルで実行してみた

デジタルイノベーション推進室の（ほ）です。数年ぶりの投稿で、以前はブロックチェーンを触っていたのですが、最近は生成AIによる業務効率化に関わっています。

私は1年に1度くらいのペースで CodeQL を触ってみているのですが、いつも Query のカスタマイズが難しいため、実際に導入するのは諦めてしまっています。
しかし、近年の生成 AI の進歩から、生成 AI のサポートを受ければ Query のカスタマイズも容易に行えるのではないかと思い、再度試してみることにしました。
本記事では、手始めとしてローカル環境の構築と CodeQL の実行方法について記載します。

1. CodeQLとは
2. CodeQLが選択される理由
3. 実際に使ってみる(Terminal編)
4. 実際に使ってみる(VS Code拡張編)
5. CodeQL C++ Queryディレクトリ別一覧表
まとめ

CodeQL は、GitHub が提供する静的解析ツールで、下記の仕組みとなっています。

• ビルド時の情報（コンパイルコマンドや依存関係）を活用して、実際のビルド環境に即した正確なデータベースを生成する
• 作成したデータベースに対して、専用のQuery言語で柔軟に解析を行う

この特徴により依存関係が複雑なソースコードでも、より正確な解析が可能で、かつユーザが自由にQueryを記述・実行することでプロジェクトに適した実装パターンの検出をすることができます。

• データベース : ビルド時に収集したソースコードの詳細な構造情報
• Query言語：論理的に「このようなコードパターンを探せ」と定義する DSL（ドメイン固有言語）

GitHub Actions と連携することで、Pull Request のタイミングで自動解析が可能です。 また、検出された問題は GitHub の Security タブで Issue のように管理されます。

標準の脆弱性検出だけでなく、自社・チーム独自のルールに基づくQueryを記述・共有可能で 自動化されたセキュリティガードレールを構築できます。

CI/CD パイプラインに組み込むことで、セキュリティを開発の初期段階から担保（シフトレフト）できます。

ここでは、下記のローカル環境で CodeQL CLI を使用して、C/C++プロジェクトを解析してみます。

実行環境

• Ubuntu 24.04(WSL2)

解析対象

• zlib v1.3.1: CodeQLは下記のライセンス文に記載のようにOSI承認されているオープンソースライセンスのコードの場合に無料で使用できます。そのため、今回の評価は OSI承認されているライセンスのzlibを使用します。それ以外のコードで使用する際には、GitHub Advanced Security の有料ライセンスが必要です。

github/codeql-cli-binaries: Binaries for the CodeQL CLI

GitHub のCodeQL CLI のリリースページから最新のバイナリをダウンロードし、パスを通します。

zlib 自体のビルドのために下記のライブラリをインストールします。 他の環境や他のコードの場合は、対象のライブラリのビルド手順などを確認してインストールしてください。

下記のコマンドで zlib を取得してビルドの確認をします。

ビルドが問題なくできれば、下記のコマンドでデータベースを作成します。

上記コマンドで指定したオプションは下記です。

•  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 のリポジトリには多くの既成Queryがあり、それを使って簡単に脆弱性を検出できます。

実行後、下記のようなログが出力されれば成功です。今回は 26,468 行であったことが示されています。

コード行数を表示する程度であればTerminalからの実行で良いのですが、問題のある個所を特定するには、VS CodeのCodeQL拡張機能を用いるのが簡単です。

今回はQueryが確実に問題を見つけられるように意図的にコードに不具合を追加します。
Free後のHeapメモリの使用を検出するQuery(codeql/cpp/ql/src/Critical/UseAfterFree.ql) を試すため、zlib/inflate.c に下記の1463行目の修正を追加します。

コード修正後に再度データベースを作成しますが、下記のように前回とは異なる名前でデータベースを作成します。

前回と同じデータベース名で作成すると下記のようなエラーメッセージが出力されます。
そのため、上記のようにデータベースを異なる名前にするか、最初に作成したデータベースを他の場所に移動させる、 --overwrite フラグを使用するなどの対処が必要です。

VS Codeを起動し、拡張機能から「CodeQL」を検索しインストールします。
Identifierは 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を実行できます。

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

事前準備で追加した不具合を見つけられたことを確認できました。

上記で実行したQuery以外にも、codeql/cpp/ql/src 以下には下記のような Queryがあります。

主要な検出カテゴリ

1. セキュリティ関連
   • CWE（Common Weakness Enumeration）に基づく脆弱性検出
   • SQL インジェクション、バッファオーバーフロー、暗号化関連など
2. メモリ管理
   • メモリリーク、二重解放、解放後使用など
3. コーディング標準
   • JPL C コーディング標準
   • NASA Power of 10 ルール
   • Microsoft SAL
4. 品質指標
   • 循環的複雑度、コード行数、関数パラメータ数など
5. 設計品質

• • クラス設計、依存関係、アーキテクチャパターン

また、今回は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 設定について確認したいと思います。