Skip to main content

Solução de problemas de sua configuração avançada para CodeQL

In this article

Se estiver tendo problemas com a configuração avançada da para code scanning, você poderá solucioná-los usando as dicas a seguir.

Code scanning está disponível para todos os repositórios públicos no GitHub.com. Code scanning também está disponível em repositórios privados pertencentes às organizações que usam o GitHub Enterprise Cloud e têm uma licença do GitHub Advanced Security. Para obter mais informações, confira "Sobre o GitHub Advanced Security".

Observação: para repositórios privados e internos, a code scanning fica disponível quando os recursos do GitHub Advanced Security são habilitados no repositório. Se você receber o erro Advanced Security must be enabled for this repository to use code scanning, verifique se o GitHub Advanced Security está habilitado. Para obter mais informações, confira "Como gerenciar as configurações de segurança e de análise do seu repositório".

Produzir registros detalhados para depuração

Para produzir a saída de log mais detalhada, você pode habilitar o log de depuração da etapa. Para obter mais informações, confira "Como habilitar o log de depuração".

Criando artefatos de depuração de CodeQL

Você pode obter artefatos para ajudar você a depurar CodeQL. Os artefatos de depuração são carregados no fluxo de trabalho executado como um artefato chamado debug-artifacts. Os dados contém os registros de CodeQL, banco(s) de dados de CodeQL, e todo(s) o(s) outro(s) arquivo(s) SARIF produzido(s) pelo fluxo de trabalho.

Estes artefatos ajudarão você a depurar problemas com digitalização de código de CodeQL code scanning. Se você entrar em contato com o suporte do GitHub, eles poderão pedir estes dados.

Como criar artefatos de depuração do CodeQL executando novamente trabalhos com log de depuração habilitado

Você pode criar artefatos de depuração do CodeQL habilitando o registro em log de depuração e executando novamente os trabalhos. Para obter mais informações sobre como executar novamente os fluxos de trabalho e os trabalhos do GitHub Actions, confira "Executar novamente fluxos de trabalho e trabalhos".

Selecione Habilitar registro em log de depuração. Essa opção habilita o log de diagnóstico do executor e o log de depuração de etapas para a execução. Em seguida, você poderá baixar debug-artifacts para investigar mais. Você não precisa modificar o arquivo de fluxo de trabalho ao criar artefatos de depuração do CodeQL executando novamente trabalhos.

Como criar artefatos de depuração de CodeQL usando um sinalizador de fluxo de trabalho

Você pode criar artefatos de depuração de CodeQL usando um sinalizador no seu fluxo de trabalho. Para isso, você precisa modificar a etapa init do arquivo do CodeQL analysis workflow e definir debug: true.

- name: Initialize CodeQL
  uses: github/codeql-action/init@v2
  with:
    debug: true

Os resultados são diferentes do esperado

Se os resultados da code scanning forem diferentes do esperado, o repositório poderá ter configurações padrão e avançadas do code scanning. Quando você habilita a configuração padrão, isso impede que arquivos de fluxo de trabalho do CodeQL no repositório carreguem resultados.

Para verificar se a configuração padrão está habilitada, navegue até a página principal do repositório e clique em Configurações. Na seção "Segurança" da barra lateral, clique em Análise e segurança de código. Na seção "Code scanning" da página, ao lado de "Análise de CodeQL," clique em . Se existe uma opção Alternar para avançada, você está usando a configuração padrão no momento. Para alternar para a configuração avançada e obter os resultados da code scanning do arquivo de fluxo de trabalho personalizado, clique em Desabilitar o CodeQL . Essa opção desabilitará apenas a configuração padrão, e o fluxo de trabalho pré-existente começará a carregar os resultados novamente. Para obter mais informações, confira "Como configurar code scanning para um repositório".

Ocorreu uma falha durante a criação automática para uma linguagem compilada

