Skip to main content

CodeQL CLI の設定

CodeQL CLI を使い始めるには、CLI をダウンロードし、データベースの作成と分析に必要なツールとライブラリにアクセスできるように設定する必要があります。

この機能を使用できるユーザーについて

GitHub CodeQL は、インストール時にユーザーごとにライセンスされます。 CodeQL は、ライセンスの制限の下で特定のタスクでのみ使用できます。 詳しくは、「CodeQL CLI について」を参照してください。

GitHub Advanced Security ライセンスがある場合は、CodeQL を使用して、自動分析、継続的インテグレーション、継続的デリバリーを行うことができます。 詳しくは、「GitHub Advanced Security について」を参照してください。

CodeQL CLI を設定する

注: この記事では、GitHub Enterprise Server 3.10 の初期リリースに含まれている CodeQL CLI 2.13.5 バンドルで使用できる機能について説明します。

サイト管理者が CodeQL CLI のバージョンをより新しいリリースに更新している場合は、この記事の GitHub Enterprise Cloud バージョンで最新の機能に関する情報を参照してください。

CodeQL コマンドを実行するには、データベースの作成と分析に必要なツール、クエリ、ライブラリにアクセスできるように CLI を設定する必要があります。

CodeQL CLI は、さまざまなユース ケースとディレクトリ構造をサポートするように設定できます。 すぐに使い始めるには、次の手順で説明するように、比較的簡単なセットアップを採用することをお勧めします。

セキュリティ調査やクエリのテストまたは投稿に CodeQL CLI を使用する場合は、CodeQL CLI のより高度なセットアップが必要になる場合があります。 詳しくは、「CodeQL CLI の高度なセットアップ」を参照してください。

CI システムで CodeQL CLI を設定している場合は、CodeQL code scanning 分析を実行するすべての CI サーバーで、CodeQL CLI バンドルの完全なコンテンツを利用できるようにする必要があります。 たとえば、内部的な中央の場所からバンドルをコピーして展開するよう、各サーバーを設定することになるでしょう。 あるいはREST APIを使ってバンドルをGitHubから直接取得し、クエリに対する最新の改善を活用できるようにすることもできます。 詳しくは、REST API ドキュメントの「リリースとリリース資産の REST API エンドポイント」をご覧ください。

Apple シリコン (例: Apple M1) の macOS を使用している場合は、Xcode コマンド ライン開発者ツールRosetta 2 がインストールされていることを確実にします。

注: 現在、CodeQL CLI は glibc 以外の Linux ディストリビューション (muslc ベースの Alpine Linux など) と互換性がありません。

1. CodeQL CLI の tar アーカイブをダウンロードする

CodeQL CLI ダウンロード パッケージは、ツールおよびスクリプトと、さまざまな CodeQL 固有のファイルを含む tar アーカイブです。 GitHub Enterprise ライセンスをお持ちでない場合は、このアーカイブをダウンロードすることで、GitHub CodeQL の使用条件に同意したことになります。

CodeQL バンドルを https://github.com/github/codeql-action/releases からダウンロードする必要があります。 このバンドルには次のものが含まれています。

  • CodeQL CLI製品
  • https://github.com/github/codeql からのクエリとライブラリの互換性のあるバージョン
  • バンドルに含まれるすべてのクエリのプリコンパイル済みバージョン
GitHub Enterprise Server 3.10 の場合は、CodeQL CLI バージョン 2.13.5 をお勧めします。

CodeQLバンドルは互換性を保証し、CodeQL CLIを個別にダウンロードし、CodeQLクエリをチェックアウトするのに比べてはるかに優れたパフォーマンスが得られるので、常にこのバンドルを利用すべきです。 1 つの特定のプラットフォームでのみ CLI を実行する場合は、適切な codeql-bundle-PLATFORM.tar.gz ファイルをダウンロードします。 または、サポートされているすべてのプラットフォーム用の CLI を含む codeql-bundle.tar.gz をダウンロードすることもできます。

2. CodeQL CLI の tar アーカイブを抽出する

CodeQL CLI の tar アーカイブを任意のディレクトリに抽出します。

3. codeql を起動する

抽出後、codeql の実行可能ファイルを実行することで、CodeQL プロセスを実行できます。方法は 2 通りあります。

  • <extraction-root>/codeql/codeql を実行します。ここで、<extraction-root> は CodeQL CLI パッケージを抽出したフォルダーです。
  • <extraction-root>/codeqlPATH に追加すると、実行可能ファイルを codeql として実行することができます。

この時点で、CodeQL のコマンドを実行できます。 CodeQL CLI コマンドの完全な一覧については、「CodeQL CLI コマンドのマニュアル」を参照してください。

注: codeqlPATH に追加すると、CodeQL からアクセス可能になり、Visual Studio Code でクエリをコンパイルして実行できるようになります。 CodeQL CLI にアクセスするように VS Code を構成する方法について詳しくは、「CodeQL CLI へのアクセスの構成」を参照してください。

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ファイルのディレクトリの場所が正しいかもチェックする必要があります。 場所は、抽出された CodeQL CLI バンドル内にある必要があります (前の例では <extraction root> として示されています)。 CodeQL CLIが期待された言語のqlpackの場所を知ることができないなら、CodeQL CLIのスタンドアローンのコピーではなくCodeQLバンドルをダウンロードしたかを確認してください。

codeql resolve languages を実行して、データベースの作成に使用できる言語を表示することもできます。 これを使用すると、CodeQL CLI パッケージで既定でサポートされている言語が一覧表示されます。

オプションで、実行したい事前コンパイル済のクエリを含むいくつかの CodeQL パックをダウンロードできます。 詳しくは、「CodeQL パックを使った分析のカスタマイズ」を参照してください。

次のステップ

CodeQL CLI によって分析されるコードを準備する方法については、「AUTOTITLEを参照してください。