Running CodeQL CLI in your CI system

CodeQL CLI を使用して、、サードパーティの継続的インテグレーションシステムで CodeQL code scanning を実行できます。

Code scanningは、Organizationが所有するGitHub Advanced Securityが有効化されたすべてのパブリック及びプライベートリポジトリで利用できます。 詳しい情報については、「GitHub Advanced Security について」を参照してください。

ここには以下の内容があります:

CodeQL CLI について

CodeQL CLI を使用して、サードパーティ継続的インテグレーション (CI) システムで処理しているコード上で code scanning を実行できます。 Code scanning は、開発者が GitHub リポジトリ内のコードを分析して、セキュリティの脆弱性とコーディングエラーを見つけることができる機能です。 分析によって特定されたすべての問題はGitHubに表示されます。詳細については、「code scanning について」を参照してください。

CodeQL CLIは、コードの分析に利用できるスタンドアローンの製品です。 その主な目的は、コードベースのデータベース表現であるCodeQLデータベースを生成することです。 データベースの準備ができれば、それに対してインタラクティブにクエリを実行したり、SARIFフォーマットで結果セットを生成するためのクエリのスイートを実行して、結果をGitHubにアップロードしたりできます。

Alternatively, you can use CodeQLランナー in your CI system, or GitHub Actions to run code scanning within GitHub. For an overview of the options for CI systems, see "About CodeQL code scanning in your CI system". For information about code scanning using actions, see "Setting up code scanning for a repository."

Note: The CodeQL CLI is free to use on public repositories that are maintained on GitHub.com, and available to use on private repositories that are owned by customers with an Advanced Security license. 詳細については「GitHub CodeQLの利用規約」及び「CodeQL CLI」を参照してください。

CodeQL CLI をダウンロードする

You should download the CodeQL bundle from https://github.com/github/codeql-action/releases. The bundle contains:

  • CodeQL CLI product
  • A compatible version of the queries and libraries from https://github.com/github/codeql
  • Precompiled versions of all the queries included in the bundle

You should always use the CodeQL bundle as this ensures compatibility and also gives much better performance than a separate download of the CodeQL CLI and checkout of the CodeQL queries. If you will only be running the CLI on one specific platform, download the appropriate codeql-bundle-PLATFORM.tar.gz file. Alternatively, you can download codeql-bundle.tar.gz, which contains the CLI for all supported platforms.

Setting up the CodeQL CLI in your CI system

You need to make the full contents of the CodeQL CLI bundle available to every CI server that you want to run CodeQL code scanning analysis on. For example, you might configure each server to copy the bundle from a central, internal location and extract it. Alternatively, you could use the REST API to get the bundle directly from GitHub, ensuring that you benefit from the latest improvements to queries. Updates to the CodeQL CLI are released every 2-3 weeks. 例:

$ wget https://github.com/github/codeql-action/releases/latest/download/codeql-bundle-linux64.tar.gz
$ tar -xvzf ../codeql-bundle-linux64.tar.gz

After you extract the CodeQL CLI bundle, you can run the codeql executable on the server:

  • By executing /extraction-root/codeql/codeql, where <extraction-root> is the folder where you extracted the CodeQL CLI bundle.
  • By adding /extraction-root/codeql to your PATH, so that you can run the executable as just codeql.

Testing the CodeQL CLI set up

After you extract the CodeQL CLI bundle, you can run the following command to verify that the CLI is correctly set up to create and analyze databases.

  • codeql resolve languages if /extraction-root/codeql is on the PATH.
  • /extraction-root/codeql/codeql resolve languages otherwise.

Example of successful output:

cpp (/extraction-root/codeql/cpp)
csharp (/extraction-root/codeql/csharp)
csv (/extraction-root/codeql/csv)
go (/extraction-root/codeql/go)
html (/extraction-root/codeql/html)
java (/extraction-root/codeql/java)
javascript (/extraction-root/codeql/javascript)
properties (/extraction-root/codeql/properties)
python (/extraction-root/codeql/python)
xml (/extraction-root/codeql/xml)

If the CodeQL CLI is unable to resolve the expected languages, check that you downloaded the CodeQL bundle and not a standalone copy of the CodeQL CLI.

Generating a token for authentication with GitHub

