Skip to main content

此版本的 GitHub Enterprise 将停止服务 2023-01-18. 即使针对重大安全问题,也不会发布补丁。 为了获得更好的性能、更高的安全性和新功能,请升级到最新版本的 GitHub Enterprise。 如需升级帮助,请联系 GitHub Enterprise 支持

Configuring CodeQL runner in your CI system

You can configure how the CodeQL runner scans the code in your project and uploads the results to GitHub.

Code scanning 可用于 GitHub Enterprise Server 中的组织拥有的存储库。 此功能需要 GitHub Advanced Security 的许可证。 有关详细信息,请参阅“关于 GitHub Advanced Security”。

Note: The CodeQL runner is being deprecated. On GitHub Enterprise Server 3.0 and greater, you can install CodeQL CLI version 2.6.3 to replace CodeQL runner.

For more information, see the CodeQL runner deprecation. For information on migrating to CodeQL CLI, see "Migrating from the CodeQL runner to CodeQL CLI."

Note: Your site administrator must enable code scanning for your GitHub Enterprise Server instance before you can use this feature. For more information, see "Configuring code scanning for your appliance."

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 runner 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.

Scanning pull requests

Scanning code whenever a pull request is created prevents developers from introducing new vulnerabilities and errors into the code.

To scan a pull request, run the analyze command and use the --ref flag to specify the pull request. The reference is refs/pull/<PR-number>/head or refs/pull/<PR-number>/merge, depending on whether you have checked out the HEAD commit of the pull request branch or a merge commit with the base branch.

$ /path/to-runner/codeql-runner-linux analyze --ref refs/pull/42/merge

Note: If you analyze code with a third-party tool and want the results to appear as pull request checks, you must run the upload command and use the --ref flag to specify the pull request instead of the branch. The reference is refs/pull/<PR-number>/head or refs/pull/<PR-number>/merge.

Overriding automatic language detection

The CodeQL runner automatically detects and scans code written in the supported languages.

  • C/C++
  • C#
  • Go
  • Java
  • JavaScript/TypeScript
  • Python

For more information, see the documentation on the CodeQL website: "Supported languages and frameworks."

如果存储库包含的代码支持多种语言,可以选择要分析的语言。 有几种原因可能使你想阻止对某种语言进行分析。 例如,项目中可能有其他语言的代码主体依赖项,你可能不想看到这些依赖项的警报。

To override automatic language detection, run the init command with the --languages flag, followed by a comma-separated list of language keywords. The keywords for the supported languages are cpp, csharp, go, java, javascript, and python.

$ /path/to-runner/codeql-runner-linux init --languages cpp,java

Running additional queries

When you use CodeQL to scan code, the CodeQL analysis engine generates a database from the code and runs queries on it. CodeQL analysis uses a default set of queries, but you can specify more queries to run, in addition to the default queries.

Any additional queries you want to run must belong to a QL pack in a repository. For more information, see "About code scanning with CodeQL."

You can specify a single .ql file, a directory containing multiple .ql files, a .qls query suite definition file, or any combination. For more information about query suite definitions, see "Creating CodeQL query suites."

以下查询套件内置于 CodeQL code scanning,可供使用。

查询套件说明
security-extended查询的严重性和精度低于默认查询
security-and-quality来自 security-extended 的查询,以及可维护性和可靠性查询。

指定查询套件时,CodeQL 分析引擎将运行默认查询集和其他查询套件中定义的任何其他查询。

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 flag instead of any in the configuration file. If you want to run the combined set of additional queries specified with the flag and in the configuration file, prefix the value passed to --queries with the + symbol. For more information, see "Using a custom configuration file."

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

Using a custom configuration file

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. For more information, see "Workflow syntax for GitHub Actions."

Use the --config-file flag of the init command to specify the configuration file. The value of --config-file is the path to the configuration file that you want to use. This example loads the configuration file .github/codeql/codeql-config.yml.

$ /path/to-runner/codeql-runner-linux init --config-file .github/codeql/codeql-config.yml

配置文件可以位于正在分析的存储库中,也可以位于外部存储库中。 使用外部存储库可以在一个位置为多个存储库指定配置选项。 引用位于外部存储库中的配置文件时,可以使用 OWNER/REPOSITORY/FILENAME@BRANCH 语法。 例如, octo-org/shared/codeql-config.yml@main

Example configuration files

当扫描代码时,此配置文件将 security-and-quality 查询套件添加到 CodeQL 运行的查询列表中。 有关可供使用的查询套件的详细信息,请参阅“运行其他查询”。

