CIシステムへのCodeQL CLIのインストール

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 のダウンロード

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 をダウンロードすることもできます。

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の設定」を参照してください。