Enterprise Server 3.21 está disponível no momento como versão candidata a lançamento.

CLI do CodeQL

Você pode usar o CodeQL CLI para executar processos CodeQL localmente em projetos de software ou para gerar resultados code scanning para envio ao 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 seu código com CodeQL análise. Para obter mais informações sobre CodeQL, confira Verificação de código com CodeQL.

CodeQL CLI é uma ferramenta autônoma de linha de comando que pode ser usada para analisar código. Sua principal finalidade é gerar uma representação de banco de dados de uma base de código, um CodeQL banco de dados. Quando o banco de dados estiver pronto, você poderá consultá-lo interativamente ou executar um conjunto de consultas para gerar um conjunto de resultados no formato SARIF e carregar os resultados em GitHub.

Você pode usar o CodeQL CLI para:

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

O CodeQL CLI pode analisar:

  • Idiomas dinâmicos, por exemplo, JavaScript e Python.
  • Idiomas compilados, por exemplo, C/C++, C#, Go, Java, Kotlin, Rust, and Swift
  • Bases de código em uma mistura de linguagens.

Sobre o uso de CodeQL CLI para code scanning

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

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

Para obter uma visão geral de todas as opções de uso CodeQL da análise para verificação de código, consulte Verificação de código com CodeQL.

Observação

  • A CodeQL CLI está disponível para clientes com uma licença do GitHub Code Security.
  • 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 verificação de código com o CodeQL CLI

Se você optar por executar diretamente CodeQL CLI , primeiro precisará instalar o CodeQL CLI localmente. Se você planeja usar o CodeQL CLI com um sistema de CI externo, precisa disponibilizar o CodeQL CLI para os servidores do seu sistema de CI.

Depois de CodeQL CLI configurado, você pode usar três comandos diferentes para gerar resultados e carregá-los em GitHub:

  1. database create para criar um CodeQL banco de dados para representar a estrutura hierárquica de cada linguagem de programação com suporte no repositório. Para obter mais informações, consulte Como preparar seu código para a análise do CodeQL.
  2. database analyze para executar consultas para analisar cada CodeQL banco de dados e resumir os resultados em um arquivo SARIF. Para obter mais informações, consulte Analyzing your code with CodeQL queries.
  3. github upload-results para enviar os arquivos SARIF resultantes para GitHub, onde os resultados são associados a uma branch ou pull request e exibidos como alertas do code scanning. Para obter mais informações, consulte Carregando resultados da análise do CodeQL para 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. Para saber mais, confira Gerenciando as configurações de segurança e análise do repositório.

Configuração de exemplo de CI para análise de CodeQL

Este é um exemplo da série completa de comandos para o CodeQL CLI qual você pode usar para analisar uma base de código com dois idiomas com suporte e, em seguida, carregar os resultados para 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

Extração de banco de dados

O CodeQL CLI usa programas especiais, chamados extratores, para extrair informações do código-fonte de um sistema de software em um banco de dados que pode ser consultado. Você pode personalizar o comportamento dos extratores definindo as opções de configuração do extrator por meio do CodeQL CLI. Consulte Opções do extrator.

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.

Sobre CodeQL CLI pacotes de banco de dados

O CodeQL CLI comando do pacote de banco de dados pode ser usado para criar um arquivo realocável de um CodeQL banco de dados.

Uma cópia de um pacote de banco de dados pode ser usada para compartilhar informações de solução de problemas com os membros da equipe ou com Suporte do GitHub. Consulte Criar pacotes de banco de dados da CLI do CodeQL.

Como começar

Para obter a maneira mais simples de começar, consulte Como configurar a CLI do CodeQL.

As opções de instalação mais avançadas estarão disponíveis se você precisar delas. Por exemplo, se você:

  • Deseja contribuir para consultas compartilhadas CodeQL de código aberto e prefere trabalhar diretamente com o código-fonte CodeQL. Consulte Verificando o código-fonte da CLI do CodeQL.
  • Precisa instalar várias versões do CodeQL CLI lado a lado. Por exemplo, se uma base de código exigir uma versão específica, enquanto outra usar a mais recente. Você pode baixar cada versão e desempacotar os arquivos de cada versão da CLI no mesmo diretório pai.
  • Está pesquisando ou desenvolvendo consultas e deseja baixar bancos de dados de GitHub.com. Consulte Baixando bancos de dados CodeQL de GitHub.