Se ocorrer uma falha na uma criação automática de código para uma linguagem compilada dentro de seu projeto, tente as seguintes etapas para a solução de problemas.

  • Remova a etapa autobuild do fluxo de trabalho da code scanning e adicione etapas de build específicas. Para obter informações sobre como editar o fluxo de trabalho, confira "Como configurar a code scanning". Para obter mais informações sobre como substituir a etapa autobuild, confira "Como configurar o fluxo de trabalho do CodeQL para as linguagens compiladas".

  • Se seu fluxo de trabalho não especificar explicitamente linguagens para analisar, CodeQL irá detectar implicitamente as linguagens compiladas na sua base de código. Nesta configuração, das linguagens compiladas C/C++, C#, Go e Java, o CodeQL analisa apenas a linguagem com mais arquivos de origem. Edite o fluxo de trabalho e adicione uma matriz especificando as linguagens que você deseja analisar. O fluxo de trabalho de análise padrão do CodeQL usa uma matriz desse tipo.

    Os seguintes extratos de um fluxo de trabalho mostram como usar uma matriz dentro da estratégia de trabalho para especificar linguagens e, em seguida, fazer referência a cada linguagem dentro da etapa "Inicializar CodeQL:

    jobs:
      analyze:
        permissions:
          security-events: write
          actions: read
        ...
        strategy:
          fail-fast: false
          matrix:
            language: ['csharp', 'cpp', 'javascript']
    
        steps:
        ...
          - name: Initialize CodeQL
            uses: github/codeql-action/init@v2
            with:
              languages: ${{ matrix.language }}
    

    Para obter mais informações sobre como editar o fluxo de trabalho, confira "Como personalizar dados do code scanning".

Nenhum código encontrado durante a criação

