CodeQL CLI の設定

CodeQL CLI を設定する

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

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

Linux、Windows、または macOS バージョン 10.14 ("Mojave") 以前を使用している場合は、次の手順に従ってください。 macOS バージョン 10.15 ("Catalina") 以降の場合は、いくつかの手順に関する追加の注意事項があります。 Apple シリコン (例: Apple M1) の macOS を使用している場合は、Xcode コマンドライン開発者ツールと Rosetta 2 がインストールされていることを確実にします。

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

コードスキャンアラートとして GitHub に表示する結果を作成するために CI システムに CodeQL CLI をインストールする方法については、「CIシステムへのCodeQL CLIのインストール」をご覧ください。

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 アーカイブをダウンロードする前に、次の手順を実行します。

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

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

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

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

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

mv ~/Downloads/codeql\*.zip ${extraction-root}
cd ${extraction-root}
/usr/bin/xattr -c codeql\*.zip
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 を構成する方法について詳しくは、「Visual Studio Code で 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バンドルをダウンロードしたかを確認してください。

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

(省略可能) 実行できる事前コンパイル済みクエリを含む "CodeQL パックを使った分析のカスタマイズ" をダウンロードできます。これを行うには、codeql pack download <pack-name> [...pack-name] を実行します。ここで、pack-name はダウンロードするパックの名前です。最初はコアクエリパックをお勧めします。これらは次のとおりです。

codeql/cpp-queries
codeql/csharp-queries
codeql/go-queries
codeql/java-queries
codeql/javascript-queries
codeql/python-queries
codeql/ruby-queries

または、codeql database analyze コマンドの --download フラグを使用して、分析中にクエリパックをダウンロードすることもできます。

GitHubでの認証のためのトークンの生成

最終的に結果を GitHub にアップロードしてコードスキャンアラートとして表示したい場合は、security_events の書き込みアクセス許可を持つ personal access token を生成する必要があります。詳しくは、「個人用アクセストークンを管理する」を参照してください。

コードスキャンアラートとして GitHub に表示する結果を作成するため、サードパーティの CI システムに CodeQL CLI をインストールしてある場合は、GitHub App または personal access token を使って、結果を GitHub にアップロードできます。詳しくは、「CIシステムへのCodeQL CLIのインストール」を参照してください。

CodeQL ソースコードディレクトリをチェックアウトする

オープンソースの共有クエリについて取り組んだり貢献したりするために、CodeQL のクエリソースを直接操作することを希望するユーザーもいます。これを行うには、次の手順をお勧めします。次の手順は、上で説明した CodeQL パッケージの操作に代わる、やや複雑な方法であることに注意してください。

1. CodeQL CLI の zip をダウンロードする

前のセクションの手順 1 に従います。

2. 新しい CodeQL ディレクトリを作成する

CLI と、使用するクエリとライブラリを配置できる新しいディレクトリを作成します。たとえば、$HOME/codeql-home のようにします。

CLI の組み込み検索操作を行うと、データベースの作成と分析で使用されるファイルのすべての兄弟ディレクトリが自動的に検索されます。これらのコンポーネントをそれぞれ独自のディレクトリに保持すると、関連のない兄弟ディレクトリは CLI で検索されず、コマンドラインで追加のオプションを指定せずにすべてのファイルを使用できます。

3. CodeQL クエリのローカルコピーを取得する

CodeQL リポジトリには、サポートされているすべての言語の CodeQL 分析に必要なクエリとライブラリが含まれています。このリポジトリのコピーを codeql-home にクローンします。

既定では、クローンされたリポジトリのルートは codeql と呼ばれます。手順 1 で抽出する CodeQL CLI と競合しないように、このフォルダー codeql-repo の名前を変更します。コマンドラインで git を使用する場合は、codeql-home フォルダーで git clone git@github.com:github/codeql.git codeql-repo を実行することで、1 つの手順でリポジトリのクローンと名前変更を行うことができます。

このリポジトリでは、クエリとライブラリが CodeQL パックにまとめられています。 CodeQL パックには、クエリ自体に加えて、クエリファイルの処理方法を CodeQL CLI に指示する重要なメタデータが含まれています。詳しくは、「CodeQL パックを使った分析のカスタマイズ」を参照してください。

注: CodeQL クエリには、ユーザーごとに異なるバージョンがあります。ユースケースに合った正しいバージョンをチェックアウトしてください。

最新の CodeQL CLI リリースで使用することを目的としたクエリについては、codeql-cli/latest というタグが付いたブランチをチェックアウトします。 CodeQL CLI を使用してビルドしたか、GitHub のコードスキャンからフェッチしたか、または GitHub.com から最近ダウンロードしたデータベースには、このブランチを使用する必要があります。
最新の CodeQL クエリについては、main ブランチをチェックアウトします。このブランチは、CodeQL の分析の最新バージョンを表します。

4. ZIP アーカイブを抽出する

Linux、Windows、macOS ユーザー (バージョン 10.14 "Mojave" 以前) の場合は単に、手順 2 で作成したディレクトリに zip アーカイブを抽出します。

たとえば、CodeQL リポジトリのコピーへのパスが $HOME/codeql-home/codeql-repo の場合は、CLI を $HOME/codeql-home/ に抽出します。

5. `codeql` を起動する

前のセクションの手順 3 を参照してください。

6. CodeQL CLI のセットアップを確認する

CodeQL CLI には、データベースの作成と分析ができるように正しく設定されたことを確認するために実行できるサブコマンドがあります。

codeql resolve languages を実行すると、データベースの作成に使用できる言語が表示されます。これを使用すると、CodeQL CLI パッケージで既定でサポートされている言語が一覧表示されます。
codeql resolve qlpacks を実行して、CLI で検索できる CodeQL パックを表示します。これにより、CodeQL CLI で直接使用可能なすべての CodeQL パックの名前が表示されます。これには、次のものが含まれます。
サポートされている各言語のクエリパック (例: codeql/{language}-queries)。これらのパックには、それぞれの分析で実行される標準クエリが含まれています。
サポートされている各言語のライブラリパック (例: codeql/{language}-all)。これらのパックには、クエリの作成に役立つ制御フローやデータフローライブラリなどのクエリライブラリが含まれています。
サポートされている各言語のサンプルパック (例: codeql/{language}-examples)。これらのパックには、クエリの作成に役立つ CodeQL の便利なスニペットが含まれています。
レガシパックを使用すると、以前の製品を使用して作成されたカスタムクエリとライブラリが、お使いのバージョンの CodeQL に対応できるようになります。

CodeQL CLI の 2 つのバージョンを使用する

最新の CodeQL 機能を使用してクエリまたは CodeQL テストを実行するだけでなく、GitHub Enterprise Server で特定のバージョンの CodeQL コードスキャンと互換性のあるデータベースを準備しようとしている場合は、2 つのバージョンの CLI をインストールすることが必要になる場合があります。推奨されるディレクトリのセットアップは、インストールするバージョンによって異なります。

両方のバージョンが 2.0.2 (またはそれ以降) の場合は、両方の CLI アーカイブを同じ親ディレクトリに展開できます。
少なくとも 1 つのバージョンが 2.0.1 (またはそれ以前) の場合、展開された CLI アーカイブを同じ親ディレクトリに置くことはできませんが、同じ祖父母ディレクトリを共有できます。たとえば、バージョン 2.0.2 を $HOME/codeql-home/codeql-cli に展開するのなら、古い方のバージョンを $HOME/codeql-older-version/old-codeql-cli に展開する必要があります。ここで、一般的な祖父母は $HOME ディレクトリです。

この記事の内容