Installing CodeQL CLI in your CI system

You can install the CodeQL CLI and use it to perform CodeQL escaneo de código in a third-party continuous integration system.

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

About using the CodeQL CLI for escaneo de código

You can use the CodeQL CLI 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. For information, see "About escaneo de código with CodeQL."

El CodeQL CLI es un producto independiente que puedes utilizar para analizar código. Su propósito principal es generar una representación de base de datos de una base de código, una base de datos de CodeQL. Una vez que esté lista la base de datos, puedes consultarla interactivamente o ejecutar una suite de consultas para generar un conjunto de resultados en formato SARIF y cargarlos a GitHub.com.

Alternatively, you can use GitHub Actions to run escaneo de código within GitHub. For information about escaneo de código using actions, see "Setting up escaneo de código for a repository." For an overview of the options for CI systems, see "About CodeQL escaneo de código in your CI system".

Nota: El CodeQL CLI se puede usar gratuitamente en los repositorios públicos que se mantienen en GitHub.com y está disponible para utilizarse en los repositorios privados que pertenezcan a los clientes con una licencia de la Advanced Security. Para obtener información, consulta la sección "Términos y condiciones del CodeQL de GitHub" y CLI de CodeQL".

Downloading the CodeQL CLI

You should download the CodeQL bundle from https://github.com/github/codeql-action/releases. The bundle contains:

  • CodeQL CLI product
  • A compatible version of the queries and libraries from https://github.com/github/codeql
  • Precompiled versions of all the queries included in the bundle

You should always use the CodeQL bundle as this ensures compatibility and also gives much better performance than a separate download of the CodeQL CLI and checkout of the CodeQL queries. If you will only be running the CLI on one specific platform, download the appropriate codeql-bundle-PLATFORM.tar.gz file. Alternatively, you can download codeql-bundle.tar.gz, which contains the CLI for all supported platforms.

Nota: La funcionalidad de administración de paquetes de CodeQL, incluyendo los paquetes de CodeQL, se encuentra actualmente en beta y está sujeta a cambios.

Setting up the CodeQL CLI in your CI system

You need to make the full contents of the CodeQL CLI bundle available to every CI server that you want to run CodeQL escaneo de código analysis on. For example, you might configure each server to copy the bundle from a central, internal location and extract it. Alternatively, you could use the REST API to get the bundle directly from GitHub, ensuring that you benefit from the latest improvements to queries. Updates to the CodeQL CLI are released every 2-3 weeks. For example:

$ wget https://github.com/github/codeql-action/releases/latest/download/codeql-bundle-linux64.tar.gz
$ tar -xvzf ../codeql-bundle-linux64.tar.gz

After you extract the CodeQL CLI bundle, you can run the codeql executable on the server:

  • By executing /<extraction-root>/codeql/codeql, where <extraction-root> is the folder where you extracted the CodeQL CLI bundle.
  • By adding /<extraction-root>/codeql to your PATH, so that you can run the executable as just codeql.

Testing the CodeQL CLI set up

After you extract the CodeQL CLI bundle, you can run the following command to verify that the CLI is correctly set up to create and analyze databases.

  • codeql resolve qlpacks if /<extraction-root>/codeql is on the PATH.
  • /<extraction-root>/codeql/codeql resolve qlpacks otherwise.

Extract from successful output:

codeql-cpp (/<extraction-root>/codeql/qlpacks/codeql-cpp)
codeql-cpp-examples (/<extraction-root>/codeql/qlpacks/codeql-cpp-examples)
codeql-cpp-upgrades (/<extraction-root>/codeql/qlpacks/codeql-cpp-upgrades)
codeql-csharp (/<extraction-root>/codeql/qlpacks/codeql-csharp)
codeql-csharp-examples (/<extraction-root>/codeql/qlpacks/codeql-csharp-examples)
codeql-csharp-upgrades (/<extraction-root>/codeql/qlpacks/codeql-csharp-upgrades)
codeql-go (/<extraction-root>/codeql/qlpacks/codeql-go)
codeql-go-examples (/<extraction-root>/codeql/qlpacks/codeql-go-examples)
codeql-go-upgrades (/<extraction-root>/codeql/qlpacks/codeql-go-upgrades)
codeql-java (/<extraction-root>/codeql/qlpacks/codeql-java)
codeql-java-examples (/<extraction-root>/codeql/qlpacks/codeql-java-examples)
codeql-java-upgrades (/<extraction-root>/codeql/qlpacks/codeql-java-upgrades)
codeql-javascript (/<extraction-root>/codeql/qlpacks/codeql-javascript)
codeql-javascript-examples (/<extraction-root>/codeql/qlpacks/codeql-javascript-examples)
codeql-javascript-upgrades (/<extraction-root>/codeql/qlpacks/codeql-javascript-upgrades)
codeql-python (/<extraction-root>/codeql/qlpacks/codeql-python)
codeql-python-examples (/<extraction-root>/codeql/qlpacks/codeql-python-examples)
codeql-python-upgrades (/<extraction-root>/codeql/qlpacks/codeql-python-upgrades)
...

You should check that the output contains the expected languages and also that the directory location for the qlpack files is correct. The location should be within the extracted CodeQL CLI bundle, shown above as <extraction root>, unless you are using a checkout of github/codeql. If the CodeQL CLI is unable to locate the qlpacks for the expected languages, check that you downloaded the CodeQL bundle and not a standalone copy of the CodeQL CLI.

Generating a token for authentication with GitHub

Each CI server needs a GitHub App or personal access token for the CodeQL CLI to use to upload results to GitHub. You must use an access token or a GitHub App with the security_events write permission. If CI servers already use a token with this scope to checkout repositories from GitHub, you could potentially allow the CodeQL CLI to use the same token. Otherwise, you should create a new token with the security_events write permission and add this to the CI system's secret store. For information, see "Building GitHub Apps" and "Creating a personal access token."

Next steps

You're now ready to configure the CI system to run CodeQL analysis, generate results, and upload them to GitHub where the results will be matched to a branch or pull request and displayed as escaneo de código alerts. For detailed information, see "Configuring CodeQL CLI in your CI system."

¿Te ayudó este documento?

Política de privacidad

¡Ayúdanos a hacer geniales estos documentos!

Todos los documentos de GitHub son de código abierto. ¿Notas algo que esté mal o que no sea claro? Emite una solicitud de cambios.

Haz una contribución

O, aprende cómo contribuir.