CodeQL コマンドラインインターフェース (CLI)

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

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

CodeQL は、次の種類のリポジトリで使用できます:

この記事で

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

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

CodeQL CLIを使用すると、次のことができます。

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

CodeQL CLIは以下を分析できます。

  • たとえばJavaScriptやPythonのような動的言語。
  • コンパイル済み言語 (例: C/C++、C#、Go、Java、Kotlin、Rust (パブリック プレビュー)、and Swift
  • 複数言語を組み合わせて書かれたコードベース。

CodeQL CLI での code scanning の使用について

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

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

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

メモ

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

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

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

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

  1. database create リポジトリでサポートされている各プログラミング言語の階層構造を表す CodeQL データベースを作成します。 詳細については、「CodeQL 分析用コードを準備する」を参照してください。
  2. database analyze クエリを実行して各 CodeQL データベースを分析し、結果を SARIF ファイルにまとめます。 詳細については、「Analyzing your code with CodeQL queries」を参照してください。
  3. github upload-results を使用して、生成された SARIF ファイルを GitHub にアップロードすると、結果がブランチまたはプル リクエストに関連付けられ、code scanning アラートとして表示されます。 詳細については、「CodeQL 分析結果をGitHubにアップロードする」を参照してください。

メモ

code scanning で GitHub の結果として表示する SARIF データのアップロードは、GitHub Code Security が有効になっている organization 所有のリポジトリでサポートされます。 詳しくは、「リポジトリのセキュリティと分析設定を管理する」をご覧ください。

CodeQL分析の CI 構成例

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

# 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

データベースの抽出

CodeQL CLIでは、抽出器と呼ばれる特別なプログラムを使用して、ソフトウェア システムのソース コードからクエリ可能なデータベースに情報を抽出します。 エクストラクターの動作をカスタマイズするには、 CodeQL CLIを使用して抽出器の構成オプションを設定します。 「エクストラクターのオプション」を参照してください。

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

ライセンスに関する注意: GitHub Code Security のライセンスをお持ちでない場合、この製品をインストールすると、GitHubCodeQL の使用条件に同意したものと見なされます。

データベース バンドル CodeQL CLI について

CodeQL CLI データベース バンドル コマンドを使用して、CodeQL データベースの再配置可能なアーカイブを作成できます。

データベース バンドルのコピーを使用して、トラブルシューティング情報をチーム メンバーや GitHub のサポートと共有できます。 「CodeQL CLI データベース バンドルを作成する」を参照してください。

作業の開始

最も簡単な作業を開始する方法については、 CodeQL CLI を設定する を参照してください。

必要に応じて、より高度なセットアップ オプションを使用できます。 たとえば、次の場合です。

  • 共有のオープンソース CodeQL クエリに貢献し、CodeQL ソースコードを直接扱うことを望む場合。 「CodeQL CLI ソース コードの取得」を参照してください。
  • 複数のバージョンの CodeQL CLI をサイド バイ サイドでインストールする必要があります。 たとえば、あるコードベースで特定のバージョンが必要で、別のコードベースが最新バージョンを使用する場合などです。 各バージョンをダウンロードし、両方の CLI アーカイブを同じ親ディレクトリにアンパックできます。
  • クエリを調査または開発しており、 GitHub.comからデータベースをダウンロードしたいと考えています。 「GitHubから CodeQL データベースをダウンロードする」を参照してください。