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

code scanningのためのCodeQL CLIの利用について

CodeQL CLI を使用すると、サードパーティの継続的インテグレーション (CI) システ� 内で処理するコードに code scanning を実行できます。 Code scanning は、開発者が GitHub リポジトリ内のコードを分析して、セキュリティの脆弱性とコーディングエラーを見つけることができる機能です。 分析によって特定されたすべての問題はGitHub Enterprise Serverに表示されます。 詳細については、「CodeQL によるcode scanningについて」を参照してく� さい。 CodeQL 解析を実行するための推奨仕様 (RAM、CPU コア、ディスク) については、「CodeQL を実行するための推奨ハードウェア リソース」を参照してく� さい。

CodeQL CLIは、コードの分析に利用できるスタンドアローンの製品です。 その主な目的は、コードベースのデータベース表現であるCodeQLデータベースを生成することです。 データベースの準備ができれば、それに対してインタラクティブにクエリを実行したり、SARIFフォーマットで結果セットを生成するためのクエリのスイートを実行して、結果をにアップロードしたりできます。

あるいは、GitHub Actionsを使ってGitHub Enterprise Server内で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://HOSTNAME/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のセットアップのテスト

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 Enterprise Serverでの認証のためのトークンの生成

それぞれのCIサーバーには、結果をGitHub Enterprise Serverにアップロードするために使うGitHub AppもしくはCodeQL CLIのための個人アクセストークンが必要です。 アクセス トークン、またはsecurity_events 書き込みアクセス許可がある GitHub App を使用する必要があります。 CIサーバーが既にGitHub Enterprise Serverからのリポジトリのチェックアウトのためのこのスコープを持つトークンを使っているなら、CodeQL CLIに同じトークンを使わせることができるかもしれません。 それ以外の� �合は、security_events 書き込みアクセス許可を持つ新しいトークンを作成し、これを CI システ� のシークレット ストアに追� します。 詳細については、「GitHub Apps を構築する」および「個人アクセストークンを使用する」を参照してく� さい。

次の手� �

これでCIシステ� でCodeQL分析を実行し、結果を生成し、それらをGitHub Enterprise Serverにアップロードする準備ができました。結果はそこでブランチもしくはPull Requestとマッチさせられ、code scanningアラートとして表示されます。 詳細については、「CI システ� での CodeQL CLI の構成」を参照してく� さい。