Each CI server needs a GitHub App or personal access token for the CodeQL CLI to use to upload results to GitHub. You must use an access token or a GitHub App with the security_events write permission. If CI servers already use a token with this scope to checkout repositories from GitHub, you could potentially allow the CodeQL CLI to use the same token. Otherwise, you should create a new token with the security_events write permission and add this to the CI system's secret store. 詳細は「GitHub Apps をビルドする」および「個人アクセストークンを作成する」を参照してください。

Using the CodeQL CLI to generate data and upload it to GitHub

You call the CodeQL CLI to analyze the codebase in three steps:

  1. Create a CodeQL database to represent a single programming language in the repository using: codeql database create
  2. Run queries to analyze the CodeQL database and summarize the results in a SARIF file using: codeql database analyze
  3. Upload the SARIF file to GitHub where the results are matched to a branch or pull request and displayed as code scanning alerts using: codeql github upload-results

Each command has a few mandatory options with additional options that you can use to modify the behavior of the command. You can display the command-line help for any command using the --help option.

ノート: GitHubでcode scanningの結果として表示するためにSARIFデータをアップロードすることは、GitHub Advanced Securityが有効化されたOrganizationが所有するリポジトリとGitHub.com上のパブリックリポジトリでサポートされています。 詳しい情報については「リポジトリのセキュリティ及び分析の設定の管理」を参照してください。

Creating a CodeQL database to analyze

  1. Check out the code that you want to analyze:

    • For a branch checkout the head of the branch that you want to analyze.
    • For a pull request checkout either the head commit of the pull request, or check out a GitHub-generated merge commit of the pull request.
  2. Set up the environment for the codebase, making sure that any dependencies are available. For more information, see Creating databases for non-compiled languages and Creating databases for compiled languages in the documentation for the CodeQL CLI.

  3. Run codeql database create from the checkout root of your repository.

    codeql database create <database> --language=<language-identifier>

    Note: If you use a containerized build, you need to run the CodeQL CLI inside the container where your build task takes place.

Option 必須 使い方
<database> Specify the name and location of a directory to create for the CodeQL database. The command will fail if you try to overwrite an existing directory.
`--language` Specify the identifier for the language to create a database for, one of: `cpp`、`csharp`、`go`、`java`、`javascript`、`python` (use javascript to analyze TypeScript code).
`--source-root` 任意. Use if you run the CLI outside the checkout root of the repository. By default, the database create command assumes that the current directory is the root directory for the source files, use this option to specify a different location.
`--command` Optional for compiled languages. Use if you want to override the CLI's automatic build system detection and compilation. Specify the build command or script that invokes the compiler. Commands are run from the current folder or, where it is defined, from `--source-root`. Do not use this option for Python and JavaScript/TypeScript analysis.

For more information, see Creating CodeQL databases in the documentation for the CodeQL CLI.

基本的な例
$ codeql database create /codeql-dbs/example-repo --language=javascript \
    --source-root /checkouts/example-repo

> Initializing database at /codeql-dbs/example-repo.
> Running command [/codeql-home/codeql/javascript/tools/autobuild.cmd]
    in /checkouts/example-repo.
> [build-stdout] Single-threaded extraction.
> [build-stdout] Extracting
... 
> Finalizing database at /codeql-dbs/example-repo.
> Successfully created database at /codeql-dbs/example-repo.

For more information and examples, see Creating CodeQL databases in the documentation for the CodeQL CLI.

Analyzing a CodeQL database

  1. Create a CodeQL database (see above).
  2. Run codeql database analyze on the database and specify which queries to use.
    codeql database analyze <database> --format=<format> \
        --output=<output>  <queries> 
Option 必須 使い方
<database> Specify the path for the directory that contains the CodeQL database to analyze.
<queries> Specify the queries to run. To run the standard queries used for code scanning, use: <language>-code-scanning.qls where <language> is the short code for the language of the database. To see the other query suites included in the CodeQL CLI bundle look in /extraction-root/codeql/qlpacks/codeql-<language>/codeql-suites. For information about creating your own query suite, see Creating CodeQL query suites in the documentation for the CodeQL CLI.
`--format` Specify the format for the results file generated by the command. For upload to GitHub this should be: sarif-latest. 詳しい情報については「code scanningの SARIF サポート」を参照してください。
`--output` Specify where to save the SARIF results file.
--sarif-category 任意. Specify a category to include in the SARIF results file for this analysis. A category can be used to distinguish multiple analyses for the same tool and commit, but performed on different languages or different parts of the code. This value will appear in the <run>.automationId property in SARIF v1, the <run>.automationLogicalId property in SARIF v2, and the <run>.automationDetails.id property in SARIF v2.1.0. |
`--threads` 任意. Use if you want to use more than one thread to run queries. The default value is 1. You can specify more threads to speed up query execution. To set the number of threads to the number of logical processors, specify 0.

