Sobre a CLI do CodeQL

Você pode usar a CodeQL CLI para executar processos do CodeQL localmente em projetos de software ou para gerar resultados da code scanning para upload no GitHub.

Quem pode usar esse recurso?

O CodeQL está disponível para os seguintes tipos de repositórios:

Neste artigo

Desenvolvedores de software e pesquisadores de segurança podem proteger o código usando a análise do CodeQL. Para obter mais informações sobre o CodeQL, confira Sobre a varredura de código com 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.

Você pode usar a CodeQL CLI para:

  • Executar análises do CodeQL usando consultas fornecidas por engenheiros do GitHub e pela comunidade de código aberto
  • Gerar alertas da verificação de código que você poderá carregar para exibição no GitHub
  • Criar bancos de dados do CodeQL para usar na extensão CodeQL para o Visual Studio Code.
  • Desenvolver e testar consultas personalizadas do CodeQL a serem usadas em suas análises

A CodeQL CLI pode analisar:

  • Linguagens dinâmicas, por exemplo, JavaScript e Python.
  • Linguagens compiladas, por exemplo, C/C++, C#, Go, Java, Kotlin, e Swift
  • Bases de código em uma mistura de linguagens.

Para obter mais informações sobre como configurar a CodeQL CLI, confira Como configurar a CLI do CodeQL.

Sobre o uso do CodeQL CLI for code scanning

Você pode usar a CodeQL CLI para executar a code scanning no código que está processando em um sistema de CI (integração contínua) de terceiros. 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. Para obter uma visão geral do uso do varredura de código com sistemas de CI externos, consulte Usando a varredura de código com seu sistema de CI existente. Para especificações recomendadas (RAM, núcleos de CPU e disco) para executar análises do CodeQL, confira Recursos de hardware recomendados para executar o CodeQL.

Como alternativa, você pode usar pipelines do GitHub Actions ou do Azure DevOps para verificar o código usando a CodeQL CLI. Para obter mais informações, confira Como definir a configuração padrão da verificação de código ou Configurar GitHub Advanced Security for Azure DevOps no Microsoft Learn.

Para obter uma visão geral de todas as opções para usar a análise do CodeQL para a verificação de código, confira Sobre a varredura de código com CodeQL.

Observação

  • O CodeQL CLI é gratuito para uso nos repositórios públicos mantidos no GitHub.com e disponível para uso nos repositórios privados pertencentes aos clientes com uma licença do GitHub Code Security. Para obter informações, confira Termos e condições do GitHub CodeQL e CLI do CodeQL.
  • Atualmente, o CodeQL CLI não é compatível com distribuições Linux não glibc, como o Alpine Linux (baseado em musl).

Sobre a geração de resultados de varredura de código com a CodeQL CLI

Se você optar por executar a CodeQL CLI diretamente, primeiro, precisará instalar a CodeQL CLI localmente. Se estiver planejando usar a CodeQL CLI com um sistema de CI externo, será necessário disponibilizar a CodeQL CLI para os servidores do seu sistema de CI. Para saber mais, confira Como configurar a CLI do CodeQL.

Depois que a CodeQL CLI estiver configurada, você poderá usar três comandos diferentes para gerar os resultados e carregá-los no GitHub:

  1. database create para criar um banco de dados do CodeQL a fim de representar a estrutura hierárquica de cada linguagem de programação compatível no repositório. Para saber mais, confira Como preparar seu código para a análise do CodeQL.
  2. database analyze para executar consultas a fim de analisar cada banco de dados do CodeQL e resumir os resultados em um arquivo SARIF. Para saber mais, confira Como analisar o código com as consultas CodeQL.
  3. github upload-results para carregar os arquivos SARIF resultantes no GitHub, no qual será feita a correspondência dos resultados com um branch ou uma solicitação de pull e no qual eles serão exibidos como alertas da code scanning. Para saber mais, confira Como carregar os resultados da análise do CodeQL no GitHub.

Observação

Há suporte para o upload de dados SARIF a serem exibidos como resultados da code scanning no GitHub nos repositórios pertencentes à organização com o GitHub Code Security habilitado e em repositórios públicos no GitHub.com. Para saber mais, confira Gerenciando as configurações de segurança e análise do repositório.

Exemplo de configuração de CI para análise de CodeQL

Este é um exemplo da série completa de comandos para a CodeQL CLI que você pode usar para analisar uma base de código com duas linguagens compatíveis e, em seguida, carregar os resultados no 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 Advanced Security de forma gratuita, confira Configurando uma avaliação do GitHub Advanced Security.