CodeQL CLI の使用を開始する

CodeQL CLI の使用を開始する

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

CodeQL CLI を設定する

CodeQL CLI は、さまざまなユース ケースとディレクトリ構造をサポートするように設定できます。

すぐに使い始めるには、次の手順で説明するように、比較的簡単なセットアップを採用することをお勧めします。 Linux、Windows、または macOS バージョン 10.14 ("Mojave") 以前を使用している場合は、次の手順に従ってください。

macOS バージョン 10.15 ("Catalina") 以降の場合、手順 1 と 4 は若干異なります。詳しくは、「macOS "Catalina" (またはそれ以降) のユーザー向けの情報」というラベルの付いたセクションを参照してください。 Apple シリコン (Apple M1 など) の macOS を使用している場合は、Xcode コマンド ライン開発者ツールと Rosetta 2 がインストールされていることを確認します。

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

1. CodeQL CLI の zip パッケージをダウンロードする

CodeQL CLI ダウンロード パッケージは、ツールおよびスクリプトと、さまざまな CodeQL 固有のファイルを含む zip アーカイブです。

GitHub Enterprise ライセンスをお持ちでない場合は、このアーカイブをダウンロードすることで、GitHub CodeQL の使用条件に同意したことになります。

Linux、Windows、または macOS バージョン 10.14 ("Mojave") 以前を使用している場合は、必要なバージョンの zip アーカイブをダウンロードするだけです。

特定のプラットフォーム用の CLI が必要な場合は、適切な codeql-PLATFORM.zip ファイルをダウンロードします。

または、サポートされているすべてのプラットフォーム用の CLI を含む codeql.zip をダウンロードすることもできます。 macOS "Catalina" (またはそれ以降) のユーザー向けの情報

macOS バージョン 10.15 ("Catalina")、バージョン 11 ("Big Sur")、または今後のバージョン 12 ("Monterey") を使用する場合は、Web ブラウザーで zip ファイルが自動的に抽出されないようにする必要があります。

Safari を使用している場合は、CodeQL CLI の zip アーカイブをダウンロードする前に、次の手順を実行します。 Safari を開きます。

1. [Safari] メニューの [環境設定...] を選びます。
2. [一般] タブをクリックします。
3. [ダウンロード後、"安全な" ファイルを開く] というラベルの付いたチェック ボックスがオフになっていることを確認します。
4. 2. zip アーカイブを抽出する

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

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

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

3. codeql を起動する

4. mv ~/Downloads/codeql\*.zip ${extraction-root}

5. cd ${extraction-root}

6. /usr/bin/xattr -c codeql\*.zip

7. unzip codeql\*.zip

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

<extraction-root>/codeql/codeql を実行します。ここで、<extraction-root> は CodeQL CLI パッケージを抽出したフォルダーです。

• <extraction-root>/codeql を PATH に追加すると、実行可能ファイルを codeql として実行することができます。
• この時点で、CodeQL のコマンドを実行できます。

CodeQL CLI コマンドの完全な一覧については、「CodeQL CLI マニュアル」を参照してください。

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

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

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 フラグを使用して、分析中にクエリ パックをダウンロードすることもできます。

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

オープンソースの共有クエリについて取り組んだり貢献したりするために、CodeQL のクエリ ソースを直接操作することを希望するユーザーもいます。

これを行うには、次の手順をお勧めします。 次の手順は、上で説明した CodeQL パッケージの操作に代わる、やや複雑な方法であることに注意してください。 1. CodeQL CLI の zip をダウンロードする

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

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

CLI と、使用するクエリとライブラリを配置できる新しいディレクトリを作成します。

たとえば、$HOME/codeql-home のようにします。 CLI の組み込み検索操作を行うと、データベースの作成と分析で使用されるファイルのすべての兄弟ディレクトリが自動的に検索されます。

これらのコンポーネントをそれぞれ独自のディレクトリに保持すると、関連のない兄弟ディレクトリは CLI で検索されず、コマンド ラインで追加のオプションを指定せずにすべてのファイルを使用できます。 3. CodeQL クエリのローカル コピーを取得する

CodeQL リポジトリには、サポートされているすべての言語の CodeQL 分析に必要なクエリとライブラリが含まれています。

このリポジトリのコピーを codeql-home にクローンします。 既定では、クローンされたリポジトリのルートは codeql と呼ばれます。

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

このリポジトリでは、クエリとライブラリが CodeQL パックにまとめられています。

CodeQL パックには、クエリ自体に加えて、クエリ ファイルの処理方法を CodeQL CLI に指示する重要なメタデータが含まれています。 詳しくは、「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 ディレクトリです。 Here, the common grandparent is the $HOME directory.