Publicamos atualizações frequentes em nossa documentação, e a tradução desta página ainda pode estar em andamento. Para obter as informações mais recentes, acesse a documentação em inglês. Se houver problemas com a tradução desta página, entre em contato conosco.

Configuring code scanning

You can configure how GitHub scans the code in your project for vulnerabilities and errors.

People with write permissions to a repository can configure Varredura de código for the repository.

Neste artigo

Note: Varredura de código is currently in beta and subject to change. To request access to the beta, join the waitlist.

About Varredura de código configuration

Varredura de código uses GitHub Actions. Before you can configure Varredura de código for a repository, you must enable Varredura de código by adding a GitHub Actions workflow to the repository. For more information, see "Enabling Varredura de código."

Typically, you don't need to edit the default workflow for Varredura de código. You can edit the workflow to specify the frequency of scans, the languages or directories to scan, and what Varredura de código looks for in your code. You might also need to edit the workflow if you use a specific set of commands to compile your code.

For more information about editing workflow files, see "Configuring a workflow."

Configuring frequency

You can scan code on a schedule or when specific events occur in a repository.

For example, the following configuration scans on push, on creation of a pull request, and on a schedule.

on:
  push:
  pull_request:
  schedule:
    - cron: '0 15 * * 0'

Scanning code on every push to the repository, and every time a pull request is created, prevents developers from introducing new vulnerabilities and errors into the code. Scanning code on a schedule informs you about the latest vulnerabilities and errors that GitHub, security researchers, and the community discover, even when developers aren't actively maintaining the repository.

Scanning on push

The default Varredura de código workflow uses the on.push event to trigger a code scan on every push to any branch containing the workflow file. Para obter mais informações, consulte "Sintaxe de fluxo de trabalho para o GitHub Actions".

We don't recommend using the branches keyword to limit on.push to specific branches. If you specify branches for on.push, Varredura de código will only run when you push branches that you specify in the workflow.

Scanning pull requests

The default Varredura de código workflow uses the pull_request event to trigger a code scan on the HEAD commit of a pull request. Scanning on the pull_request event doesn't work if you open a pull request from a private fork.

For more information about the pull_request event, see "Workflow syntax for GitHub Actions."

Scanning on a schedule

If you use the default workflow, Varredura de código will scan the code in your repository once a week, in addition to the scans triggered by events. To adjust this schedule, edit the cron value in the workflow. Para obter mais informações, consulte "Sintaxe de fluxo de trabalho para o GitHub Actions".

Note: GitHub only runs scheduled jobs that are in workflows on the default branch. Changing the schedule in a workflow on any other branch has no effect until you merge the branch into the default branch.

Specifying an operating system

If your code requires a specific operating system to compile, you can configure this in your workflow. Edit the value of jobs.<job_id>.runs-on to specify the operating system for the machine that runs your Varredura de código actions. Varredura de código supports the latest versions of macOS, Ubuntu, and Windows. For more information, see "Workflow syntax for GitHub Actions."

Overriding automatic language detection

Varredura de código automatically detects and scans code written in the supported languages.

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

If your repository contains code in multiple languages, you can specify the languages you want to analyze. There are several reasons you might want to prevent a language being analyzed. For example, the project might have dependencies in a different language to the main body of your code, and you might prefer not to see alerts for those dependencies.

To override automatic language detection, add with:languages: to the init action in your workflow. The keywords for the supported languages are cpp, csharp, go, java, javascript, and python.

For example, the following configuration limits Varredura de código to C/C++, C#, and Python.

- uses: github/codeql-action/init@v1
  with:
    languages: cpp, csharp, python

Adding build steps for a compiled language

For C/C++, C#, and Java, the autobuild step in the default workflow attempts to build code before the action performs CodeQL analysis. In contrast to the other compiled languages, CodeQL analyzes Go without building the code.

If the C/C++, C#, or Java in your repository has a non-standard build process, autobuild may fail. If this happens, remove the autobuild action from the workflow, and uncomment the run step.

The run step runs command-line programs using the operating system's shell. You can modify these commands and add more commands to customize the build process.

- run: |
  make bootstrap
  make release

For more information about the run keyword, see "Workflow syntax for GitHub Actions."

Accessing private repositories

If your workflow for Varredura de código accesses private repositories on GitHub, you'll need to configure Git to authenticate with a personal access token. Define the secret in the runner environment by using jobs.<job_id>.steps.env in your workflow before any CodeQL actions. For more information, see "Creating a personal access token for the command line" and "Creating and storing encrypted secrets."

