code scanningのためのCodeQL CLIの利用について
CodeQL CLI を使用すると、サードパーティの継続的インテグレーション (CI) システム内で処理するコードに code scanning を実行できます。 Code scanning は、GitHub リポジトリ内のコードを分析して、セキュリティの脆弱性とコーディング エラーを見つけることができる機能です。 分析によって特定されたすべての問題はGitHubに表示されます。 詳しくは「CodeQL によるコード スキャンについて」をご覧ください。 CodeQL 分析を実行するための推奨仕様 (RAM、CPU コア数、ディスク) については、「CodeQL を実行するための推奨ハードウェア リソース」をご覧ください。
CodeQL CLIは、コードの分析に利用できるスタンドアローンの製品です。 その主な目的は、コードベースのデータベース表現であるCodeQLデータベースを生成することです。 データベースの準備ができたら、それに対して対話形式でクエリを実行することや、一連のクエリを実行して SARIF 形式で結果セットを生成し、結果を GitHub.com にアップロードすることができます。
あるいは、GitHub Actionsを使ってGitHub内でcode scanningを実行することもできます。 code scanning について詳しくは、「リポジトリの code scanning を構成する」をご覧ください。 CI システムのオプションの概要については、「CIシステムでのCodeQL Code scanningについて」をご覧ください。
メモ:
- CodeQL CLI は、パブリック リポジトリ上で無料で使うことができます。 また、GitHub Enterprise Cloud を使い、GitHub Advanced Security のライセンスを持つ組織が所有するプライベート リポジトリでも、CodeQL CLI を使用できます。 詳細については、「GitHub CodeQL の使用条件」および「CodeQL CLI」を参照してください。
- CodeQL CLI は現在、glibc 以外の Linux ディストリビューション ((musl ベースの) Alpine Linux など) との互換性がありません。
CodeQL CLI のダウンロード
CodeQL バンドルを https://github.com/github/codeql-action/releases からダウンロードする必要があります。 このバンドルには次のものが含まれています。
- CodeQL CLI製品
- https://github.com/github/codeql からのクエリとライブラリの互換性のあるバージョン
- バンドルに含まれるすべてのクエリのプリコンパイル済みバージョン
CodeQLバンドルは互換性を保証し、CodeQL CLIを個別にダウンロードし、CodeQLクエリをチェックアウトするのに比べてはるかに優れたパフォーマンスが得られるので、常にこのバンドルを利用すべきです。 1 つの特定のプラットフォームでのみ CLI を実行する場合は、適切な codeql-bundle-PLATFORM.tar.gz
ファイルをダウンロードします。 または、サポートされているすべてのプラットフォーム用の CLI を含む codeql-bundle.tar.gz
をダウンロードすることもできます。
注: CodeQL パッケージ管理機能 (CodeQL パックを含む) は現在ベータ版であり、変更される可能性があります。
CIシステムでのCodeQL CLIのセットアップ
CodeQL code scanning分析を実行したいすべてのCIサーバーで、CodeQL CLIバンドルの完全な内容が利用できるようにしなければなりません。 たとえば、内部的な中央の場所からバンドルをコピーして展開するよう、各サーバーを設定することになるでしょう。 あるいはREST APIを使ってバンドルをGitHubから直接取得し、クエリに対する最新の改善を活用できるようにすることもできます。 CodeQL CLIのアップデートは、2-3週ごとにリリースされます。 次に例を示します。
$ wget https://github.com/github/codeql-action/releases/latest/download/codeql-bundle-linux64.tar.gz
$ tar -xvzf ./codeql-bundle-linux64.tar.gz
CodeQL CLIバンドルを抽出したら、サーバー上で codeql
の実行可能ファイルを実行できます。
-
/<extraction-root>/codeql/codeql
を実行すると、<extraction-root>
は、CodeQL CLI バンドルを抽出したフォルダーになります。 -
/<extraction-root>/codeql
をPATH
に追加すると、実行可能ファイルをcodeql
として実行することができます。
CodeQL CLI を使って Python で記述されたコードを分析する場合、CI システムに Python 3 がインストールされていることを確認する必要があります。
CodeQL CLI の構成のテスト
CodeQL CLI バンドルを抽出したら、次のコマンドを実行して、データベースを作成して分析できるように CLI が正しく構成されたことを確認できます。
/<extraction-root>/codeql
がPATH
にある場合は、codeql resolve qlpacks
。- それ以外の場合は
/<extraction-root>/codeql/codeql resolve qlpacks
。
成功した出力からの抜粋:
codeql/cpp-all (/<extraction-root>/qlpacks/codeql/cpp-all/<version>)
codeql/cpp-examples (/<extraction-root>/qlpacks/codeql/cpp-examples/<version>)
codeql/cpp-queries (/<extraction-root>/qlpacks/codeql/cpp-queries/<version>)
codeql/csharp-all (/<extraction-root>/qlpacks/codeql/charp-all/<version>)
codeql/csharp-examples (/<extraction-root>/qlpacks/codeql/charp-examples/<version>)
codeql/csharp-queries (/<extraction-root>/qlpacks/codeql/charp-queries/<version>)
codeql/java-all (/<extraction-root>/qlpacks/codeql/java-all/<version>)
codeql/java-examples (/<extraction-root>/qlpacks/codeql/java-examples/<version>)
codeql/java-queries (/<extraction-root>/qlpacks/codeql/java-queries/<version>)
codeql/javascript-all (/<extraction-root>/qlpacks/codeql/javascript-all/<version>)
codeql/javascript-examples (/<extraction-root>/qlpacks/codeql/javascript-examples/<version>)
codeql/javascript-queries (/<extraction-root>/qlpacks/codeql/javascript-queries/<version>)
codeql/python-all (/<extraction-root>/qlpacks/codeql/python-all/<version>)
codeql/python-examples (/<extraction-root>/qlpacks/codeql/python-examples/<version>)
codeql/python-queries (/<extraction-root>/qlpacks/codeql/python-queries/<version>)
codeql/ruby-all (/<extraction-root>/qlpacks/codeql/ruby-all/<version>)
codeql/ruby-examples (/<extraction-root>/qlpacks/codeql/ruby-examples/<version>)
codeql/ruby-queries (/<extraction-root>/qlpacks/codeql/ruby-queries/<version>)
...
出力が期待した言語を含んでいるか、そしてqlpackファイルのディレクトリの場所が正しいかもチェックする必要があります。 この場所は、github/codeql
のチェックアウトを使用していない限り、上記の <extraction root>
のように、抽出された CodeQL CLI バンドル内にある必要があります。 CodeQL CLIが期待された言語のqlpackの場所を知ることができないなら、CodeQL CLIのスタンドアローンのコピーではなくCodeQLバンドルをダウンロードしたかを確認してください。
GitHubでの認証のためのトークンの生成
それぞれの CI サーバーには、結果を GitHub にアップロードするために使う GitHub App もしくは CodeQL CLI のための personal access token が必要です。 アクセス トークン、またはsecurity_events
書き込みアクセス許可がある GitHub App を使用する必要があります。 CIサーバーが既にGitHubからのリポジトリのチェックアウトのためのこのスコープを持つトークンを使っているなら、CodeQL CLIに同じトークンを使わせることができるかもしれません。 それ以外の場合は、security_events
書き込みアクセス許可を持つ新しいトークンを作成し、これを CI システムのシークレット ストアに追加します。 詳細については、「GitHub アプリの作成」と「個人用アクセス トークンの作成」を参照してください。
次の手順
これでCIシステムでCodeQL分析を実行し、結果を生成し、それらをGitHubにアップロードする準備ができました。結果はそこでブランチもしくはPull Requestとマッチさせられ、code scanningアラートとして表示されます。 詳細については、「CIシステムでのCodeQL CLIの設定」を参照してください。