CodeQL CLI の設定

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

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

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

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

この記事の内容

CodeQL CLI を設定する

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 の zip パッケージをダウンロードする

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

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 パックを含む) は現在ベータ版であり、変更される可能性があります。

macOS "Catalina" (またはそれ以降) のユーザー向けのダウンロード情報

macOS バージョン 10.15 ("Catalina") 以降では、Web ブラウザーで ZIP ファイルが自動的に抽出されないようにする必要があります。 Safari を使用している場合は、CodeQL CLI の zip アーカイブをダウンロードする前に、次の手順を実行します。

  1. Safari を開きます。
  2. Safari のメニューから [環境設定...] または [設定...] を選びます (バージョン 13 "Ventura" 以降)。
  3. [一般] タブをクリックします。
  4. [ダウンロード後、"安全な" ファイルを開く] というラベルの付いたチェック ボックスがオフになっていることを確認します。

2. zip アーカイブを抽出する

Linux、Windows、macOS ユーザー (バージョン 10.14 "Mojave" 以前) の場合は、単純に zip アーカイブを抽出します。

macOS "Catalina" (またはそれ以降) のユーザー向けの抽出情報

macOS の "Catalina"、"Big Sur"、"Monterey"、または "Ventura" のユーザーは、ターミナルで次のコマンドを実行する必要があります。${extraction-root} は、CodeQL CLI ZIP アーカイブを抽出するディレクトリへのパスです。

  1. mv ~/Downloads/codeql\*.zip ${extraction-root}
  2. cd ${extraction-root}
  3. /usr/bin/xattr -c codeql\*.zip
  4. unzip codeql\*.zip

3. codeql を起動する

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

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

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

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

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

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

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

次のステップ

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