name: "My CodeQL config"

queries:
  - uses: security-and-quality

以下配置文件禁用默认查询,并指定一组要运行的自定义查询。 它还配置 CodeQL 以扫描 src 目录(相对于根目录)中的文件,除了 src/node_modules 目录和名称以 .test.js 结尾的文件 。 因此,src/node_modules 中的文件和名称以 .test.js 结尾的文件被排除在分析之外 。

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'

Configuring code scanning for compiled languages

For the compiled languages C/C++, C#, and Java, CodeQL builds the code before analyzing it. 对于这些语言,CodeQL 分析生成的存储库中的源文件。 对于上述任何语言,可以禁用 autobuild 并改用自定义生成命令,以仅分析这些自定义命令生成的文件。

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 runner in your CI system."

Uploading code scanning data to GitHub

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.

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.

FlagRequiredInput value
--repositoryName of the repository to initialize.
--github-urlURL of the GitHub instance where your repository is hosted.
--github-auth-stdinRead the GitHub Apps token or personal access token from standard input.
--languagesComma-separated list of languages to analyze. By default, the CodeQL runner detects and analyzes all supported languages in the repository.
--queriesComma-separated list of additional queries to run, in addition to the default suite of security queries. This overrides the queries setting in the custom configuration file.
--config-filePath to custom configuration file.
--codeql-pathPath to a copy of the CodeQL CLI executable to use. By default, the CodeQL runner downloads a copy.
--temp-dirDirectory where temporary files are stored. The default is ./codeql-runner.
--tools-dirDirectory where CodeQL tools and other files are stored between runs. The default is a subdirectory of the home directory.
--checkout-pathThe path to the checkout of your repository. The default is the current working directory.
--debugNone. Prints more verbose output.
--trace-process-nameAdvanced, Windows only. Name of the process where a Windows tracer of this process is injected.
--trace-process-levelAdvanced, Windows only. Number of levels up of the parent process where a Windows tracer of this process is injected.
-h, --helpNone. 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.

FlagRequiredInput value
--languageThe language to build. By default, the CodeQL runner builds the compiled language with the most files.
--temp-dirDirectory where temporary files are stored. The default is ./codeql-runner.
--debugNone. Prints more verbose output.
-h, --helpNone. Displays help for the command.

analyze

Analyzes the code in the CodeQL databases and uploads results to GitHub Enterprise Server.

FlagRequiredInput value
--repositoryName of the repository to analyze.
--commitSHA 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.
--refName of the reference to analyze, for example refs/heads/main or refs/pull/42/merge. In Git or in Jenkins, this corresponds to the value of git symbolic-ref HEAD. In Azure DevOps, this corresponds to $(Build.SourceBranch).
--github-urlURL of the GitHub instance where your repository is hosted.
--github-auth-stdinRead the GitHub Apps token or personal access token from standard input.
--checkout-pathThe path to the checkout of your repository. The default is the current working directory.
--no-uploadNone. Stops the CodeQL runner from uploading the results to GitHub Enterprise Server.
--output-dirDirectory where the output SARIF files are stored. The default is in the directory of temporary files.
--ramAmount of memory to use when running queries. The default is to use all available memory.
--no-add-snippetsNone. Excludes code snippets from the SARIF output.
--categoryCategory 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>.automationDetails.id property in SARIF v2.1.0.
--threadsNumber of threads to use when running queries. The default is to use all available cores.
--temp-dirDirectory where temporary files are stored. The default is ./codeql-runner.
--debugNone. Prints more verbose output.
-h, --helpNone. Displays help for the command.

upload

Uploads SARIF files to GitHub Enterprise Server.

Note: If you analyze code with the CodeQL runner, the analyze command uploads SARIF results by default. You can use the upload command to upload SARIF results that were generated by other tools.

FlagRequiredInput value
--sarif-fileSARIF file to upload, or a directory containing multiple SARIF files.
--repositoryName of the repository that was analyzed.
--commitSHA 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.
--refName of the reference that was analyzed, for example refs/heads/main or refs/pull/42/merge. In Git or in Jenkins, this corresponds to the value of git symbolic-ref HEAD. In Azure DevOps, this corresponds to $(Build.SourceBranch).
--github-urlURL of the GitHub instance where your repository is hosted.
--github-auth-stdinRead the GitHub Apps token or personal access token from standard input.
--checkout-pathThe path to the checkout of your repository. The default is the current working directory.
--debugNone. Prints more verbose output.
-h, --helpNone. Displays help for the command.