Note: The CodeQLランナー is being deprecated. On GitHub Enterprise Server 3.0 and greater, you can install CodeQL CLI version 2.6.3 to replace CodeQLランナー.
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ランナー. For more information, see "Running CodeQLランナー in your CI system."
In general, you invoke the CodeQLランナー as follows.
$ /path/to-runner/codeql-runner-OS
/path/to-runner/
depends on where you've downloaded the CodeQLランナー on your CI system. codeql-runner-OS
depends on the operating system you use.
There are three versions of the CodeQLランナー, codeql-runner-linux
, codeql-runner-macos
, and codeql-runner-win
, for Linux, macOS, and Windows systems respectively.
To customize the way the CodeQLランナー 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ランナー automatically detects and scans code written in the supported languages.
- C/C++
- C#
- Go
- Java
- JavaScript/TypeScript
- Python
リポジトリがサポートされている言語を複数含む� �合、分析したい言語を選択できます。 言語が分析されないようにする理由はいくつかあります。 たとえば、プロジェクトには、コードの本文とは異なる言語の依存関係があり、それらの依存関係のアラートを表示する必要がない� �合があります。
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
コードをスキャンするためにCodeQLを使う� �合、CodeQL分析エンジンはコードからデータベースを生成し、それに対してクエリを実行します。 CodeQLの分析はデフォルトのクエリセットを使いますが、デフォルトのクエリに� えてもっと多くのクエリを実行するよう指定することもできます。
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."
単一の .ql ファイル、複数の .ql ファイルを含むディレクトリ、.qls クエリスイート定義ファイル、または任意の組み合わせを指定できます。 クエリスイートの定義に関する詳しい情� �については「CodeQLクエリスイートの作成」を参照してく� さい。
以下のクエリスイートはCodeQL code scanningに組み込まれており、利用可能です。
クエリスイート | 説明 |
---|---|
security-extended | デフォルトのクエリよりも重要度と精度が低いクエリ |
security-and-quality | security-extended からのクエリ、および保守性と信� �性に関するクエリ |
When you specify a query suite, the CodeQL analysis engine will run the default set of queries and any extra queries defined in the additional query suite.
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ランナー uses the additional queries specified with the --queries
--queries
+
symbol.
For more information, see "Using a custom configuration file."
In the following example, the +
symbol ensures that the CodeQLランナー 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ランナー 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
$ /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
この設定ファイルは、コードのスキャン時に CodeQL によって実行されるクエリのリストに security-and-quality
クエリスイートを追� します。 使用可能なクエリスイートの詳細については、「追� のクエリを実行する」を参照してく� さい。
name: "My CodeQL config"
queries:
- uses: security-and-quality
以下の設定ファイルはデフォルトのクエリを無効化し、その代わりに実行するカスタ� クエリのセットを指定します。 また、CodeQLがsrc/node_modulesディレクトリと.test.jsで名前が終わるファイルを除く、srcディレクトリ(ルートに対する相対)内のファイルをスキャンするようにも設定します。 したがって、 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は、プロジェクトをセットアップするためにGoのプロジェクトのビルドも実行します。 た� し、他のコンパイル言語とは対照的に、リポジトリ内のGoのファイルはビルドされるもの� けでなく、すべてが展開されます。 ビルドが処理しないGoのファイルの展開をスキップするために、カスタ� のビルドコマンドを使うこともできます。
For many common build systems, the CodeQLランナー 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ランナー in your CI system."
Uploading code scanning data to GitHub
By default, the CodeQLランナー 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.
- If you uploaded to a pull request, for example
--ref refs/pull/42/merge
or--ref refs/pull/42/head
, then the results appear as alerts in a pull request check. For more information, see "Triaging code scanning alerts in pull requests." - If you uploaded to a branch, for example
--ref refs/heads/my-branch
, then the results appear in the Security tab for your repository. For more information, see "Managing code scanning alerts for your repository."
CodeQLランナー command reference
The CodeQLランナー supports the following commands and flags.
init
Initializes the CodeQLランナー and creates a CodeQL database for each language to be analyzed.
Flag | Required | 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ランナー 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. This overrides the queries setting in the custom configuration file. | |
--config-file | Path to custom configuration file. | |
--codeql-path | Path to a copy of the CodeQL CLI executable to use. By default, the CodeQLランナー 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 | None. Prints more verbose output. | |
--trace-process-name | Advanced, Windows only. Name of the process where a Windows tracer of this process is injected. | |
--trace-process-level | Advanced, Windows only. Number of levels up of the parent process where a Windows tracer of this process is injected. | |
-h , --help | None. 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 | Required | Input value |
---|---|---|
--language | The language to build. By default, the CodeQLランナー builds the compiled language with the most files. | |
--temp-dir | Directory where temporary files are stored. The default is ./codeql-runner . | |
--debug | None. Prints more verbose output. | |
-h , --help | None. Displays help for the command. |
analyze
Analyzes the code in the CodeQL databases and uploads results to GitHub Enterprise Server.
Flag | Required | 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 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-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 | None. Stops the CodeQLランナー from uploading the results to GitHub Enterprise Server. | |
--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 | None. 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 | None. Prints more verbose output. | |
-h , --help | None. 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.
Flag | Required | 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 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-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 | None. Prints more verbose output. | |
-h , --help | None. Displays help for the command. |