Note: The CodeQL runner is currently in beta and subject to change.
About configuring CodeQL code scanning in your CI system
To integrate code scanning into your CI system, you can use the CodeQL runner. For more information, see "Running CodeQL code scanning in your CI system."
In general, you invoke the CodeQL runner as follows.
$ /path/to-runner/codeql-runner-OS
/path/to-runner/
depends on where you've downloaded the CodeQL runner on your CI system. codeql-runner-OS
depends on the operating system you use. There are three versions of the CodeQL runner, codeql-runner-linux
, codeql-runner-macos
, and codeql-runner-win
, for Linux, macOS, and Windows systems respectively.
To customize the way the CodeQL runner scans your code, you can use flags, such as --languages
and --queries
, or you can specify custom settings in a separate configuration file.
自動言語検出をオーバーライドする
The CodeQL runner automatically detects and scans code written in the supported languages.
- C/C++
- C#
- Go
- Java
- JavaScript/TypeScript
- Python
If your repository contains code in more than one of the supported languages, you can choose which languages you want to analyze. 言語が分析されないようにする理由はいくつかあります。 たとえば、プロジェクトには、コードの本文とは異なる言語の依存関係があり、それらの依存関係のアラートを表示する必要がない場合があります。
To override automatic language detection, run the init
command with the --languages
flag, followed by a comma-separated list of language keywords. サポートされている言語のキーワードは、cpp
、csharp
、go
、java
、JavaScript
、および python
です。
$ /path/to-runner/codeql-runner-linux init --languages cpp,java
追加のクエリを実行する
When you use CodeQL to scan code, the CodeQL analysis engine generates a database from the code and runs queries on it. For more information, see "About code scanning."
CodeQL analysis uses a default set of queries, but you can specify more queries to run, in addition to the default queries. 実行するクエリは、QL パックに属している必要があり、独自のリポジトリまたは任意のパブリックリポジトリに格納することができます。 詳しい情報については、「QL パックについて」を参照してください。
クエリは、標準ライブラリ(クエリの import LANGUAGE
ステートメントで参照されるライブラリ)、またはクエリと同じ QL パック内のライブラリにのみ依存している必要があります。 標準ライブラリは github/codeql リポジトリにあります。 For more information, see "About CodeQL queries."
単一の .ql ファイル、複数の .ql ファイルを含むディレクトリ、.qls クエリスイート定義ファイル、または任意の組み合わせを指定できます。 For more information about query suite definitions, see "Creating CodeQL query suites."
We don't recommend referencing query suites directly from the github/codeql
repository, like github/codeql/cpp/ql/src@main
. Such queries may not be compiled with the same version of CodeQL as used for your other queries, which could lead to errors during analysis.
The following query suites are built into CodeQL code scanning and are available for use.
クエリスイート | 説明 |
---|---|
security-extended | デフォルトのクエリよりも重要度と精度が低いクエリ |
security-and-quality | security-extended からのクエリ、および保守性と信頼性に関するクエリ |
When you specify a query suite, the CodeQL analysis engine will run the queries contained within the suite for you, in addition to the default set of queries.
To add one or more queries, pass a comma-separated list of paths to the --queries
flag of the init
command. You can also specify additional queries in a configuration file.
If you also are using a configuration file for custom settings, and you are also specifying additional queries with the --queries
flag, the CodeQL runner uses the additional queries specified with the --queries
--queries
+
symbol. 設定ファイルの例については、「Example configuration files」を参照してください。
In the following example, the +
symbol ensures that the CodeQL runner uses the additional queries together with any queries specified in the referenced configuration file.
$ /path/to-runner/codeql-runner-linux init --config-file .github/codeql/codeql-config.yml
--queries +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
サードパーティのコードスキャンツールを使用する
Instead of passing additional information to the CodeQL runner commands, you can specify custom settings in a separate configuration file.
The configuration file is a YAML file. It uses syntax similar to the workflow syntax for GitHub Actions, as illustrated in the examples below. 詳細については、「GitHub Actionsのワークフロー構文」を参照してください。
Use the --config-file
flag of the init
command to specify the configuration file. The value of --config-file
$ /path/to-runner/codeql-runner-linux init --config-file .github/codeql/codeql-config.yml
設定ファイルの例
この設定ファイルは、コードのスキャン時に CodeQL によって実行されるクエリのリストに security-and-quality
クエリスイートを追加します。 使用可能なクエリスイートの詳細については、「追加のクエリを実行する」を参照してください。
name: "My CodeQL config"
queries:
- uses: security-and-quality
The following configuration file disables the default queries and specifies a set of custom queries to run instead. It also configures CodeQL to scan files in the src directory (relative to the root), except for the src/node_modules directory, and except for files whose name ends in .test.js. Files in src/node_modules and files with names ending .test.js are therefore excluded from analysis.
name: "My CodeQL config"
disable-default-queries: true
queries:
- name: Use an in-repository QL pack (run queries in the my-queries directory)
uses: ./my-queries
- name: Use an external JavaScript QL pack (run queries from an external repo)
uses: octo-org/javascript-qlpack@main
- name: Use an external query (run a single query from an external QL pack)
uses: octo-org/python-qlpack/show_ifs.ql@main
- name: Use a query suite file (run queries from a query suite in this repo)
uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls
paths:
- src
paths-ignore:
- src/node_modules
- '**/*.test.js'
コンパイルされた言語の code scanning を設定する
For the compiled languages C/C++, C#, and Java, CodeQL builds the code before analyzing it. CodeQL also runs a build for Go projects to set up the project. However, in contrast to the other compiled languages, all Go files in the repository are extracted, not just those that are built. Custom build commands are not supported for Go.
For many common build systems, the CodeQL runner can build the code automatically. To attempt to build the code automatically, run autobuild
between the init
and analyze
steps. Note that if your repository requires a specific version of a build tool, you may need to install the build tool manually first.
The autobuild
process only ever attempts to build one compiled language for a repository. The language automatically selected for analysis is the language with the most files. If you want to choose a language explicitly, use the --language
flag of the autobuild
command.
$ /path/to-runner/codeql-runner-linux autobuild --language csharp
If the autobuild
command can't build your code, you can run the build steps yourself, between the init
and analyze
steps. For more information, see "Running CodeQL code scanning in your CI system."
code scanning 用の設定ファイルを作成できます。
By default, the CodeQL runner uploads results from code scanning when you run the analyze
command. You can also upload SARIF files separately, by using the upload
command.
Once you've uploaded the data, GitHub displays the alerts in your repository. For more information, see "Managing code scanning alerts for your repository."
CodeQL runner command reference
The CodeQL runner supports the following commands and flags.
init
Initializes the CodeQL runner and creates a CodeQL database for each language to be analyzed.
Flag | 必須 | Input value |
---|---|---|
--repository | ✓ | Name of the repository to initialize. |
--github-url | ✓ | URL of the GitHub instance where your repository is hosted. |
--github-auth | ✓ | A GitHub Apps token or personal access token. |
--languages | Comma-separated list of languages to analyze. By default, the CodeQL runner detects and analyzes all supported languages in the repository. | |
--queries | Comma-separated list of additional queries to run, in addition to the default suite of security queries. | |
--config-file | Path to custom configuration file. | |
--codeql-path | Path to a copy of the CodeQL CLI executable to use. By default, the CodeQL runner downloads a copy. | |
--temp-dir | Directory where temporary files are stored. The default is ./codeql-runner. | |
--tools-dir | Directory where CodeQL tools and other files are stored between runs. The default is a subdirectory of the home directory. | |
--checkout-path | The path to the checkout of your repository. The default is the current working directory. | |
--debug | なし. Prints more verbose output. | |
-h , --help | なし. Displays help for the command. |
autobuild
Attempts to build the code for the compiled languages C/C++, C#, and Java. For those languages, CodeQL builds the code before analyzing it. Run autobuild
between the init
and analyze
steps.
Flag | 必須 | Input value |
---|---|---|
--language | The language to build. By default, the CodeQL runner builds the compiled language with the most files. | |
--temp-dir | Directory where temporary files are stored. The default is ./codeql-runner. | |
--debug | なし. Prints more verbose output. | |
-h , --help | なし. Displays help for the command. |
analyze
Analyzes the code in the CodeQL databases and uploads results to GitHub.
Flag | 必須 | Input value |
---|---|---|
--repository | ✓ | Name of the repository to analyze. |
--commit | ✓ | SHA of the commit to analyze. In Git and in Azure DevOps, this corresponds to the value of git rev-parse HEAD . In Jenkins, this corresponds to $GIT_COMMIT . |
--ref | ✓ | Name of the reference to analyze, for example refs/heads/main . In Git and in Jenkins, this corresponds to the value of git symbolic-ref HEAD . In Azure DevOps, this corresponds to $(Build.SourceBranch) . |
--github-url | ✓ | URL of the GitHub instance where your repository is hosted. |
--github-auth | ✓ | A GitHub Apps token or personal access token. |
--checkout-path | The path to the checkout of your repository. The default is the current working directory. | |
--no-upload | なし. Stops the CodeQL runner from uploading the results to GitHub. | |
--output-dir | Directory where the output SARIF files are stored. The default is in the directory of temporary files. | |
--ram | Amount of memory to use when running queries. The default is to use all available memory. | |
--no-add-snippets | なし. Excludes code snippets from the SARIF output. | |
--threads | Number of threads to use when running queries. The default is to use all available cores. | |
--temp-dir | Directory where temporary files are stored. The default is ./codeql-runner. | |
--debug | なし. Prints more verbose output. | |
-h , --help | なし. Displays help for the command. |
アップロード
Uploads SARIF files to GitHub.
Flag | 必須 | Input value |
---|---|---|
--sarif-file | ✓ | SARIF file to upload, or a directory containing multiple SARIF files. |
--repository | ✓ | Name of the repository that was analyzed. |
--commit | ✓ | SHA of the commit that was analyzed. In Git and in Azure DevOps, this corresponds to the value of git rev-parse HEAD . In Jenkins, this corresponds to $GIT_COMMIT . |
--ref | ✓ | Name of the reference that was analyzed, for example refs/heads/main . In Git and in Jenkins, this corresponds to the value of git symbolic-ref HEAD . In Azure DevOps, this corresponds to $(Build.SourceBranch) . |
--github-url | ✓ | URL of the GitHub instance where your repository is hosted. |
--github-auth | ✓ | A GitHub Apps token or personal access token. |
--checkout-path | The path to the checkout of your repository. The default is the current working directory. | |
--debug | なし. Prints more verbose output. | |
-h , --help | なし. Displays help for the command. |