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.

Running CodeQL code scanning in your CI system

You can use the Executor do CodeQL to perform CodeQL Varredura de código in a third-party continuous integration system.

Varredura de código is available if you have an Segurança Avançada license.

Neste artigo

Nota: Varredura de código está atualmente em versão beta e sujeito a alterações. Para obter mais informações sobre a participação no beta, inscreva-se aqui.

Observação: O administrador do site deve habilitar Varredura de código para your GitHub Enterprise Server instance antes de usar este recurso. Para obter mais informações, consulte "Configurar o Varredura de código para seu aplicativo ".

Using CodeQL Varredura de código with your existing CI system

If you use a continuous integration or continuous delivery/deployment (CI/CD) system other than GitHub Actions, you can use your existing system to run GitHub's CodeQL analysis and upload the results to GitHub. To do this, use the Executor do CodeQL.

About the Executor do CodeQL

Varredura de código is a feature that you use to analyze the code in a GitHub repository to find security vulnerabilities and coding errors. Any problems identified by the analysis are shown in GitHub Enterprise Server. For information, see "About Varredura de código."

You can use the Executor do CodeQL to run Varredura de código on code that you're processing in a third-party continuous integration (CI) system. Alternatively, you can use GitHub Actions to run Varredura de código on your GitHub Enterprise Server instance. For information, see "Enabling Varredura de código for a repository."

The Executor do CodeQL is a command-line tool that runs CodeQL analysis on a checkout of a GitHub repository. You add the runner to your third-party system, then call the runner to analyze code and upload the results to your GitHub Enterprise Server instance. These results are displayed as Varredura de código alerts in the repository.

Observação: O Executor do CodeQL está disponível para os clientes com uma licença de Segurança Avançada.

Downloading the Executor do CodeQL

You can download the Executor do CodeQL from https://github.com/github/codeql-action/releases. On some operating systems, you may need to change permissions for the downloaded file before you can run it.

On Linux:

chmod +x codeql-runner-linux

On MacOS:

chmod +x codeql-runner-macos
sudo xattr -d com.apple.quarantine codeql-runner-macos

On Windows, the codeql-runner-win.exe file usually requires no change to permissions.

Adding the Executor do CodeQL to your CI system

Once you have downloaded the Executor do CodeQL and verified that it can be executed, you should make the runner available to each CI server that you intend to use for Varredura de código. It is important to notice that each CI server that you intend to use for Varredura de código needs to have the Executor do CodeQL. You might configure each server to copy the runner from a central, internal location, or you could use the REST API to get the runner direct from GitHub, for example:

wget https://github.com/github/codeql-action/releases/download/codeql-bundle-20200826/codeql-runner-linux 
chmod +x codeql-runner-linux

In addition to this, each CI server also needs:

  • A Aplicativos do GitHub or personal access token for the Executor do CodeQL to use. For private repositories the token must have the repo scope. For public the token needs only the public_repo and repo:security_events scopes. For information, see "Building Aplicativos do GitHub" and "Creating a personal access token."
  • Access to the CodeQL bundle associated with this release of the Executor do CodeQL. This package contains the CodeQL CLI, queries, and libraries needed for CodeQL analysis. For information, see "CodeQL CLI."

The options for providing access to the CodeQL bundle are:

  1. Allow the CI servers access to GitHub.com so that the Executor do CodeQL can download the bundle automatically.

  2. Manually download/extract the bundle, store it with other central resources, and use the --codeql-path flag to specify the location of the bundle in calls to initialize the Executor do CodeQL.

  3. You can mirror the github/codeql-action repository on your GitHub Enterprise Server instance. Unless you specify the --codeql-path flag, the runner automatically checks for the bundle in this location and on GitHub.com.

Calling the Executor do CodeQL

You should call the Executor do CodeQL from the checkout location of the repository you want to analyze. The two main commands are:

  1. init required to initialize the runner and create a CodeQL database for each language to be analyzed. These databases are populated and analyzed by subsequent commands.
  2. analyze required to populate the CodeQL databases, analyze them, and upload results to your GitHub Enterprise Server instance.

