
こんにちは、エーピーコミュニケーションズ ACS事業部の福井です。
GitHub Advanced Security(GHAS)の中核をなす静的解析ツール「CodeQL」。
導入時、「せっかくなら検知範囲が一番広い設定にしよう」と考えて、標準の default スイートや少し拡張した security-extended から、security-and-quality(通称:全部盛りパック)へ切り替えることを検討する方は多いのではないでしょうか。
私も同じことを考えた一人です。
ただ、切り替えた先に何が起きるのかを自分の目で確かめないまま導入を勧めるのは、一次情報とは言えないと感じました。
そこで、JavaScriptとPythonのそれぞれで意図的に脆弱性とコードスメル(バグではないものの、可読性や保守性を下げる「臭う」コード。未使用変数や空の例外処理などが代表例です)を埋め込んだPoC(検証用)リポジトリを作成し、基本パックと拡張パックを並行スキャンで比較してみました。
その結果見えてきたのは、確かな検知力の向上と、そのすぐ隣に潜む「ノイズの壁」でした。
今回は、その壁の正体と、.qls(カスタムクエリスイート)を使った乗り越え方についてお話しします。
- 検証1:security-extended と security-and-quality で何が変わるのか
- 検証2:.qlsによる「引き算」のチューニング
- コラム:クエリパックの「バージョン固定」でCI/CDを守る
- そもそもCodeQLのクエリパックはどれだけ種類があるのか
- おわりに:機能を「オンにする」だけではDevSecOpsは完成しない
- ACS 事業部のご紹介
検証1:security-extended と security-and-quality で何が変わるのか
まず、JavaScript(Node.js/Express)とPythonの2つのダミーアプリに、SQLインジェクションやOSコマンドインジェクションといった脆弱性と、未使用変数や空のexceptブロックといったコードスメルを意図的に仕込みました。
この同一コードに対して security-extended と security-and-quality をGitHub Actionsのマトリックスビルドで並行実行し、検知結果を比較しています。
※本記事の検証は2026年7月時点のCodeQL(バージョン2.26.1)の挙動に基づいています。クエリの内容やバージョンは今後変更される可能性があります。
検証で使ったPythonコード(app.py)の一部と、GHAS APIからダンプした実際のアラートはこのような内容です。
▼ 検知対象のダミーコード(Python)
def code_quality_issues(): # 品質問題: 未使用のローカル変数 (py/unused-local-variable) x = 10 y = 20 # 品質問題: 空の except ブロック (py/empty-except) try: z = 1 / 0 except ZeroDivisionError: pass return True
▼ 検知されたアラートのイメージ(py/empty-except ルールの内容を元に整形)
{ "rule": { "id": "py/empty-except", "severity": "note" }, "message": { "text": "This except clause does nothing." } }
上記は実際にダンプしたJSONそのものではなく、CodeQLの公式クエリ定義(py/empty-except)の内容をもとに、GHAS APIレスポンスの形式に合わせて再現したものです。
生のダンプデータはJavaScript側の検証で取得済みで、references.md に記載の raw_alerts.json として保存しています。
両パックの検知結果をまとめると、次の通りです。
| Rule ID | Severity | 検知パック | 備考 |
|---|---|---|---|
js/command-line-injection |
critical | 両方 | exec によるOSコマンドインジェクション |
js/sql-injection |
high | 両方 | 文字列連結によるSQLインジェクション |
js/reflected-xss |
high | 両方 | 反射型XSS |
js/missing-rate-limiting |
high | 両方 | レート制限の欠如(2件) |
py/command-line-injection |
critical | 両方 | os.system によるコマンドインジェクション |
py/sql-injection |
high | 両方 | 文字列連結によるSQLインジェクション |
py/stack-trace-exposure |
high | 両方 | エラー詳細のそのままの露出 |
js/unused-local-variable |
note(品質) | qualityのみ | 未使用の変数・関数(2件) |
py/unused-local-variable |
note(品質) | qualityのみ | 未使用のローカル変数 |
py/unused-import |
note(品質) | qualityのみ | 未使用のインポート |
py/empty-except |
note(品質) | qualityのみ | エラーの握りつぶし |
セキュリティ上重大な脆弱性(critical・high)は両パックで確実に捕捉されており、security-and-quality ではその上に「品質面の問題」が追加で検知されていました。
JavaScript側では security-and-quality の総アラート数が9件、うち2件が品質系(severity: note)のアラートでした。
なお、極小サイズのアプリだったこともあり、スキャン実行時間はほぼ差が出ませんでした(security-extended 約65秒、security-and-quality 約64秒)。
ビルド時間への影響は規模の大きいリポジトリでは変わってくる可能性があるため、この点は自分のPoCで確認できた範囲の事実として留めておきます。
ここに、現場を悩ませる罠があると感じました。
今回はダミーの小さなアプリだったので9件で済みましたが、既存の大規模なレガシープロジェクトにいきなり security-and-quality を有効化すると、数千件規模の「未使用変数」や「非推奨の書き方」がダッシュボードを埋め尽くし、本当に対応すべき重大な脆弱性が埋もれてしまうことは容易に想像できます。
これがいわゆる「アラート疲労」です。
検証2:.qlsによる「引き算」のチューニング
「重大な脆弱性は検知したいが、自社のコーディング規約に合わない一部の品質アラートは除外したい」。
このジレンマを解決できるか、独自のクエリスイート(.qls)を使ったチューニングを試しました。
security-and-quality をベースにしつつ、ノイズになりやすい特定のルールだけを exclude(除外)する設定ファイル(custom-suite.qls)を作成します。
# custom-suite.qls の例 - import: codeql-suites/javascript-security-and-quality.qls from: codeql-javascript - exclude: id: - js/unused-local-variable
このカスタム設定で再スキャンをかけたところ、JavaScript側のアラート数が9件から7件に減少しました。
狙い通り、critical・highの脆弱性はそのまま維持しつつ、「未使用変数」のアラートだけをピンポイントで除外できたことになります。
実際の現場に導入するなら、次のような段階的なアプローチが現実的だと思います。
まずは影響の少ない security-extended で小さく始め、トリアージ運用が定着した段階で security-and-quality へ移行する。
そのうえで、自社の開発スタイルに合わないルールだけを .qls で除外していく、という進め方です。
コラム:クエリパックの「バージョン固定」でCI/CDを守る
検証の過程で、「言語仕様に破壊的変更が入った場合、CodeQLはどう追随するのか」という疑問が浮かびました。
CodeQLの解析エンジンやルールセットはGitHub Security Labによって日々アップデートされており、新しいバージョンで特定のAPIが危険と判定されるようになった場合、最新のCodeQLがそれを新たなアラートとして教えてくれます。
ただ、これは裏を返すと「昨日まで通っていたCI/CDのビルドが、ある日突然CodeQLのルール更新によって失敗し、開発がブロックされる」というリスクにもなり得ます。
この課題に対処するため、CodeQLは解析エンジンとデフォルトのクエリセットをまとめた「CodeQLバンドル」単位でバージョン管理されており、tools パラメータで特定のバンドルバージョンに固定して実行することができます。
- name: Initialize CodeQL uses: github/codeql-action/init@v3 with: languages: python # CodeQLバンドル(解析エンジン+同梱クエリ)のバージョンを固定し、CI/CDの突然の失敗を防ぐ tools: https://github.com/github/codeql-action/releases/download/codeql-bundle-v2.17.0/codeql-bundle-linux64.tar.gz
メインのパイプラインではあえて古いバンドルバージョンに固定(ピン留め)して突然のビルド失敗を防ぎ、半年に1回など計画的なタイミングで別ブランチ上で最新バンドルへ更新し、新規アラートをトリアージしてからメインにマージする。
この運用であれば、セキュリティの最新化と開発スピード(CI/CDの安定性)を両立できると考えています。
なお、security-and-quality のような組み込みスイート以外に、独自の拡張クエリパックだけをGitHub Container Registry経由でバージョン指定したい場合は、queries: codeql/python-queries@0.8.4 のように <スコープ>/<パック名>@<バージョン>(github/ は付けず、バージョンにも v を付けない)という書式になります。
なお、余談ですが「利用している外部パッケージ自体の脆弱性」はCodeQL(静的アプリケーションセキュリティテスト:SAST)の守備範囲ではなく、Dependabot(ソフトウェア構成分析:SCA)が担う領域です。
自社コードの書き方はCodeQL、外部ライブラリの脆弱性はDependabotという多層防御(Defense in Depth)を意識して組み合わせるのがよいと思います。
そもそもCodeQLのクエリパックはどれだけ種類があるのか
今回は組み込みスイート(security-extended / security-and-quality)と.qlsによるチューニングまでしか検証できていませんが、実は全体像を俯瞰できる一覧が公式ドキュメントに用意されています。
- CodeQL query suites(組み込みスイートの説明)
- Queries for CodeQL analysis(言語ごとの全クエリ一覧)
- github/codeql(実験的クエリを含むソース本体)
ドキュメントを読み解くと、ワークフローの language に指定する文字列や公式QLパック名、クエリID(Rule ID)の頭文字(プレフィックス)は言語ごとに規則性が決まっていることがわかりました。
自分で調べる際の索引として、代表的な言語をまとめておきます。
| 対象言語 | language の指定値 |
公式QLパック名 | クエリIDのプレフィックス |
|---|---|---|---|
| JavaScript / TypeScript | javascript |
codeql/javascript-queries |
js/... |
| Python | python |
codeql/python-queries |
py/... |
| Java / Kotlin | java-kotlin |
codeql/java-queries |
java/... |
| C / C++ | cpp |
codeql/cpp-queries |
cpp/... |
| C# | csharp |
codeql/csharp-queries |
cs/... |
| Ruby | ruby |
codeql/ruby-queries |
rb/... |
| Swift | swift |
codeql/swift-queries |
swift/... |
※以前はJavaとKotlinが別々に扱われていたりしましたが、現在は統合されている言語(javascript-typescript や java-kotlin など)もあります。
ワークフロー上は旧名(java など)でも動作するケースが多いですが、最新のドキュメントの指定値に合わせるのが確実です。
個別チューニングで使う「クエリID」は「言語のプレフィックス/脆弱性やバグの名前」というシンプルな命名規則になっています。
ブログの具体例としても載せやすい代表的なルールを、言語別にいくつかピックアップしました。
JavaScript / TypeScript
- js/sql-injection: SQLインジェクション
- js/xss: クロスサイトスクリプティング(XSS)
- js/hardcoded-credentials: クレデンシャルのハードコード
Python
- py/sql-injection: SQLインジェクション
- py/path-injection: パストラバーサル
- py/command-line-injection: OSコマンドインジェクション
Java / Kotlin
- java/sql-injection: SQLインジェクション
- java/spring-disabled-csrf-protection: Spring frameworkのCSRF保護無効化
- java/insecure-cookie: 安全でないCookieの設定
言語ごとの公式パックのリポジトリパス指定や、security-experimental(実験的クエリ)、コミュニティが公開しているサードパーティのクエリパックを組み合わせれば、もっと自社のコーディング規約に踏み込んだ検知ができそうだと感じました。
このあたりは次回、実際に試してから改めて記事にしたいと思います。
おわりに:機能を「オンにする」だけではDevSecOpsは完成しない
新しいセキュリティ機能がリリースされると、つい「とりあえず一番強い設定を有効化しよう」と考えがちです。
しかし、実際にPoC環境で手を動かしてみると、「ノイズによるアラート疲労」や「CI/CDパイプラインの突然の崩壊」という、ドキュメントには目立って書かれていない現場の課題が見えてきました。
「基本パックと品質パックの検知差分を理解する」
「.qlsファイルで引き算のチューニングを行う」
「クエリパックのバージョンを固定してCI/CDを守る」
この3つを自分の手で確認できたことは、今後GHASの導入を提案する際の強力な根拠になると感じています。
単にツールを有効化するだけでなく、こうした検証を積み重ねて「開発者が納得し、開発スピードを落とさないセキュリティ運用」を追求していくことが、DevSecOpsへの第一歩だと私は考えています。
「全部盛りは検知力を上げてくれる。でも、ノイズを引き算する準備がなければ、現場では使いこなせない。」
ACS 事業部のご紹介
私の所属する ACS 事業部では、開発者ポータル Backstage、Azure AI Service などを活用し、Platform Engineering + AI の推進・内製化を支援しています。
www.ap-com.co.jp www.ap-com.co.jp www.ap-com.co.jp
また、GitHub パートナーとしてお客様に GitHub ソリューションの導入支援を行っています。 GitHub Copilot などのトレーニングなども行っておりますので、ご興味を持っていただけましたらぜひお声がけいただけますと幸いです。
一緒に働いていただける仲間も募集中です! ご興味持っていただけましたらぜひお声がけください。 ※求人名の冒頭に【ACSD】と入っている求人が当事業部の求人です。