About the CodeQL CLI

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

A CodeQL CLI é uma ferramenta de linha de comando autônoma que você pode usar para analisar o código. Seu principal propósito é gerar uma representação do banco de dados de uma base de código, um banco de dados de CodeQL. Assim que o banco de dados estiver pronto, será possível consultá-lo interativamente ou executar um conjunto de consultas a fim de gerar um conjunto de resultados no formato SARIF e enviá-los ao 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, e Swift
• Codebases written in a mixture of languages.

For information about setting up the CodeQL CLI, see Como configurar a CLI do CodeQL.

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. A Code scanning é um recurso que você usa para analisar o código em um repositório GitHub para encontrar vulnerabilidades de segurança e erros de codificação. Os problemas que forem identificados pela análise serão mostrados em seu repositório. For an overview of using code scanning with external CI systems, see Usando a varredura de código com seu sistema de CI existente. For recommended specifications (RAM, CPU cores, and disk) for running CodeQL analysis, see Recursos de hardware recomendados para executar o CodeQL.

Alternatively, you can use GitHub Actions or Azure DevOps pipelines to scan code using the CodeQL CLI. For more information, see Como definir a configuração padrão da verificação de 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 About code scanning with CodeQL.

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 Como configurar a CLI do CodeQL.

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 Como preparar seu código para a análise do CodeQL.
2. database analyze to run queries to analyze each CodeQL database and summarize the results in a SARIF file. For more information, see Como analisar o código com as consultas 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 Como carregar os resultados da análise do CodeQL no GitHub.

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

Sobre a licença do GitHub CodeQL

Aviso de licença: se você não tiver uma licença da GitHub Code Security então, ao instalar este produto, estará concordando com os GitHub CodeQL Termos e Condições.

Para obter informações sobre como é possível testar o GitHub Enterprise com o GitHub Advanced Security de forma gratuita, confira Configurar uma versão de avaliação do GitHub Enterprise Cloud e Como configurar uma avaliação gratuita do GitHub Advanced Security na documentação do GitHub Enterprise Cloud.