Skip to main content
ドキュメントへの更新が頻繁に発行されており、このページの翻訳はまだ行われている場合があります。最新情報については、英語版のドキュメントをご覧ください。
 

 

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

この記事では、次の項目が扱われます。

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

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

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

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

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

あるいは、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のセットアップのテスト

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

次の手順

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