CodeQL CLI の高度なセットアップ

About advanced setup of the CodeQL CLI について

コードスキャン以外の目的で CodeQL を使用する場合は、CodeQL CLI の高度なセットアップの使用をお勧めします。

オープンソースの共有 CodeQL クエリにコントリビューションしたい場合は、CodeQL ソースコードを直接操作することをお勧めします。
最新の CodeQL 機能を使用してコードベースのコードスキャンアラートを生成し、且つをインストールできます。
クエリを調査または開発している場合は、GitHub.com から興味深いデータベースまたは一意のデータベースをダウンロードできます。

CodeQL CLI の最も簡単な設定については、「CodeQL CLI の設定」を参照してください。

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

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

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 からのクエリとライブラリの互換性のあるバージョン
バンドルに含まれるすべてのクエリのプリコンパイル済みバージョン

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

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

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

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.com からダウンロードしたデータベースには、このブランチを使用する必要があります。
最新の CodeQL クエリについては、main ブランチをチェックアウトします。このブランチは、CodeQL の分析の最新バージョンを表します。

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

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

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

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

5. `codeql` を起動する

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

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

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

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 をインストールすることが必要になる場合があります。必要な CodeQL CLI のバージョンをダウンロードし、両方の CLI アーカイブを同じ親ディレクトリに解凍できます。

GitHub.comからのデータベースのダウンロード

GitHub では、REST API を使用してダウンロードできる 200,000 を超えるリポジトリの CodeQL データベースを GitHub.com に保存しています。リポジトリの一覧は、セキュリティ調査のための最も興味深いコードベースが確実に含まれるように、絶えず増加し、進化しています。

VS Code 拡張機能の CodeQL を使用して、GitHub.com からデータベースを分析することもできます。詳しくは、「CodeQL クエリの実行」を参照してください。

/repos/<owner>/<repo>/code-scanning/codeql/databases エンドポイントを使用して、リポジトリにダウンロード可能な CodeQL データベースがあるかどうかを確認できます。たとえば、GitHub CLI を使用して CodeQL データベースの有無を確認するには、次のように実行します。

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases

このコマンドからは、リポジトリで使用できる CodeQL データベースに関する情報が返されます。データベースが表す言語や、データベースが最後に更新された日時などです。使用できる CodeQL データベースがない場合、応答は空です。

目的の言語の CodeQL データベースが存在することを確認したら、次のコマンドを使用してダウンロードできます。

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases/<language> -H 'Accept: application/zip' > path/to/local/database.zip

詳しくは、「CodeQL データベースエンドポイントの取得」のドキュメントを参照してください。

CodeQL CLI を使用して分析を実行する前に、データベースを解凍する必要があります。