For more information, see Analyzing databases with the CodeQL CLI in the documentation for the CodeQL CLI.

基本的な例
$ codeql database analyze /codeql-dbs/example-repo  \
    javascript-code-scanning.qls --format=sarif-latest \
    --output=/temp/example-repo-js.sarif

> Running queries.
> Compiling query plan for /codeql-home/codeql/qlpacks/
    codeql-javascript/AngularJS/DisablingSce.ql.
... 
> Shutting down query evaluator.
> Interpreting results.

Uploading results to GitHub

ノート: SARIFのアップロードは、アップロードごとに最大で5000件の結果をサポートしています。 この制限を超えた結果は無視されます。 ツールがあまりに多くの結果を生成する場合、最も重要なルールやクエリに対する結果に焦点を当てるよう、設定を更新すべきです。

Before you can upload results to GitHub, you must determine the best way to pass the GitHub App or personal access token you created earlier to the CodeQL CLI (see Generating a token for authentication with GitHub above). We recommend that you review your CI system's guidance on the secure use of the secret store. The CodeQL CLI supports:

  • Passing the token to the CLI via standard input using the --github-auth-stdin option (recommended).
  • Saving the secret in the environment variable GITHUB_TOKEN and running the CLI without including the --github-auth-stdin option.

When you have decided on the most secure and reliable method for your CI server, run codeql github upload-results on the SARIF results file and include --github-auth-stdin unless the token is available in the environment variable GITHUB_TOKEN.

echo "$UPLOAD_TOKEN" | codeql github upload-results --repository=<repository-name> \
      --ref=<ref> --commit=<commit> --sarif=<file> \
      --github-auth-stdin
Option 必須 使い方
`--repository` Specify the OWNER/NAME of the repository to upload data to. The owner must be an organization within an enterprise that has a license for GitHub Advanced Security and GitHub Advanced Security must be enabled for the repository, unless the repository is public. 詳しい情報については「リポジトリのセキュリティ及び分析の設定の管理」を参照してください。
`--ref` Specify the name of the ref you checked out and analyzed so that the results can be matched to the correct code. For a branch use: refs/heads/BRANCH-NAME, for the head commit of a pull request use refs/pulls/NUMBER/head, or for the GitHub-generated merge commit of a pull request use refs/pulls/NUMBER/merge.
`--commit` Specify the full SHA of the commit you analyzed.
`--sarif` Specify the SARIF file to load.
`--github-auth-stdin` 任意. Use to pass the CLI the GitHub App or personal access token created for authentication with GitHub's REST API via standard input. This is not needed if the command has access to a GITHUB_TOKEN environment variable set with this token.

For more information, see github upload-results in the documentation for the CodeQL CLI.

基本的な例
$ echo $UPLOAD_TOKEN | codeql  github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif --github-auth-stdin

There is no output from this command unless the upload was unsuccessful. The command prompt returns when the upload is complete and data processing has begun. On smaller codebases, you should be able to explore the code scanning alerts in GitHub shortly afterward. Alerts are shown directly in the pull request or on the Security tab for branches, depending on the code that was checked out. For more information, see "Triaging code scanning alerts in pull requests" and "Managing code scanning alerts for your repository."

参考リンク

このドキュメントは役立ちましたか?プライバシーポリシー

これらのドキュメントを素晴らしいものにするのを手伝ってください!

GitHubのすべてのドキュメントはオープンソースです。間違っていたり、はっきりしないところがありましたか?Pull Requestをお送りください。

コントリビューションを行う

OR, コントリビューションの方法を学んでください。

問題がまだ解決していませんか?

GitHubコミュニティで質問するサポートへの連絡