For example, the following configuration has Git replace the full URLs to the github/foo, github/bar, and github/baz repositories on GitHub.com with URLs that include the personal access token that you store in the ACCESS_TOKEN environment variable.

steps:
- name: Configure access to private repository on GitHub.com
  env:
    TOKEN: ${{ secrets.ACCESS_TOKEN }}
  run: |
    git config --global url."https://${TOKEN}@github.com/github/foo".insteadOf "https://github.com/github/foo"
    git config --global url."https://${TOKEN}@github.com/github/bar".insteadOf "https://github.com/github/bar"
    git config --global url."https://${TOKEN}@github.com/github/baz".insteadOf "https://github.com/github/baz"

Using a custom configuration

You can write a configuration file for Varredura de código. A configuration file can specify which queries to run and which directories to scan.

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

- uses: github/codeql-action/init@v1
  with:
    config-file: ./.github/codeql/codeql-config.yml

The configuration file must be located within the local repository. For examples of configuration files, see "Example configuration files."

Running additional queries

When you enable Varredura de código, GitHub's CodeQL analysis engine generates a database from the code and runs queries on it. Para obter mais informações, consulte "Sobre o Varredura de código".

You can run additional queries by specifying these in a configuration file. The queries you want to run must belong to a QL pack and can be in your own repository or any public repository. For more information, see "About QL packs."

Queries must only depend on the standard libraries (that is, the libraries referenced by an import LANGUAGE statement in your query), or libraries in the same QL pack as the query. The standard libraries are located in the github/codeql repository. For more information, see "Introduction to query files."

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

To add one or more queries, add a queries section to your configuration file.

queries:
  - name: DESCRIPTION OF YOUR CHOICE
    uses: PATH

You can also run additional query suites by specifying these in a configuration file. Query suites are collections of queries, usually grouped by purpose or language.

The following query suites are built into Varredura de código and available for use in your configuration file.

Query suiteDescrição
security-extendedQueries of lower severity and precision than the default queries
security-and-qualityQueries from security-extended, plus maintainability and reliability queries

When you specify a query suite in your configuration file, the CodeQL analysis engine will run the queries contained in the suite for you, in addition to the default set of queries.

To add one or more query suites, add a queries section to your configuration file.

queries:
 - uses: security-and-quality

We don't recommend referencing query suites for uses directly from the github/codeql repository, like github/codeql/cpp/ql/src@master. Such queries may not be compiled with the same version of CodeQL as the version used in your configuration file, which could lead to errors during analysis.

Disabling the default queries

If you only want to run custom queries, you can disable the default security queries by adding disable-default-queries: true to your configuration file.

Specifying directories to scan

For the interpreted languages that CodeQL supports (Python and JavaScript/TypeScript), you can restrict Varredura de código to files in specific directories by using the paths keyword in the configuration file. You can exclude the files in specific directories from scans by using the paths-ignore keyword.

Note: The paths and paths-ignore keywords, used in the context of the Varredura de código configuration file, should not be confused with the same keywords when used for on.<push|pull_request>.paths. When they are used to modify on.<push|pull_request> in a workflow file, they determine whether the actions will be run when someone modifies code in the specified directories. Para obter mais informações, consulte "Sintaxe de fluxo de trabalho para o GitHub Actions".

For C/C++, C#, and Java, if you want to limit Varredura de código to specific directories in your project, you must specify appropriate build steps in the workflow. The commands you need to use to exclude a directory from the build will depend on your build system. For more information, see "Adding build steps for a compiled language."

You can quickly analyze small portions of a monorepo when you modify code in specific directories. You'll need to both exclude directories in your build steps and use the paths-ignore and paths keywords for on.<push|pull_request> in your workflow file.

Example configuration files

This configuration file adds the security-and-quality query suite to the list of queries run by CodeQL when scanning your code. For more information about the query suites available for use, see "Running additional queries."

name: "My CodeQL config"

queries:
  - uses: security-and-quality

This 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, including all of its subdirectories except for one called node_modules.

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@master
  - name: Use an external query (run a single query from an external QL pack)
    uses: octo-org/python-qlpack/show_ifs.ql@master
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

paths-ignore: 
  - '/node_modules/'
paths:
  - '/src' 

Using a third-party code scanning tool

You can display code analysis from a third-party tool in GitHub by adding the upload-sarif action to your workflow. For more information, see "Uploading a SARIF file to GitHub."

Pergunte a uma pessoa

Não consegue encontrar o que procura?

Entrar em contato