Varredura de código

Artigo
04/15/2024

A digitalização de código no GitHub Advanced Security para Azure DevOps permite que você analise o código em um repositório do Azure DevOps para encontrar vulnerabilidades de segurança e erros de codificação. Todos os problemas identificados pela análise são gerados como um alerta. A verificação de código usa o CodeQL para identificar vulnerabilidades.

CodeQL é o mecanismo de análise de código desenvolvido pelo GitHub para automatizar verificações de segurança. Você pode analisar seu código usando CodeQL e exibir os resultados como alertas de varredura de código.

O GitHub Advanced Security para Azure DevOps funciona com o Azure Repos. Se você quiser usar o GitHub Advanced Security com repositórios do GitHub, consulte o GitHub Advanced Security.

Alertas do CodeQL

Os especialistas do GitHub, pesquisadores de segurança e colaboradores da comunidade escrevem e fazem a manutenção de consultas padrão do CodeQL usando uma verificação de código. As consultas são regularmente atualizadas para melhorar a análise e reduzir quaisquer resultados falso-positivos. As consultas são de software livre, portanto, você pode exibir e contribuir para as consultas no repositório github/codeql .

Para obter uma documentação mais específica sobre o CodeQL, visite a documentação do CodeQL no GitHub.

CodeQL suporta linguagens compiladas e interpretadas e pode encontrar vulnerabilidades e erros em código escrito nos idiomas suportados.

C/C++
C#
Ir
Java
JavaScript/TypeScript
Kotlin (beta)
Python
Ruby
Swift

Para obter mais informações, consulte a documentação no site do CodeQL sobre linguagens e estruturas compatíveis.

Você pode exibir as consultas específicas e os detalhes da tarefa usados pelo CodeQL examinando o log de build, semelhante à verificação de dependência.

Captura de tela da tarefa de resultados de publicação de verificação de código

Alertas de varredura de código

Os alertas de verificação de código do GitHub Advanced Security para Azure DevOps incluem sinalizadores de verificação de código por repositório que alerta sobre vulnerabilidades de aplicativo no nível de código.

Para usar a verificação de código, primeiro você precisa configurar o GitHub Advanced Security para o Azure DevOps.

A guia Segurança Avançada em Repos no Azure DevOps é o hub para exibir seus alertas de verificação de código. Selecione a guia Verificação de código para exibir alertas de verificação. Você pode filtrar por branch, estado, pipeline, tipo de regra e severidade. No momento, o hub de alertas não exibe alertas para varredura concluída em ramificações de relações públicas.

Não haverá efeito nos resultados se pipelines ou branches forem renomeados – pode levar até 24 horas até que o novo nome seja exibido.

Se você optar por executar consultas CodeQL personalizadas, não haverá, por padrão, um filtro separado para alertas gerados a partir de pacotes de consulta diferentes. Você pode filtrar por regra, que é diferente para cada consulta.

Captura de tela dos alertas de verificação de código para um repositório

Se você desativar a Segurança Avançada para seu repositório, perderá o acesso aos resultados na guia Segurança Avançada e na tarefa de compilação. A tarefa de compilação não falha, mas todos os resultados de compilações executadas com a tarefa enquanto a Segurança Avançada está desabilitada ficam ocultos e não são mantidos.

Detalhes do Alerta

Selecione um alerta para obter mais detalhes, incluindo diretrizes de correção. Cada alerta inclui um local, uma descrição, um exemplo e uma gravidade.

Captura de tela dos detalhes do alerta de verificação de código

Seção	Explicação
Localidade	A seção Locais detalha uma instância específica em que o CodeQL detectou uma vulnerabilidade. Se houver várias instâncias do código violando a mesma regra, um novo alerta será gerado para cada local distinto. O cartão Locais contém um link direto para o snippet de código afetado para que você possa selecionar o snippet a ser direcionado para a interface do usuário da Web do Azure DevOps para edição.
Descrição	A descrição é fornecida pela ferramenta CodeQL com base no problema.
Recomendação	A recomendação é a correção sugerida para um determinado alerta de verificação de código.
Exemplo	A seção de exemplo mostra um exemplo simplificado da fraqueza identificada em seu código.
Severity	Os níveis de gravidade podem ser baixos, médios, altos ou críticos. A pontuação de severidade baseia-se na pontuação de Common Vulnerability Score System (CVSS) fornecida para a Common Weakness Enumeration (CWE). Saiba mais sobre como a gravidade é pontuada nesta postagem no blog do GitHub.

