About the 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 peut utiliser cette fonctionnalité ?

CodeQL est disponible pour les types de référentiels suivants :

Dans cet article

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

L’CodeQL CLI est un outil en ligne de commande autonome que vous pouvez utiliser pour analyser le code. Son objectif principal est de générer une représentation de base de données d’un codebase, une base de données CodeQL. Une fois que la base de données est prête, vous pouvez l’interroger de manière interactive, ou exécuter une suite de requêtes pour générer un ensemble de résultats au format SARIF et charger les résultats dans 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, et Swift
  • Codebases written in a mixture of languages.

For information about setting up the CodeQL CLI, see Configuration de CodeQL CLI.

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 une fonctionnalité que vous utilisez pour analyser le code dans un dépôt GitHub afin de détecter d’éventuelles vulnérabilités de sécurité et erreurs de codage. Tous les problèmes identifiés par l’analyse sont énumérés dans votre référentiel. For an overview of using code scanning with external CI systems, see Utilisation de l'analyse du code avec votre système CI existant. For recommended specifications (RAM, CPU cores, and disk) for running CodeQL analysis, see Ressources matérielles recommandées pour l’exécution de CodeQL.

Alternatively, you can use GitHub Actions or Azure DevOps pipelines to scan code using the CodeQL CLI. For more information, see Définition de la configuration par défaut pour l’analyse du code 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 About code scanning with CodeQL.

Remarque

  • L’utilisation de CodeQL CLI est gratuite sur les dépôts publics. Le CodeQL CLI est également disponible dans les référentiels privés appartenant aux organisations qui utilisent GitHub Team ou GitHub Enterprise Cloud et qui disposent d’une licence pour GitHub Code Security. Pour plus d’informations, consultez Conditions générales de GitHub CodeQL et Interface de ligne de commande de CodeQL.
  • CodeQL CLI n’est actuellement pas compatible avec les distributions Linux non-glibc comme Alpine Linux (basée sur 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. For more information, see Configuration de CodeQL CLI.

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 Préparation de votre code pour l’analyse CodeQL.
  2. database analyze to run queries to analyze each CodeQL database and summarize the results in a SARIF file. For more information, see Analyse de votre code avec des requêtes 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 Chargement des résultats d'analyse de CodeQL sur GitHub.

Remarque

Le chargement des données SARIF à afficher comme résultats code scanning dans GitHub est pris en charge pour les référentiels appartenant à l’organisation avec GitHub Code Security activé, et les référentiels publics sur GitHub.com. Pour plus d’informations, consultez « Gestion des paramètres de sécurité et d’analyse pour votre dépôt ».

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

À propos de la licence GitHub CodeQL

Avis de licence : si vous ne disposez pas d’une licence pour GitHub Code Security, alors, en installant ce produit, vous acceptez les Conditions générales de GitHub CodeQL.

Pour plus d’informations sur la façon dont vous pouvez essayer GitHub Enterprise gratuitement avec GitHub Advanced Security, consultez Configuration d’un essai de GitHub Enterprise Cloud et Configuration d’un essai de GitHub Advanced Security dans la documentation GitHub Enterprise Cloud.