Nota: El Ejecutor de CodeQL se va a obsoletizar. En GitHub Enterprise Server 3.0 y superior, puedes instalar el CodeQL CLI versión 2.6.3 para reemplazar el Ejecutor de CodeQL.
Para obtener más información, consulta la obsoletización del ejecutor de CodeQL. Para obtener más información sobre cómo migrarse al CodeQL CLI, consulta la sección "Migrarse desde el ejecutor de CodeQL al CLI de CodeQL".
Nota: Tu administrador de sitio debe habilitar el escaneo de código para tu instancia de GitHub Enterprise Server antes de que puedas utilizar esta característica. Para obtener más información, consulta "Configurar el escaneo de código en tu aplicativo."
About the Ejecutor de CodeQL
The Ejecutor de CodeQL is a tool you can use to run escaneo de código on code that you're processing in a third-party continuous integration (CI) system. Escaneo de código es una característica que utilizas para analizar el código en un repositorio de GitHub para encontrar vulnerabilidades de seguridad y errores de código. Cualquier problema que se identifique con el análisis se muestra en GitHub Enterprise Server. For information, see "About escaneo de código with CodeQL."
Alternatively, you can use GitHub Actions to run escaneo de código within GitHub Enterprise Server. For information, see "Setting up escaneo de código for a repository."
The Ejecutor de 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 GitHub Enterprise Server. These results are displayed as escaneo de código alerts in the repository.
Note:
-
The Ejecutor de CodeQL is available to customers with an Advanced Security license.
-
The Ejecutor de CodeQL shouldn't be confused with the CodeQL CLI. The CodeQL CLI is a command-line interface that lets you create CodeQL databases for security research and run CodeQL queries. For more information, see "CodeQL CLI."
Downloading the Ejecutor de CodeQL
You can download the Ejecutor de CodeQL from https://HOSTNAME/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 Ejecutor de CodeQL to your CI system
Once you download the Ejecutor de CodeQL and verify that it can be executed, you should make the runner available to each CI server that you intend to use for escaneo de código. For example, you might configure each server to copy the runner from a central, internal location. Alternatively, you could use the REST API to get the runner directly from GitHub, for example:
wget https://HOSTNAME/github/codeql-action/releases/latest/download/codeql-runner-linux
chmod +x codeql-runner-linux
In addition to this, each CI server also needs:
- A GitHub App or personal access token for the Ejecutor de CodeQL to use. You must use an access token with the
repo
scope, or a GitHub App with thesecurity_events
write permission, andmetadata
andcontents
read permissions. For information, see "Building GitHub Apps" and "Creating a personal access token." - Access to the CodeQL bundle associated with this release of the Ejecutor de CodeQL. This package contains queries and libraries needed for CodeQL analysis, plus the CodeQL CLI, which is used internally by the runner. For information, see "CodeQL CLI."
The options for providing access to the CodeQL bundle are:
- Allow the CI servers access to https://HOSTNAME/github/codeql-action so that the Ejecutor de CodeQL can download the bundle automatically.
- Manually download/extract the bundle, store it with other central resources, and use the
flag to specify the location of the bundle in calls to initialize the Ejecutor de CodeQL.--codeql-path
Calling the Ejecutor de CodeQL
You should call the Ejecutor de CodeQL from the checkout location of the repository you want to analyze. The two main commands are:
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.analyze
required to populate the CodeQL databases, analyze them, and upload results to GitHub Enterprise Server.
For both commands, you must specify the URL of GitHub Enterprise Server, 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.
You can configure where the Ejecutor de CodeQL stores the CodeQL bundle for future analysis on a server using the --tools-dir
--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 escaneo de código in your CI system."
Notas:
-
La carga de SARIF es compatible con un máximo de 1000 resultados por carga. Cualquier resultado que sobrepase este límite se ignorará. Si una herramienta genera demasiados resultados, debes actualizar la configuración para enfocarte en los resultados de las reglas o consultas más importantes.
-
Para cada carga, la carga de SARIF es compatible con un tamaño máximo de 10 MB para el archivo comprimido de
gzip
. Cualquier carga que esté sobre este límite, se rechazará. Si tu archivo SARIF es demasiado grande porque contiene demasiados resultados, debes actualizar la configuración para enfocarte en los resultados de las reglas o consultas más importantes.
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).
In this example, the server has access to download the CodeQL bundle directly from the github/codeql-action
repository, so there is no need to use the --codeql-path
flag.
-
Check out the repository to analyze.
-
Move into the directory where the repository is checked out.
-
Initialize the Ejecutor de 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
-
Llena las bases de datos de CodeQL, analízalas, y carga los resultados aGitHub Enterprise Server. Los resultados aparecerán en la pestaña de Seguridad de tu repositorio.
$ /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/my-branch > Finalizing database creation > ... > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms > Successfully uploaded results
-
Para cargar los resultados del escaneo de código como verificaciones de solicitudes de cambios, especifica la solicitud de cambios utilizando el mrcador
. Te recomendamos configurar el Ejecutor de CodeQL para que se ejecute en el evento de webhook--ref
pull_request
.$ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo --github-url https://github.example.com --github-auth TOKEN --commit 1dc7a1346e5ce7b86835b68bbda3078b37d6abbe --ref refs/pull/123/merge > Finalizing database creation > ... > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms > Successfully uploaded results
Para obtener más información acerca de visualizar las alertas del escaneo de código, consulta las secciones "Clasificar las alertas del escaneo de código en las solicitudes de cambios" y "Administrar las alertas del escaneo de código para tu repositorio".
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.
-
Check out the repository to analyze.
-
Move into the directory where the repository is checked out.
-
Initialize the Ejecutor de 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
-
Source the script generated by the
init
action to set up the environment to monitor the build. Note the leading dot and space in the following code snippet.$ . /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh
-
Build the code. On macOS, you need to prefix the build command with the environment variable
$CODEQL_RUNNER
. For more information, see "Troubleshooting Ejecutor de CodeQL in your CI system." -
Llena las bases de datos de CodeQL, analízalas, y carga los resultados aGitHub Enterprise Server. Los resultados aparecerán en la pestaña de Seguridad de tu repositorio.
$ /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/my-branch > Finalizing database creation > ... > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms > Successfully uploaded results
-
Para cargar los resultados del escaneo de código como verificaciones de solicitudes de cambios, especifica la solicitud de cambios utilizando el mrcador
. Te recomendamos configurar el Ejecutor de CodeQL para que se ejecute en el evento de webhook--ref
pull_request
.$ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo --github-url https://github.example.com --github-auth TOKEN --commit 1dc7a1346e5ce7b86835b68bbda3078b37d6abbe --ref refs/pull/123/merge > Finalizing database creation > ... > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms > Successfully uploaded results
Para obtener más información acerca de visualizar las alertas del escaneo de código, consulta las secciones "Clasificar las alertas del escaneo de código en las solicitudes de cambios" y "Administrar las alertas del escaneo de código para tu repositorio".
Note: If you use a containerized build, you need to run the Ejecutor de CodeQL in the container where your build task takes place.