Gerenciar alertas de verificação de códigos

Visualizando alertas de um repositório

Qualquer pessoa com permissões de colaborador para um repositório pode exibir um resumo de todos os alertas de um repositório na guia Segurança Avançada em Repositório. Selecione a guia Verificação de código para exibir todos os alertas de verificação ocultos.

Para exibir resultados, as tarefas de verificação de código precisam ser executadas primeiro. Depois que a primeira verificação for concluída, todas as vulnerabilidades detectadas serão exibidas na guia Segurança Avançada.

Por padrão, a página de alertas mostra os resultados da verificação de dependência para o branch padrão do repositório.

O status de um determinado alerta reflete o estado do branch padrão e do pipeline de execução mais recente, mesmo que o alerta exista em outros branches e pipelines.

Descartando alertas de verificação de código

Para ignorar alertas, você precisa de permissões apropriadas. Por padrão, somente os administradores de projeto podem ignorar alertas de Segurança Avançada.

Para ignorar um alerta:

Navegue até o alerta que você deseja fechar e selecione no alerta.
Selecione a lista suspensa Fechar alerta .
Se ainda não estiver selecionado, selecione Risco aceito ou Falso positivo como o motivo do fechamento.
Adicione um comentário opcional à caixa de texto Comentário .
Selecione Fechar para enviar e fechar o alerta.
O estado de alerta muda de Abrir para Fechado e seu motivo de demissão é exibido.

Captura de tela de como ignorar um alerta de verificação de código

Essa ação descarta apenas o alerta para o branch selecionado. Outros branches que contêm a mesma vulnerabilidade permanecem ativos até serem ignorados. Qualquer alerta anteriormente descartado pode ser reaberto manualmente.

Usando consultas personalizadas com CodeQL

Por padrão, se você não tiver um arquivo de configuração personalizado especificado na configuração do pipeline, o CodeQL executará o security-extended pacote de consulta para analisar seu código. Você pode utilizar consultas CodeQL personalizadas para escrever suas próprias consultas a fim de encontrar vulnerabilidades e erros específicos. Você também precisa criar um arquivo de configuração personalizado para modificar a análise padrão do CodeQL.

Para encontrar consultas personalizadas ou contribuir com sua própria consulta personalizada, consulte Contribuindo para o CodeQL.

Análise com consultas personalizadas

A maneira mais rápida de começar a utilizar uma consulta personalizada é escrever uma consulta e salvá-la em seu repositório local do Azure DevOps. Você pode personalizar os detalhes de uma consulta personalizada de acordo com sua necessidade, mas ela deve ter pelo menos uma ID de regra. Para saber mais sobre como escrever sua própria consulta do CodeQL, consulte Escrevendo consultas do CodeQL. Você também pode agrupar várias consultas em um conjunto de consultas ou utilizar pacotes publicados por outras pessoas. Para saber mais, consulte Publicando e usando pacotes do CodeQL.

Usando um arquivo de configuração personalizado

Um arquivo de configuração personalizado é uma maneira de gerenciar quais consultas serão executadas durante a análise do CodeQL em relação ao seu código. Você pode especificar mais consultas ou pacotes de consulta a serem executados e alterar ou desabilitar as consultas CodeQL padrão.

Para incluir uma consulta específica, especifique a consulta com um nome e um caminho até o local do arquivo de consulta (.ql) em seu repositório.

Para incluir um pacote específico, especifique o nome do pacote. Você pode especificar qualquer número de pacotes de consulta do CodeQL para executar em seu arquivo de configuração.

A próxima etapa é criar um qlpack.yml arquivo. Este arquivo declara o pacote CodeQL e informações sobre ele. Todos *.ql os arquivos no mesmo diretório (ou subdiretório) como um qlpack.yml são considerados parte do pacote.

Dica

