CodeQL CLI について

CodeQL CLI を使うと、ソフトウェアプロジェクトで CodeQL プロセスをローカル実行したり、code scanning の結果を生成し、GitHub Enterprise Server にアップロードしたりできます。

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

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

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

この記事の内容

ソフトウェア開発者とセキュリティ研究者は、CodeQL 分析を使ってコードをセキュリティ保護できます。 CodeQL について詳しくは、「CodeQL によるコードスキャンについて」をご覧ください。

CodeQL CLI は、コードの分析に使うことができるスタンドアロンのコマンドラインツールです。その主な目的は、コードベースのデータベース表現であるCodeQLデータベースを生成することです。データベースの準備ができたら、それに対して対話形式でクエリを実行することや、一連のクエリを実行して SARIF 形式で結果セットを生成し、結果をお使いの GitHub Enterprise Server インスタンスにアップロードすることができます。

CodeQL CLI を使って次のことができます。

GitHub エンジニアとオープンソースコミュニティによって提供されるクエリを使って、CodeQL の分析を実行します
GitHub Enterprise Server に表示する目的でアップロードできるコードスキャンアラートを生成します。
CodeQL 拡張機能の Visual Studio Code で使用する CodeQL データベースを作成します。
独自の分析で使うカスタム CodeQL クエリを開発してテストします

CodeQL CLI では、次を分析できます。

たとえばJavaScriptやPythonのような動的言語。
コンパイル型言語 (例: C/C++、C#、Go、Java
複数言語を組み合わせて書かれたコードベース。

CodeQL CLI の設定について詳しくは、「CodeQL CLI の設定」をご覧ください。

code scanningのためのCodeQL CLIの利用について

CodeQL CLI を使用すると、サードパーティの継続的インテグレーション (CI) システム内で処理するコードに code scanning を実行できます。 Code scanning は、GitHub リポジトリ内のコードを分析して、セキュリティの脆弱性とコーディングエラーを見つけることができる機能です。分析によって特定された問題は、リポジトリに表示されます。外部 CI システムでのコードスキャンの使用の概要については、「既存の CI システムでコードスキャンを使用する」をご覧ください。 CodeQL 分析を実行するための推奨仕様 (RAM、CPU コア数、ディスク) については、「CodeQL を実行するための推奨ハードウェアリソース」をご覧ください。

あるいは、GitHub Actions か Azure DevOps パイプラインを使い、CodeQL CLI でコードをスキャンできます。詳細については、「コードスキャンの既定セットアップの構成」または Microsoft Learn で「GitHub Advanced Security for Azure DevOps を構成する」を参照してください。

コードスキャンに CodeQL 分析を使用するためのすべてのオプションの概要については、「CodeQL によるコードスキャンについて」を参照してください。

メモ:

CodeQL CLI は、Advanced Security のライセンスを持つ顧客が使うことができます。
CodeQL CLI は現在、glibc 以外の Linux ディストリビューション ((musl ベースの) Alpine Linux など) との互換性がありません。

CodeQL CLI を使用したコードスキャン結果の生成について

CodeQL CLI を直接実行する場合、まず、CodeQL CLI をローカルにインストールする必要があります。外部 CI システムで CodeQL CLI を使用する予定の場合は、CI システム内のサーバーで CodeQL CLI を使用できるようにする必要があります。詳しくは、「CodeQL CLI の設定」を参照してください。

CodeQL CLI が設定されたら、3 つの異なるコマンドを使って結果を生成し、それを GitHub Enterprise Server にアップロードできます。

database create では、リポジトリのサポートされている各プログラミング言語の階層構造を表すために CodeQL データベースを作成します。詳しくは、「CodeQL 分析のためのコードの準備」を参照してください。
database analyze では、クエリを実行して各 CodeQL データベースを分析し、結果を SARIF ファイルにまとめます。詳しくは、「CodeQL クエリによるコード分析」を参照してください。
github upload-results では、結果の SARIF ファイルを GitHub Enterprise Server にアップロードします。そこで結果はブランチまたは pull request と照合され、code scanning アラートとして表示されます。詳しくは、「CodeQL 分析結果を GitHub にアップロードする」を参照してください。

注: GitHub Enterprise Server の結果の code scanning として表示する SARIF データをアップロードすることは、GitHub Advanced Security が有効にされた組織が所有するリポジトリ。詳しくは、「リポジトリのセキュリティと分析設定を管理する」を参照してください。

CodeQL分析のためのCIの設定例

これは、サポートされている 2 つの言語でコードベースを分析し、その結果を GitHub Enterprise Server にアップロードするために使用できる、CodeQL CLI の一連のコマンドの例です。

# Create CodeQL databases for Java and Python in the 'codeql-dbs' directory
# Call the normal build script for the codebase: 'myBuildScript'

codeql database create codeql-dbs --source-root=src \
    --db-cluster --language=java,python --command=./myBuildScript

# Analyze the CodeQL database for Java, 'codeql-dbs/java'
# Tag the data as 'java' results and store in: 'java-results.sarif'

codeql database analyze codeql-dbs/java java-code-scanning.qls \
    --format=sarif-latest --sarif-category=java --output=java-results.sarif

# Analyze the CodeQL database for Python, 'codeql-dbs/python'
# Tag the data as 'python' results and store in: 'python-results.sarif'

codeql database analyze codeql-dbs/python python-code-scanning.qls \
    --format=sarif-latest --sarif-category=python --output=python-results.sarif

# Upload the SARIF file with the Java results: 'java-results.sarif'
# The GitHub App or personal access token created for authentication
# with GitHub's REST API is available in the `GITHUB_TOKEN` environment variable.

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=java-results.sarif

# Upload the SARIF file with the Python results: 'python-results.sarif'

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=python-results.sarif

GitHub CodeQL のライセンスについて

ライセンスに関する注意: GitHub Enterprise ライセンスをお持ちでない場合は、この製品をインストールすることで、GitHub CodeQL の使用条件に同意したことになります。

GitHub CodeQL のライセンスは、ユーザーごとに付与されます。ライセンスの制限の下で、CodeQL を使って次のタスクを実行できます。

学術研究を行う。
ソフトウェアのデモを行う。
OSI 承認済みライセンスの下でリリースされた CodeQL クエリをテストし、それらのクエリの新しいバージョンで引き続き適切な脆弱性が検出されることを確認する。

"OSI 承認済みライセンス" とは、オープンソースイニシアティブ (OSI) が承認したオープンソースソフトウェアライセンスを意味します。

オープンソースコードベース (つまり、OSI 承認済みライセンスの下でリリースされたコードベース) を使用している場合は、次のタスクに CodeQL を使うこともできます。

オープンソースコードベースの分析を実行する。
オープンソースコードベースが GitHub.com でホストおよび保守されている場合、自動分析、継続的インテグレーション、または継続的デリバリーのために、またはそれらの間に、CodeQL データベースを生成する。

GitHub Advanced Security のライセンスがない限り、ここに記載されている場合を除き、通常のソフトウェアエンジニアリングプロセスの一部であるかどうかにかかわらず、自動分析、継続的インテグレーション、または継続的デリバリーに CodeQL を使用することはできません。