Skip to main content

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

サードパーティの継続的インテグレーションシステムにCodeQL CLIをインストールし、CodeQL code scanningを実行するために使用できます。

Code scanning は、GitHub.com のすべてのパブリック リポジトリに使用できます。 Organization によって所有されるプライベート リポジトリで code scanning を使うには、GitHub Advanced Security のライセンスが必要です。 詳細については、「GitHub Advanced Security について」を参照してください。

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

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

CodeQL CLIは、コードの分析に利用できるスタンドアローンの製品です。 その主な目的は、コードベースのデータベース表現であるCodeQLデータベースを生成することです。 データベースの準備ができたら、それに対して対話形式でクエリを実行することや、一連のクエリを実行して SARIF 形式で結果セットを生成し、結果を GitHub.com にアップロードすることができます。

あるいは、GitHub Actionsを使ってGitHub Enterprise Cloud内でcode scanningを実行することもできます。 アクションを使用した code scanning の詳細については、「リポジトリの code scanning の設定」を参照してください。 CI システムのオプションの概要については、「CI システムの CodeQL code scanning について」を参照してください。

メモ:

  • CodeQL CLI は、GitHub.com 上で管理されているパブリック リポジトリ上で無料で使うことができます。また、Advanced Security のライセンスを持つ顧客が所有するプライベート リポジトリでも使うことができます。 詳細については、「GitHub Enterprise Cloud 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>/codeqlPATH に追加すると、実行可能ファイルを codeql として実行することができます。

CodeQL CLI を使って Python で記述されたコードを分析する場合、CI システムに Python 3 がインストールされていることを確認する必要があります。

CodeQL CLIのセットアップのテスト

CodeQL CLIバンドルを展開したら、CLIがデータベースを作成して分析できるよう正しくセットアップされたことを、以下のコマンドを実行して確認できます。

  • /<extraction-root>/codeqlPATH にある場合は、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 Cloudでの認証のためのトークンの生成

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

次の手順

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