Se o fluxo de trabalho falhar com o erro No source code was seen during the build ou The process '/opt/hostedtoolcache/CodeQL/0.0.0-20200630/x64/codeql/codeql' failed with exit code 32, isso indicará que o CodeQL não pôde monitorar o código. Há várias explicações para essa falha:

  1. O repositório pode não conter código-fonte escrito em idiomas compatíveis com CodeQL. Verifique a lista de idiomas com suporte e, se esse for o caso, remova o fluxo de trabalho CodeQL. Para obter mais informações, confira "Sobre a code scanning com CodeQL".

  2. A detecção automática da linguagem identificou uma linguagem compatível, mas não há código analisável dessa linguagem no repositório. Um exemplo típico é quando o serviço de detecção de linguagem encontra um arquivo associado a determinada linguagem de programação, como um arquivo .h ou .gyp, mas nenhum código executável correspondente está presente no repositório. Para resolver o problema, defina manualmente as linguagens que deseja analisar atualizando a lista de linguagens na matriz language. Por exemplo, a configuração a seguir analisará somente Go, e JavaScript.

    strategy:
      fail-fast: false
      matrix:
        # Override automatic language detection by changing the list below.
        # Supported options are listed in a comment in the default workflow.
        language: ['go', 'javascript']
    

    Para obter mais informações, confira a extração de fluxo de trabalho em "Falha no build automático para uma linguagem compilada" acima.

  3. O fluxo de trabalho de code scanning está analisando uma linguagem compilada (C, C++, C#, Go ou Java), mas o código não foi compilado. Por padrão, o fluxo de trabalho da análise do CodeQL contém uma etapa autobuild. No entanto, essa etapa representa um processo de melhor esforço e talvez não funcione na compilação do código, dependendo do ambiente de build específico. A compilação também pode falhar se você removeu a etapa autobuild e não incluiu as etapas de build manualmente. Para obter mais informações sobre como especificar etapas de build, confira "Como configurar o fluxo de trabalho do CodeQL para as linguagens compiladas".

  4. O fluxo de trabalho está analisando uma linguagem compilada (C, C++, C#, Go ou Java), mas partes do build são armazenadas em cache para aprimorar o desempenho (é mais provável que ocorra com sistemas de build como Gradle ou Bazel). Uma vez que o CodeQL observa a atividade do compilador para entender os fluxos de dados em um repositório, CodeQL exige uma compilação completa para realizar a análise.

  5. Seu fluxo de trabalho está analisando uma linguagem compilada (C, C++, C#, Go ou Java), mas a compilação não ocorre entre as etapas init e analyze no fluxo de trabalho. O CodeQL exige que a sua compilação aconteça entre essas duas etapas para observar a atividade do compilador e realizar a análise.

  6. O código compilado (em C, C++, C#, Go ou Java) foi compilado com sucesso, mas o CodeQL não conseguiu detectar as invocações do compilador. As causas mais comuns são:

    • Executar seu processo de criação em um contêiner separado para CodeQL. Para obter mais informações, confira "Como executar a code scanning do CodeQL em um contêiner".
    • Criar usando um sistema de compilação distribuído externo às Ações GitHub, usando um processo de daemon.
    • CodeQL não está ciente do compilador específico que você está usando.

    Para projetos .NET Framework e em C# que usam dotnet build ou msbuild, você deve especificar /p:UseSharedCompilation=false na etapa run do fluxo de trabalho ao compilar seu código.

    Por exemplo, a seguinte configuração para C# irá passar o sinalizador durante a primeira etapa de criação.

    - run: |
        dotnet build /p:UseSharedCompilation=false
    

    Se você encontrar outro problema com seu compilador específico ou configuração, entre em contato com Suporte do GitHub.

Para obter mais informações sobre como especificar etapas de build, confira "Como configurar o fluxo de trabalho do CodeQL para as linguagens compiladas".

As inhas de código digitalizadas são menores do que o esperado

Para linguagens compiladas como, por exemplo, C/C++, C#, Go e Java, CodeQL só faz a digitalização de arquivos criados durante a análise. Portanto, o número de linhas de código digitalizadas será menor do que o esperado se parte do código-fonte não for compilado corretamente. Isso pode ocorrer por diversos motivos:

  1. O recurso autobuild do CodeQL usa a heurística para compilar o código em um repositório. No entanto, às vezes essa abordagem resulta em uma análise incompleta de um repositório. Por exemplo, quando vários comandos build.sh existem em um só repositório, talvez a análise não seja completa, pois a etapa autobuild executará apenas um dos comandos. Portanto, alguns arquivos de origem podem não ser compilados.
  2. Alguns compiladores não funcionam com CodeQL e podem causar problemas ao analisar o código. Por exemplo, o projeto Lombok usa APIs do compilador não público para modificar o comportamento do compilador. As suposições usadas nessas modificações do compilador não são válidas para o extrator Java do CodeQL. Portanto, o código não pode ser analisado.

Se a sua análise de CodeQL digitalizar menos linhas de código do que o esperado, existem várias abordagens que você pode testar para garantir que todos os arquivos fonte necessários sejam compilados.

Substituir a etapa autobuild

Substitua a etapa autobuild pelos os mesmos comandos de build que serão usados em produção. Isso garante que CodeQL sabe exatamente como compilar todos os arquivos de origem que você deseja digitalizar. Para obter mais informações, confira "Como configurar o fluxo de trabalho do CodeQL para as linguagens compiladas".

Inspecionar a cópia dos arquivos de origem no banco de dados de CodeQL

Talvez você seja possa entender por que alguns arquivos de origem não foram analisados inspecionando a cópia do código-fonte incluído na base de dados de CodeQL. Para obter o banco de dados por meio do fluxo de trabalho do Actions, modifique a etapa init do arquivo de fluxo de trabalho do CodeQL e defina debug: true.

- name: Initialize CodeQL
  uses: github/codeql-action/init@v2
  with:
    debug: true

Isso faz o upload do banco de dados como um artefato de ações que você pode baixar para a sua máquina local. Para obter mais informações, confira "Como armazenar artefatos de fluxo de trabalho".

O artefato conterá uma cópia arquivada dos arquivos de origem verificados pelo CodeQL chamada src.zip. Se você comparar os arquivos do código-fonte no repositório e os arquivos no src.zip, poderá ver quais tipos de arquivos estão ausentes. Uma vez que você sabe quais tipos de arquivo não estão sendo analisados, é mais fácil entender como você pode precisar alterar o fluxo de trabalho para a análise de CodeQL.

Alertas encontrados no código gerado

Para linguagens compiladas como Java, Kotlin, Go, C, C++ e C#, o CodeQL analisa todo o código criado durante a execução do fluxo de trabalho. Para limitar a quantidade de código analisada, compile apenas o código que deseja analisar especificando etapas de build próprias em um bloco run. Combine a especificação de etapas de build próprias com o uso dos filtros paths e paths-ignore nos eventos pull_request e push para garantir que o fluxo de trabalho seja executado somente quando o código específico for alterado. Para obter mais informações, confira "Sintaxe de fluxo de trabalho do GitHub Actions".

Para linguagens como JavaScript, Python e TypeScript, que o CodeQL analisa sem compilar o código-fonte, você pode especificar opções de configuração adicionais para limitar a quantidade de código a ser analisado. Para obter mais informações, confira "Como personalizar a code scanning".

Erros de extração no banco de dados

A equipe de CodeQL trabalha constantemente em erros críticos de extração para garantir que todos os arquivos de origem possam ser digitalizados. No entanto, os extratores de CodeQL às vezes geram erros durante a criação do banco de dados. CodeQL fornece informações sobre erros de extração e avisos gerados durante a criação do banco de dados em um arquivo de registro. A informação sobre o diagnóstico de extração fornece uma indicação da saúde geral do banco de dados. A maioria dos erros dos extratores não impactam a análise significativamente. Um pequeno número de erros de extrator é saudável e normalmente indica um bom estado de análise.

No entanto, se você vir erros de extrator na grande maioria dos arquivos que foram compilados durante a criação do banco de dados, você deverá analisar os erros mais detalhadamente para tentar entender por que alguns arquivos de origem não foram extraídos corretamente.

A criação demora muito tempo

Se a sua criação com a análise de CodeQL demorar muito para ser executada, existem várias abordagens que você pode tentar para reduzir o tempo de criação.

Usar criações da matriz para paralelizar a análise

Se você usar executores auto-hospedados para executar a análise do CodeQL, você poderá aumentar a memória ou o número de núcleos nesses executores.

Usar criações da matriz para paralelizar a análise

O CodeQL analysis workflow padrão usa uma matriz de linguagens, o que faz com que a análise de cada linguagem seja executada em paralelo. Se você especificou as linguagens que deseja analisar diretamente na etapa "Inicializar CodeQL", a análise de cada linguagem acontecerá sequencialmente. Para acelerar a análise de várias linguagens, modifique o seu fluxo de trabalho para usar uma matriz. Para obter mais informações, confira a extração de fluxo de trabalho em "Falha no build automático para uma linguagem compilada" acima.

Reduz a quantidade de código em análise em um único fluxo de trabalho

O tempo de análise é normalmente proporcional à quantidade de código que está sendo analisado. Você pode reduzir o tempo de análise reduzindo a quantidade de código em análise de uma vez, por exemplo, excluindo o código de teste, ou dividindo a análise em vários fluxos de trabalho que analisam apenas um subconjunto do seu código por vez.

Para linguagens compiladas como Java, Kotlin, Go, C, C++ e C#, o CodeQL analisa todo o código criado durante a execução do fluxo de trabalho. Para limitar a quantidade de código analisada, compile apenas o código que deseja analisar especificando etapas de build próprias em um bloco run. Combine a especificação de etapas de build próprias com o uso dos filtros paths e paths-ignore nos eventos pull_request e push para garantir que o fluxo de trabalho seja executado somente quando o código específico for alterado. Para obter mais informações, confira "Sintaxe de fluxo de trabalho do GitHub Actions".

Para linguagens como JavaScript, Python e TypeScript, que o CodeQL analisa sem compilar o código-fonte, você pode especificar opções de configuração adicionais para limitar a quantidade de código a ser analisado. Para obter mais informações, confira "Como personalizar a code scanning".

Se você dividir sua análise em vários fluxos de trabalho, conforme descrito acima, ainda assim recomendaremos que você tenha, pelo menos, um fluxo de trabalho que seja executado em um schedule que analise todo o código no repositório. Já que o CodeQL analisa os fluxos de dados entre os componentes, alguns comportamentos de segurança complexos só podem ser detectados em uma criação completa.

Execução somente durante um evento schedule

Se a execução da análise estiver muito lenta durante os eventos push ou pull_request, o ideal será disparar a análise somente no evento schedule. Para obter mais informações, confira "Eventos".

Verifique qual conjunto de consultas que o fluxo de trabalho executa

Por padrão, existem três principais conjuntos de consultas disponíveis para cada linguagem. Se você otimizar o build do banco de dados do CodeQL mas mesmo assim o processo continuar sendo muito longo, você poderá reduzir o número de consultas executadas. O conjunto de consulta padrão é executado automaticamente. Ele contém as consultas de segurança mais rápidas com as taxas mais baixas de resultados falso-positivos.

Você pode executar consultas adicionais ou conjuntos de consulta além das consultas padrão. Verifique se o fluxo de trabalho define um conjunto de consultas adicional ou consultas adicionais a serem executadas usando o elemento queries. Você pode experimentar desabilitar o conjunto de consultas adicionais ou consultas. Para obter mais informações, confira "Como personalizar code scanning".

Observação: se você executar o conjunto de consultas security-extended ou security-and-quality para JavaScript, algumas consultas usarão uma tecnologia experimental. Para obter mais informações, confira "Sobre os alertas da code scanning".

Os resultados diferem entre as plataformas de análise

Se você está analisando um código escrito no Python, talvez veja resultados diferentes, dependendo se você executa o CodeQL analysis workflow no Linux, no macOS ou no Windows.

Nos executores hospedados no GitHub que usam o Linux, o CodeQL analysis workflow tenta instalar e analisar as dependências do Python, o que pode gerar mais resultados. Para desabilitar a instalação automática, adicione setup-python-dependencies: false à etapa "Inicializar CodeQL" do fluxo de trabalho. Para obter mais informações sobre como configurar a análise de dependências do Python, confira "Como personalizar code scanning".

Erro: "Erro de servidor"

Se a execução de um fluxo de trabalho para code scanning falhar devido a um erro no servidor, tente executar o fluxo de trabalho novamente. Se o problema persistir, entre em contato com Suporte do GitHub.

Erro: "Sem espaço em disco" ou "Memória insuficiente"

Em projetos muito grandes, CodeQL pode ficar ficar sem disco ou sem memória no executor. Se você encontrar esse problema em um executor hospedado pelo GitHub Actions, entre em contato com o Suporte do GitHub para que possamos investigar o problema.

Erro: 403 "Resource not accessible by integration" ao usar Dependabot

Dependabot é considerado não confiável quando aciona uma execução de fluxo de trabalho, e o fluxo de trabalho será executado com escopos somente leitura. Em geral, o upload dos resultados da code scanning em um branch exige o escopo security_events: write. No entanto, a code scanning sempre permite o upload dos resultados quando o evento pull_request dispara a execução da ação. É por isso que, para os branches do Dependabot, recomendamos que você use o evento pull_request em vez do evento push.

Uma abordagem simples é executar pushes no branch padrão e todos os outros branches importantes de execução longa, além de pull requests abertos contra este conjunto de branches:

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

Uma abordagem alternativa é executar em todos os pushes, exceto em branches de Dependabot:

on:
  push:
    branches-ignore:
      - 'dependabot/**'
  pull_request:

A análise ainda falha na ramificação padrão

Se o CodeQL analysis workflow ainda falhar em um commit criado no branch padrão, você precisará verificar:

  • se Dependabot criou o commit
  • se a solicitação de pull que inclui o commit foi mesclada por meio de @dependabot squash and merge

Este tipo de commit de merge foi criado por Dependabot e, portanto, qualquer fluxo de trabalho que esteja em execução no commit terá permissões de somente leitura. Se você habilitou as atualizações de segurança ou as atualizações de versão da code scanning e do Dependabot no seu repositório, recomendamos que você evite usar o comando @dependabot squash and merge do Dependabot. Em vez disso, você pode habilitar a mesclagem automática para seu repositório. Isso significa que as solicitações de pull serão mescladas automaticamente quando todas as revisões necessárias forem atendidas e as verificações de status tiverem passado. Para obter mais informações sobre como habilitar a mesclagem automática, confira "Mesclar automaticamente uma solicitação de pull".

Erro: "não é um arquivo .ql, um arquivo .qls, um diretório ou uma especificação do pacote de consultas"

Você verá esse erro se o CodeQL não conseguir localizar a consulta nomeada, o pacote de consultas ou o pacote de consultas no local solicitado no fluxo de trabalho. Há duas razões comuns para este erro.

  • Há um erro de digitação no fluxo de trabalho.
  • Um recurso ao qual o fluxo de trabalho se refere por caminho foi renomeado, excluído ou movido para um novo local.

Depois de verificar o local do recurso, você poderá atualizar o fluxo de trabalho para especificar o local correto.

Aviso: "git checkout HEAD^2 não é mais necessário"

Se você estiver usando um fluxo de trabalho antigo de CodeQL, você poderá receber o aviso a seguir na saída "Inicializar CodeQL" da ação:

Warning: 1 issue was detected with this workflow: git checkout HEAD^2 is no longer
necessary. Please remove this step as Code Scanning recommends analyzing the merge
commit for best results.

Corrija isto removendo as seguintes linhas do fluxo de trabalho CodeQL. Essas linhas foram incluídas na seção steps do trabalho Analyze nas versões iniciais do fluxo de trabalho do CodeQL.

        with:
          # We must fetch at least the immediate parents so that if this is
          # a pull request then we can checkout the head.
          fetch-depth: 2

      # If this run was triggered by a pull request event, then checkout
      # the head of the pull request instead of the merge commit.
      - run: git checkout HEAD^2
        if: ${{ github.event_name == 'pull_request' }}

A seção revisada steps do fluxo de trabalho terá esta aparência:

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      # Initializes the CodeQL tools for scanning.
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v2

      ...

Para obter mais informações sobre como editar o arquivo de fluxo de trabalho do CodeQL, confira "Como configurar a code scanning".