For both commands, you must specify the URL of your GitHub Enterprise Server instance, the repository OWNER/NAME, and the GitHub Apps or personal access token to use for authentication. You also need to specify the location of the CodeQL bundle unless the CI server has access to download it directly from the github/codeql-action repository on GitHub.com or mirrored on your GitHub Enterprise Server instance.

You can configure where the Executor do CodeQL stores the CodeQL bundle for future analysis on a server using the --tools-dir flag and where it stores temporary files during analysis using --temp-dir.

To view the command-line reference for the runner, use the -h flag. For example, to list all commands run: codeql-runner-OS -h, or to list all the flags available for the init command run: codeql-runner-OS init -h (where OS varies according to the executable that you are using). For more information, see "Configuring Varredura de código in your CI system."

Basic example

This example runs CodeQL analysis on a Linux CI server for the octo-org/example-repo repository hosted on https://github.example.com. The process is very simple because the repository contains only languages that can be analyzed by CodeQL directly, without being built (that is, Go, JavaScript, Python, and TypeScript).

  1. Check out the repository to analyze.

  2. Move into the directory where the repository is checked out.

  3. Initialize the Executor do CodeQL and create CodeQL databases for the languages detected.

    $ /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth TOKEN
    > Cleaning temp directory /srv/checkout/example-repo/codeql-runner
    > ...
    > Created CodeQL database at /srv/checkout/example-repo/codeql-runner/codeql_databases/javascript.
  4. Populate the Executor do CodeQL databases, analyze them, and upload the results to GitHub Enterprise Server.

    $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth TOKEN
        --commit 5b6a3078b31dc346e5ce7b86837d6abbe7a18bbd --ref refs/heads/main
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
    > Successfully uploaded results

The server has access to download the CodeQL bundle directly from the github/codeql-action repository on GitHub.com or mirrored on your GitHub Enterprise Server instance, so there is no need to use the --codeql-path flag. When the analysis is complete, the Executor do CodeQL uploads the results to the Varredura de código view. For more information, see "Managing Varredura de código alerts for your repository."

Compiled language example

This example is similar to the previous example, however this time the repository has code in C/C++, C#, or Java. To create a CodeQL database for these languages, the CLI needs to monitor the build. At the end of the initialization process, the runner reports the command you need to set up the environment before building the code. You need to run this command, before calling the normal CI build process, and then running the analyze command.

  1. Check out the repository to analyze.

  2. Move into the directory where the repository is checked out.

  3. Initialize the Executor do CodeQL and create CodeQL databases for the languages detected.

    $ /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo-2
        --github-url https://github.example.com --github-auth TOKEN
    > Cleaning temp directory /srv/checkout/example-repo-2/codeql-runner
    > ...
    > CodeQL environment output to "/srv/checkout/example-repo-2/codeql-runner/codeql-env.json"
      and "/srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".
      Please export these variables to future processes so the build can be traced, for example by running "
      . /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".
  4. Run the script generated by the init action to set up the environment to monitor the build.

    $ . /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh
  5. Build the code.

  6. Populate the CodeQL databases, analyze them, and upload the results to GitHub.

    $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo-2
        --github-url https://github.example.com --github-auth TOKEN
        --commit ae7b655ef30b50fb726ae7b3daa79571a39d194d --ref refs/heads/main
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo-2/code-scanning/sarifs - 202 in 573ms
    > Successfully uploaded results

Note: If you use a containerized build, you need to run the Executor do CodeQL in the container where your build task takes place.

Further reading

Esse documento ajudou você?

Privacy policy

Ajude-nos a tornar esses documentos ótimos!

Todos os documentos do GitHub são de código aberto. Você percebeu que algo que está errado ou não está claro? Envie um pull request.

Faça uma contribuição

Ou, aprenda como contribuir.