CodeQL CLI について

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

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

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

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

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

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

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 を使用したコード スキャン結果の生成について

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

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

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

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

これは、サポートされている 2 つの言語でコードベースを分析し、その結果を GitHub にアップロードするために使用できる、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 Advanced Security のライセンスをお持ちでない場合は、この製品をインストールすることで、GitHub CodeQL の使用条件に同意したことになります。

GitHub Advanced Security で GitHub Enterprise を無料で試す方法の詳細については、「GitHub Enterprise Cloud のトライアルを設定する」と GitHub Enterprise Cloud ドキュメントの「GitHub Advanced Security の無料試用版を設定する」を参照してください。