Skip to main content
Frecuentemente publicamos actualizaciones de nuestra documentación. Es posible que la traducción de esta página esté en curso. Para conocer la información más actual, visita la documentación en inglés. Si existe un problema con las traducciones en esta página, por favor infórmanos.

Esta versión de GitHub Enterprise se discontinuó el 2022-06-03. No se realizarán lanzamientos de patch, ni siquiera para problemas de seguridad críticos. Para obtener un mejor desempeño, más seguridad y nuevas características, actualiza a la última versión de GitHub Enterprise. Para obtener ayuda con la actualización, contacta al soporte de GitHub Enterprise.

Configuring CodeQL runner in your CI system

You can configure how the Ejecutor de CodeQL scans the code in your project and uploads the results to GitHub.

El Escaneo de código se encuentra disponible para los repositorios que pertenecen a organizaciones donde se habilitó el GitHub Advanced Security. Para obtener más información, consulta la sección "Acerca de GitHub Advanced Security".

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 configuring CodeQL escaneo de código in your CI system

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

In general, you invoke the Ejecutor de CodeQL as follows.

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

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

To customize the way the Ejecutor de 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 Ejecutor de CodeQL automatically detects and scans code written in the supported languages.

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

Si tu repositorio contiene código en más de uno de los lenguajes compatibles, puedes elegir qué lenguajes quieres analizar. Hay varias razones que por las cuales querrías prevenir que un lenguaje se analice. Por ejemplo, el proyecto puede tener dependencias en un lenguaje distinto al del cuerpo principal de tu código, y tal vez prefieras no ver las alertas para esas dependencias.

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, y python.

$ /path/to-runner/codeql-runner-linux init --languages cpp,java

Running additional queries

When you use CodeQL to scan code, the CodeQL analysis engine generates a database from the code and runs queries on it. CodeQL analysis uses a default set of queries, but you can specify more queries to run, in addition to the default queries.

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

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

Las siguientes suites de consultas se compilan en el CodeQL del escaneo de código y están disponibles para utilizarse.

Conjunto de consultasDescripción
security-extendedLas consultas de severidad y precisión más baja que aquellas predeterminadas
security-and-qualityLas consultas de security-extended, mas aquellas de mantenibilidad y confiabilidad

Cuando especificas una suite de consultas, el motor de análisis de CodeQL ejecutará el conjunto predeterminado de consultas y cualquier consulta adicional que se defina en la suite de consultas adicionales.

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 Ejecutor de 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 Ejecutor de 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 Ejecutor de 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

El archivo de configuración puede ubicarse dentro del repositorio que estás analizando o en un repositorio externo. El utilizar un repositorio externo te permite especificar las opciones de configuración para repositorios múltiples en un solo lugar. Cuando referencias un archivo de configuración que se ubica en un repositorio externo, puedes utilizar la sintaxis OWNER/REPOSITORY/FILENAME@BRANCH. Por ejemplo, octo-org/shared/codeql-config.yml@main.

Example configuration files

Este archivo de configuración agrega el conjunto de consultas security-and-quality a la lista de consultas que se ejecutan con CodeQL cuando se escanea tu código. Para obtener más información acerca de los conjuntos de consultas que están disponibles para utilizarse, consulta la sección "Ejecutar consultas adicionales".

name: "My CodeQL config"

queries:
  - uses: security-and-quality

El siguiente archivo de configuración inhabilita las consultas predeterminadas y especifica un conjunto de consultas personalizadas para ejecutarse en vez de éstas. También configura a CodeQL para escanear archivos en el directorio src (relativo a la raíz), con excepción del directorio src/node_modules y de los archivos cuyo nombre termine en .test.js. Los archivos en src/node_modules y aquellos cuyos nombres terminan en .test.js se excluyen por lo tanto del análisis.

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

For the compiled languages C/C++, C#, and Java, CodeQL builds the code before analyzing it. CodeQL también ejecuta una compilación para que los proyectos de Go configuren el proyecto. Sin embargo, en contraste con el resto de los lenguajes compilados, todos los archivos de Go en el repositorio se extraen, y no únicamente aquellos que se compilaron. Puedes utilizar comandos personalizados de compilación para saltarte la extracción de archivos de Go que no haya tocado la compilación.

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

Uploading escaneo de código data to GitHub

By default, the Ejecutor de CodeQL uploads results from escaneo 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.

Ejecutor de CodeQL command reference

The Ejecutor de CodeQL supports the following commands and flags.

init

Initializes the Ejecutor de CodeQL and creates a CodeQL database for each language to be analyzed.

FlagRequiredInput value
--repositoryName of the repository to initialize.
--github-urlURL of the GitHub instance where your repository is hosted.
--github-auth-stdinRead the GitHub Apps token or personal access token from standard input.
--languagesComma-separated list of languages to analyze. By default, the Ejecutor de CodeQL detects and analyzes all supported languages in the repository.
--queriesComma-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-filePath to custom configuration file.
--codeql-pathPath to a copy of the CodeQL CLI executable to use. By default, the Ejecutor de CodeQL downloads a copy.
--temp-dirDirectory where temporary files are stored. The default is ./codeql-runner.
--tools-dirDirectory where CodeQL tools and other files are stored between runs. The default is a subdirectory of the home directory.
--checkout-pathThe path to the checkout of your repository. The default is the current working directory.
--debugNone. Prints more verbose output.
--trace-process-nameAdvanced, Windows only. Name of the process where a Windows tracer of this process is injected.
--trace-process-levelAdvanced, Windows only. Number of levels up of the parent process where a Windows tracer of this process is injected.
-h, --helpNone. 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.

FlagRequiredInput value
--languageThe language to build. By default, the Ejecutor de CodeQL builds the compiled language with the most files.
--temp-dirDirectory where temporary files are stored. The default is ./codeql-runner.
--debugNone. Prints more verbose output.
-h, --helpNone. Displays help for the command.

analyze

Analyzes the code in the CodeQL databases and uploads results to GitHub Enterprise Server.

FlagRequiredInput value
--repositoryName of the repository to analyze.
--commitSHA 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.
--refName 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-urlURL of the GitHub instance where your repository is hosted.
--github-auth-stdinRead the GitHub Apps token or personal access token from standard input.
--checkout-pathThe path to the checkout of your repository. The default is the current working directory.
--no-uploadNone. Stops the Ejecutor de CodeQL from uploading the results to GitHub Enterprise Server.
--output-dirDirectory where the output SARIF files are stored. The default is in the directory of temporary files.
--ramAmount of memory to use when running queries. The default is to use all available memory.
--no-add-snippetsNone. Excludes code snippets from the SARIF output.
--threadsNumber of threads to use when running queries. The default is to use all available cores.
--temp-dirDirectory where temporary files are stored. The default is ./codeql-runner.
--debugNone. Prints more verbose output.
-h, --helpNone. 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.

FlagRequiredInput value
--sarif-fileSARIF file to upload, or a directory containing multiple SARIF files.
--repositoryName of the repository that was analyzed.
--commitSHA 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.
--refName 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-urlURL of the GitHub instance where your repository is hosted.
--github-auth-stdinRead the GitHub Apps token or personal access token from standard input.
--checkout-pathThe path to the checkout of your repository. The default is the current working directory.
--debugNone. Prints more verbose output.
-h, --helpNone. Displays help for the command.