Configuring CodeQL runner in your CI system

About configuring CodeQL Varredura de código in your CI system

To integrate Varredura de código into your CI system, you can use the Executor do CodeQL. For more information, see "Running Executor do CodeQL in your CI system."

In general, you invoke the Executor do CodeQL as follows.

$ /path/to-runner/codeql-runner-OS  

/path/to-runner/ depends on where you've downloaded the Executor do CodeQL on your CI system. codeql-runner-OS depends on the operating system you use. There are three versions of the Executor do CodeQL, codeql-runner-linux, codeql-runner-macos, and codeql-runner-win, for Linux, macOS, and Windows systems respectively.

To customize the way the Executor do 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

Overriding automatic language detection

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

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

Se o seu repositório contiver código em mais de uma das linguagens compatíveis, você poderá escolher quais linguagens deseja analisar. Há vários motivos para impedir que uma linguagem seja analisada. Por exemplo, o projeto pode ter dependências em uma linguagem diferente do texto principal do seu código, e você pode preferir não ver os alertas para essas dependências.

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

Ao usar CodeQL para fazer a varredura do código, o mecanismo de análise de CodeQL gera um banco de dados do código e executa consultas no mesmo. A análise de CodeQL usa um conjunto-padrão de consultas, mas você pode especificar outras consultas a serem executadas, além das consultas-padrão.

Any additional queries you want to run must belong to a QL pack in a repository. For more information, see "About Varredura de código with CodeQL."

Você pode especificar um único arquivo .ql, um diretório que contém múltiplos arquivos .ql, um arquivo de definição de suite de consultas .qls ou qualquer outra combinação. Para obter mais informações sobre definições do conjunto de consultas, consulte "Criar as conjuntos de consulta do CodeQL".

Os conjuntos de consulta a seguir foram criados em CodeQL Varredura de código e estão disponíveis para uso.

Suite de consulta	Descrição
security-extended	Consultas de menor gravidade e precisão que as consultas-padrão
security-and-quality	Consultas de security-extended, mais consultas de manutenção e confiabilidade

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 Executor do CodeQL 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 Executor do 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 Executor do 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 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

O arquivo de configuração pode ser localizado no repositório que você está analisando ou em um repositório externo. O uso de um repositório externo permite especificar opções de configuração para vários repositórios em um único lugar. Ao fazer referência a um arquivo de configuração localizado em um repositório externo, você pode usar a sintaxe OWNER/REPOSITORY/FILENAME@BRANCH. Por exemplo, octo-org/shared/codeql-config.yml@main.

Example configuration files

Este arquivo de configuração adiciona o suite de consulta de security-and-quality para a lista de consultas executadas por CodeQL ao fazer a varredura do seu código. Para obter mais informações sobre o suite de consultas disponível para uso, consulte "Executar consultas adicionais".

name: "My CodeQL config"

queries:
  - uses: security-and-quality

O seguinte arquivo de configuração desabilita as consultas-padrão e especifica um conjunto de consultas personalizadas para serem executadas. Também configura CodeQL para fazer a varredura de arquivos no diretório src (relativo �  raiz), exceto o diretório src/node_modules e os arquivos cujo nome termina com .test.js. Os arquivos em src/node_modules e arquivos com nomes terminados em .test.js são, portanto, excluídos da análise.

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 Varredura de código for compiled languages

For the compiled languages C/C++, C#, and Java, CodeQL builds the code before analyzing it. CodeQL também executa uma criação para projetos Go para configurar o projeto. Entretanto, diferente das outras linguagens compiladas, todos os Go no repositório são extraídos, não apenas aqueles construídos. Você pode usar comandos de criação personalizados para ignorar arquivos de Go de extração que não são tocados pela compilação.

For many common build systems, the Executor do 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 Executor do CodeQL in your CI system."

Uploading Varredura de código data to GitHub

By default, the Executor do CodeQL uploads results from Varredura de código 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."

Executor do CodeQL command reference

The Executor do CodeQL supports the following commands and flags.

init

Initializes the Executor do 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 Aplicativos do GitHub token or personal access token.
--languages		Comma-separated list of languages to analyze. By default, the Executor do 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 Executor do 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 Executor do 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 Aplicativos do GitHub 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 Executor do 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.

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 Aplicativos do GitHub 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.