About the CodeQL CLI

You can use the CodeQL CLI to run CodeQL processes locally on software projects or to generate code scanning results for upload to GitHub.

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

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

この記事の内容

Software developers and security researchers can secure their code using CodeQL analysis. For more information about CodeQL, see About code scanning with CodeQL.

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

You can use the CodeQL CLI to:

  • Run CodeQL analyses using queries provided by GitHub engineers and the open source community
  • Generate code scanning alerts that you can upload to display in GitHub
  • Create CodeQL databases to use in the CodeQL for Visual Studio Code extension.
  • Develop and test custom CodeQL queries to use in your own analyses

The CodeQL CLI can analyze:

  • Dynamic languages, for example, JavaScript and Python.
  • Compiled languages, for example, C/C++、C#、Go、Java、Kotlin、Rust (パブリック プレビュー)、、Swift
  • Codebases written in a mixture of languages.

For information about setting up the CodeQL CLI, see CodeQL CLI の設定.

About using the CodeQL CLI for code scanning

You can use the CodeQL CLI to run code scanning on code that you're processing in a third-party continuous integration (CI) system. Code scanning は、GitHub リポジトリ内のコードを分析して、セキュリティの脆弱性とコーディング エラーを見つけることができる機能です。 分析によって特定された問題は、リポジトリに表示されます。 For an overview of using code scanning with external CI systems, see 既存の CI システムでコード スキャンを使用する. For recommended specifications (RAM, CPU cores, and disk) for running CodeQL analysis, see CodeQL を実行するための推奨ハードウェア リソース.

Alternatively, you can use GitHub Actions or Azure DevOps pipelines to scan code using the CodeQL CLI. For more information, see コード スキャンの既定セットアップの構成 or Configure GitHub Advanced Security for Azure DevOps in Microsoft Learn.

For an overview of all the options for using CodeQL analysis for code scanning, see About code scanning with CodeQL.

メモ

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

About generating code scanning results with the CodeQL CLI

If you choose to run the CodeQL CLI directly, you first have to install the CodeQL CLI locally. If you are planning to use the CodeQL CLI with an external CI system, you need to make the CodeQL CLI available to servers in your CI system. For more information, see CodeQL CLI の設定.

Once the CodeQL CLI is set up, you can use three different commands to generate results and upload them to GitHub:

  1. database create to create a CodeQL database to represent the hierarchical structure of each supported programming language in the repository. For more information, see CodeQL 分析のためのコードの準備.
  2. database analyze to run queries to analyze each CodeQL database and summarize the results in a SARIF file. For more information, see CodeQL クエリによるコード分析.
  3. github upload-results to upload the resulting SARIF files to GitHub where the results are matched to a branch or pull request and displayed as code scanning alerts. For more information, see CodeQL 分析結果を GitHub にアップロードする.

メモ

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

Example CI configuration for CodeQL analysis

This is an example of the full series of commands for the CodeQL CLI that you might use to analyze a codebase with two supported languages and then upload the results to 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

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

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