O filtro packs do arquivo de configuração oferece suporte ao download de pacotes de repositórios hospedados no GitHub, embora o filtro queries não faça o mesmo. Se o pacote for privado no GitHub, você precisará fornecer um token de acesso ao GitHub por meio da AdvancedSecurity-Codeql-Init@1 tarefa como uma variável de ambiente e nome da variável como GITHUB_TOKEN, com o escopo do token sendo read:packages.

Aqui está um arquivo de configuração de exemplo:

name: "Run custom queries"

# When using a configuration file, if you do not disable default queries,
# then the default CodeQL queries in the `code-scanning` query suite will also execute upon analysis.
disable-default-queries: true
 
# To reference local queries saved to your repository,
# the path must start with `./` followed by the path to the custom query or queries.
# Names for each query referenced is optional.
queries:
  - name: Use security-extended query suite
    uses: security-extended
  - name: Use local custom query (single query)
    uses: ./customQueries/javascript/FindTestFunctions.ql
  - name: Use local custom query (directory of queries)
    uses: ./customQueries/javascript/MemoryLeakQueries  
 
packs:
 - mygithuborg/mypackname
 
paths:
 - src
 
paths-ignore:
  - src/node_modules
  - '**/*.test.js'
 
query-filters:
 - include:
    kind: problem
 - include:
     precision: medium
 - exclude:
    id:
      - js/angular/disabling-sce
      - js/angular/insecure-url-allowlist

Dica

As especificações do arquivo de configuração ignoram e têm precedência sobre as configurações no nível do pipeline para a tarefa AdvancedSecurity-Codeql-Init@1. includepaths / ignorepathsserá ignorado ou, se paths/paths-ignore estiverem presentes, substituído por valores direto de paths/paths-ignore querysuite será substituído por valores especificados em queries ou packs no arquivo de configuração.

Se você estiver usando qualquer consulta personalizada, aqui está um exemplo qlpack.yml colocado no diretório de suas consultas personalizadas:

version: 1.0.1
dependencies:
  codeql/javascript-all: "*"
  codeql/javascript-queries: "*"

A dependencies variável contém todas as dependências deste pacote e seus intervalos de versão compatíveis. Cada dependência é referenciada como a scope/name de um pacote de biblioteca CodeQL. Ao definir dependencieso , você qlpack.yml depende exatamente de um dos pacotes de linguagem principais (por exemplo, JavaScript, C#, Ruby, etc.), que determina a linguagem que sua consulta pode analisar.

Para obter conselhos mais específicos e opções de configuração com seu arquivo de configuração, consulte Personalizando sua configuração avançada para verificação de código ou para qlpack.yml instalação, consulte Estrutura do pacote CodeQL.

Depois de ter o arquivo de configuração, você precisará personalizar o pipeline executando a análise do CodeQL para utilizar o novo arquivo. Veja aqui um pipeline de exemplo apontando para um arquivo de configuração:

trigger: none
 
pool:
  vmImage: windows-latest

# You can either specify your CodeQL variables in a variable block... 
variables:
# `configfilepath` must be an absolute file path relative to the repository root
  advancedsecurity.codeql.configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml' 

# Or you can specify variables as variables for the task. You do not need both definitions. 
steps:
- task: AdvancedSecurity-Codeql-Init@1
  displayName: Initialize CodeQL
  inputs:
    languages: 'javascript'
    loglevel: '2'
    configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml'
# If downloading a pack from GitHub,
# you must include a GitHub access token with the scope of `read:packages`.
  env:
    GITHUB_TOKEN: $(githubtoken)
 
- task: AdvancedSecurity-Codeql-Autobuild@1
  displayName: AutoBuild
 
- task: AdvancedSecurity-Codeql-Analyze@1
  displayName: Perform CodeQL Analysis

Solução de problemas de verificação de código

De modo geral, se você estiver encontrando erros com a execução do CodeQL, a CLI do CodeQL relatará o status de cada comando executado como um código de saída. O código de saída fornece informações para comandos subsequentes ou para outras ferramentas que dependem da CLI do CodeQL. Para obter mais informações sobre detalhes do código de saída, consulte Códigos de saída.

Erro: comando 'database finalize' do CodeQL (32)

Esse erro indica um problema com a finalização da criação do banco de dados CodeQL, possivelmente devido a erros de extração ou a etapas de compilação ausentes.