CodeQL CLI について

CodeQL CLI について

ソフトウェア開発者とセキュリティ研究者は、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 でコードをスキャンできます。 詳細については、"About the CodeQL CLI" または Microsoft Learn で GitHub Advanced Security for Azure DevOps を構成するを参照してください。

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

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

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

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

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

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 を使用することはできません。