Codeqlを使う
codeqlで静的解析と単体テストをするための備忘録。
無料と有料の制限についてGeminiで調べると:
個人開発・テストページの場合(利用可能)
GitHub CodeQLのライセンス利用規約では、以下の用途であれば無料での使用が明示的に認められている。
- オープンソースソフトウェア(OSI承認ライセンス)の開発・解析
- 学術研究やセキュリティリサーチ、個人の学習目的
- 自作したCodeQLクエリのテスト・動作確認
そのため、「個人で勉強のために書いているコード」や「個人の検証用テストページ」であれば、ローカルでホストしていてもCodeQL CLIやVS Code拡張機能を使って無料で解析できる。
商用・会社業務の場合(利用不可・要契約)
無料利用が制限(禁止)されるのは以下のようなケースである。
- 会社の業務で開発している商用Webサイト・アプリのコードをローカルで解析する場合
- 非公開(プライベート)の商用リポジトリに対してCI/CDや手動でCodeQLを実行する場合
※これらを解析したい場合は、GitHub Advanced Security (GHAS) などの有償ライセンスが必要である。
筆者の環境:Windows 11 Home, git-bash
codeqlのインストール
サイト https://github.com/github/codeql から git clone あるいは
サイト https://github.com/github/codeql-cli-binaries/releases/tag/v2.27.1
からOSに合わせたzipをダウンロードして、展開する
VS codeの拡張機能のインストール
拡張機能「CodeQL」をインストール
テスト対象をOWASPのWebGoatにした場合、適当なところにgit cloneする(/e/my/samples/WebGoat)
サイト https://github.com/github/vscode-codeql-starter/ より
スターターワークスペースをダウンロードする(場所はどこでもいい。例えばCodeQLフォルダに展開)
このスターターワークスペースをVS codeで開く。
テスト対象用のデータベースを作成する
まずCodeQL CLIでデータベースを作成する。
git-bashの例:
src="/e/my/samples/WebGoat"
db="/e/my/samples/webgoat-db"
codeql database create "$db" \
--language=java \
--source-root="$src" \
--build-mode=autobuild
成功すると
Finished writing database (relations: 4.95 MiB; string pool: 11.03 MiB).
TRAP import complete (6.3s).
Finished zipping source archive (610.13 KiB).
Successfully created database at E:\my\samples\webgoat-db.
VS codeの左端ペインに追加された拡張機能QLをクリックする。Databaseビューにある大きな「From a folder」ボタンをクリックする。作成したばかりのデータベースフォルダを選ぶ(例:E:\my\samples\webgoat-db)
解析してみる
動作確認
今回のターゲットはjavaで作成されているのでワークスペースのcodeql-custom-queries-java\example.qlを開き、エディタ上部の三角アイコン(Run Query)をクリックする。CodeQL Query Resultsビューが開いて結果が表示される。
WebGoatで試す
ここからが本番:
拡張機能のSARIF Explorerをインストールしておく
解析結果からソースコードへ飛べるようにテスト対象のフォルダをワークスペースに追加する
codeql database analyze \
--search-path="E:/codeql-repo" \
"/e/my/samples/webgoat-db" \
codeql/java-queries:codeql-suites/java-security-and-quality.qls \
--format=sarif-latest \
--output=webgoat-results.sarif
webgoat-results.sarifがWebGoatフォルダと並列な位置に生成され、SARIF ExplorerがResultsビューを表示する。
このビューに表示されるバグ候補を展開して、ソースコードの各行をクリックするとソースコードが開き、該当箇所に飛ぶ。Resultsの下に表示されるコメントビューにルールの説明が表示され、コメントを追加できる。
注意:
- もしSARIF Explorerが開かなかったらwebgoat-results.sarifをワークスペースにドロップすると開く
- --search-path="E:/vscode-codeql-starter/ql"とするとstarter側のクエリに切り替わる
CWEから脆弱性をチェックする方法
1.クエリファイルを開く:
- VS Code のエクスプローラー(ファイル一覧)を開く
-
vscode-codeql-starterフォルダ配下のqlフォルダを展開する - 以下のパスを順に辿る
ql>java>ql>src>Security>CWE-089
4.例えばSqlTainted.qlをクリックして開く
2.クエリを実行する:
- 開いた
SqlTainted.qlのコード上で右クリックする - メニューから
CodeQL: Run Query on Selected Databaseをクリック
3.CodeQL Query Results パネルが開く
- alerts結果リストを展開する
- データフローを追跡する:
以下の例はステップ1のuserからのuserIdがsourceであり、ステップ10でqueryが実行するまでを順にクリックすることで辿ることができる。
10 This query depends on a user-provided value. SqlInjectionLesson6a.java:72:50
Path (10 steps)
1 userId : String SqlOnlyInputValidationOnKeywords.java:36:7
2 userId : String SqlOnlyInputValidationOnKeywords.java:37:14
3 toUpperCase(...) : String SqlOnlyInputValidationOnKeywords.java:37:14
4 replace(...) : String SqlOnlyInputValidationOnKeywords.java:37:14
5 replace(...) : String SqlOnlyInputValidationOnKeywords.java:37:14
6 userId : String SqlOnlyInputValidationOnKeywords.java:41:58
7 accountName : String SqlInjectionLesson6a.java:50:39
8 query : String SqlInjectionLesson6a.java:56:46
9 query : String SqlInjectionLesson6a.java:68:67
10 query SqlInjectionLesson6a.java:72:50
codeqlのCLIを更新する方法
which codeql
codeql version
where.exe codeql
Windows用のcodeql.zipをダウンロードして展開し、たとえば次のように配置します。
E:\codeql\codeql.exe
E:\codeql\tools\
E:\codeql\java\
単体テスト
単体テストを実施する方法:
わかりやすい例を示す(git-bash)
cd /e/my/samples/vscode-codeql-starter/ql
codeql test run \
java/ql/test/query-tests/security/CWE-089/semmle/examples/SqlTainted.qlref \
--search-path .
実行結果:
Extracting test database in E:\my\samples\vscode-codeql-starter\ql\java\ql\test\query-tests\security\CWE-089\semmle\examples.
Compiling E:\my\samples\vscode-codeql-starter\ql\java\ql\lib\utils\test\InlineExpectationsTestQuery.ql.
Compiled E:\my\samples\vscode-codeql-starter\ql\java\ql\lib\utils\test\InlineExpectationsTestQuery.ql (11.8s).
Compiling E:\my\samples\vscode-codeql-starter\ql\java\ql\lib\utils\test\PrettyPrintModels.ql.
Compiled E:\my\samples\vscode-codeql-starter\ql\java\ql\lib\utils\test\PrettyPrintModels.ql (6s).
Compiling E:\my\samples\vscode-codeql-starter\ql\java\ql\src\Security\CWE\CWE-089\SqlTainted.ql.
Found in cache: E:\my\samples\vscode-codeql-starter\ql\java\ql\src\Security\CWE\CWE-089\SqlTainted.ql (1.1s).
Loading data extensions in E:\my\samples\vscode-codeql-starter\ql\java\ql\test\query-tests\security\CWE-089\semmle\examples\SqlTainted.ext.yml.
Executing tests in E:\my\samples\vscode-codeql-starter\ql\java\ql\test\query-tests\security\CWE-089\semmle\examples.
[1/1 comp 1.1s eval 8.5s] PASSED E:\my\samples\vscode-codeql-starter\ql\java\ql\test\query-tests\security\CWE-089\semmle\examples\SqlTainted.qlref
Failed to clean up E:\my\samples\vscode-codeql-starter\ql\java\ql\test\query-tests\security\CWE-089\semmle\examples\examples.testproj
Completed in 1m6s (extract 28.1s comp 18.9s eval 8.8s).
All 1 tests passed.
テスト用のサンプルコードではSQLインジェクション対策がされていないため、クエリが脆弱性を正しく検出し、期待通りテストがパスする。
CWE-089 のテスト一式を実行する場合は、ディレクトリを指定する
codeql test run \
java/ql/test/query-tests/security/CWE-089 \
--search-path .
codeql test run は、テスト用 Java ファイルから一時的な CodeQL データベースを作成し、クエリを実行して、期待結果と比較する。WebGoat の起動、データベース接続、HTTP リクエストは必要ない。
以上で、codeqlを使用した静的解析と単体テストのやり方を駆け足で一通り見たが、強力なツールであることは納得できる、と思う。