CodeQL CLI について

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

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

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

この記事の内容

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

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

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

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

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

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

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

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

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

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

メモ

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

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

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

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

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

メモ

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

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

これは、CodeQL CLI の一連のコマンドの例です。これを使用して、サポートされている 2 つの言語でコードベースを分析し、その結果を 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 を使ってエクストラクターの構成オプションを設定します。 「AUTOTITLE」を参照してください。

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

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

作業の開始

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

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

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