CodeQL CLI

You can use the CodeQL CLI to run CodeQL processes locally on software projects or to generate code scanning results for upload to GitHub.

¿Quién puede utilizar esta característica?

CodeQL está disponible para los siguientes tipos de repositorios:

En este artículo

Software developers and security researchers can secure their code using CodeQL analysis. For more information about CodeQL, see Code scanning with CodeQL.

The CodeQL CLI is a standalone, command-line tool that you can use to analyze code. Its main purpose is to generate a database representation of a codebase, a CodeQL database. Once the database is ready, you can query it interactively, or run a suite of queries to generate a set of results in SARIF format and upload the results to GitHub.

You can use the CodeQL CLI to:

  • Run CodeQL analyses using queries provided by GitHub engineers and the open source community
  • Generate code scanning alerts that you can upload to display in GitHub
  • Create CodeQL databases to use in the CodeQL for Visual Studio Code extension.
  • Develop and test custom CodeQL queries to use in your own analyses

The CodeQL CLI can analyze:

  • Dynamic languages, for example, JavaScript and Python.
  • Compiled languages, for example, C/C++, C#, Go, Java, Kotlin, Rust, and Swift
  • Codebases written in a mixture of languages.

About using the CodeQL CLI for code scanning

You can use the CodeQL CLI to run code scanning on code that you're processing in a third-party continuous integration (CI) system. Code scanning es una característica que se usa para analizar el código en un repositorio de GitHub para buscar vulnerabilidades de seguridad y errores de código. Los problemas identificados por el análisis se muestran en el repositorio. For an overview of using code scanning with external CI systems, see Utilizar el análisis de código de CodeQL con tu sistema de IC existente. For recommended specifications (RAM, CPU cores, and disk) for running CodeQL analysis, see Recommended hardware resources for running CodeQL.

Alternatively, you can use GitHub Actions or Azure DevOps pipelines to scan code using the CodeQL CLI. For more information, see Establecimiento de la configuración predeterminada para el examen del código or Configure GitHub Advanced Security for Azure DevOps in Microsoft Learn.

For an overview of all the options for using CodeQL analysis for code scanning, see Code scanning with CodeQL.

Nota:

  • La CodeQL CLI puede usarse libremente en repositorios públicos. CodeQL CLI también está disponible en los repositorios privados que pertenecen a las organizaciones que usan GitHub Team o GitHub Enterprise Cloud y que tienen una licencia de GitHub Code Security. Para obtener información, consulta Términos y condiciones de GitHub CodeQL y CLI de CodeQL.
  • La CodeQL CLI no es compatible actualmente con distribuciones de Linux que no sean glibc, como Alpine Linux (basado en musl).

About generating code scanning results with the CodeQL CLI

If you choose to run the CodeQL CLI directly, you first have to install the CodeQL CLI locally. If you are planning to use the CodeQL CLI with an external CI system, you need to make the CodeQL CLI available to servers in your CI system.

Once the CodeQL CLI is set up, you can use three different commands to generate results and upload them to GitHub:

  1. database create to create a CodeQL database to represent the hierarchical structure of each supported programming language in the repository. For more information, see Preparación del código para el análisis de CodeQL.
  2. database analyze to run queries to analyze each CodeQL database and summarize the results in a SARIF file. For more information, see Análisis del código con consultas de CodeQL.
  3. github upload-results to upload the resulting SARIF files to GitHub where the results are matched to a branch or pull request and displayed as code scanning alerts. For more information, see Carga de resultados de análisis de CodeQL en GitHub.

Nota:

Cargar datos de SARIF para mostrarlos como resultados de code scanning en GitHub se admite en los repositorios propiedad de una organización que tengan GitHub Code Security habilitado y en los repositorios públicos de GitHub.com. Para más información, consulta Administración de la configuración de seguridad y análisis para el repositorio.

Example CI configuration for CodeQL analysis

This is an example of the full series of commands for the CodeQL CLI that you might use to analyze a codebase with two supported languages and then upload the results to GitHub.

# Create CodeQL databases for Java and Python in the 'codeql-dbs' directory
# Call the normal build script for the codebase: 'myBuildScript'

codeql database create codeql-dbs --source-root=src \
    --db-cluster --language=java,python --command=./myBuildScript

# Analyze the CodeQL database for Java, 'codeql-dbs/java'
# Tag the data as 'java' results and store in: 'java-results.sarif'

codeql database analyze codeql-dbs/java java-code-scanning.qls \
    --format=sarif-latest --sarif-category=java --output=java-results.sarif

# Analyze the CodeQL database for Python, 'codeql-dbs/python'
# Tag the data as 'python' results and store in: 'python-results.sarif'

codeql database analyze codeql-dbs/python python-code-scanning.qls \
    --format=sarif-latest --sarif-category=python --output=python-results.sarif

# Upload the SARIF file with the Java results: 'java-results.sarif'
# The GitHub App or personal access token created for authentication
# with GitHub's REST API is available in the `GITHUB_TOKEN` environment variable.

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=java-results.sarif

# Upload the SARIF file with the Python results: 'python-results.sarif'

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=python-results.sarif

Database extraction

The CodeQL CLI uses special programs, called extractors, to extract information from the source code of a software system into a database that can be queried. You can customize the behavior of extractors by setting extractor configuration options through the CodeQL CLI. See Opciones de extractor.

Acerca de la licencia de GitHub CodeQL

Aviso sobre la licencia: Si no tienes una licencia de GitHub Code Security, al instalar este producto aceptas los términos y condiciones de GitHub CodeQL.

Para obtener información sobre cómo puedes probar GitHub Enterprise con GitHub Advanced Security de forma gratuita, consulta Configuración de una versión de prueba de GitHub Enterprise Cloud y Configuración de una evaluación de GitHub Advanced Security en la documentación de GitHub Enterprise Cloud.

About CodeQL CLI database bundles

The CodeQL CLI database bundle command can be used to create a relocatable archive of a CodeQL database.

A copy of a database bundle can be used to share troubleshooting information with your team members or with Soporte de GitHub. See Creación de agrupaciones de bases de datos de la CLI de CodeQL.

Getting started

For the simplest way to get started, see Configuración de la CLI de CodeQL.

More advanced setup options are available if you need them. For example, if you:

  • Want to contribute to open source shared CodeQL queries and prefer working with the CodeQL source code directly. See Comprobación del código fuente de la CLI de CodeQL.
  • Need to install multiple versions of the CodeQL CLI side by side. For example, if one codebase requires a specific version while another uses the latest. You can download each version and unpack both CLI archives in the same parent directory.
  • Are researching or developing queries and want to download databases from GitHub.com. See Descarga de bases de datos codeQL desde GitHub.