Varredura de código
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.
O CodeQL dá suporte a linguagens compiladas e interpretadas e pode encontrar vulnerabilidades e erros no código escrito nas seguintes linguagens com suporte.
- C/C++
- C#
- Ir
- Java
- JavaScript/TypeScript
- Kotlin (beta)
- Python
- Ruby
- Swift
Dica
- Use
java-kotlin
para analisar o código escrito em Java, Kotlin ou ambos. - Use
javascript-typescript
para analisar o código escrito em JavaScript, TypeScript ou ambos.
Para obter mais informações, consulte a documentação no site do CodeQL sobre linguagens e estruturas compatíveis.
O CodeQL usa os seguintes identificadores de idioma:
Idioma | Identificador | Identificadores alternativos opcionais (se houver) |
---|---|---|
C/C++ | c-cpp |
c ou cpp |
C# | csharp |
|
Ir | go |
|
Java/Kotlin | java-kotlin |
|
JavaScript/TypeScript | javascript-typescript |
|
Python | python |
|
Ruby | ruby |
|
Swift | swift |
Dica
- Use
c-cpp
para analisar o código escrito em C, C++ ou ambos - Use
java-kotlin
para analisar o código escrito em Java, Kotlin ou ambos - Use
javascript-typescript
para analisar o código escrito em JavaScript, TypeScript ou ambos
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.
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 PR.
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 direto de pacotes de consulta diferentes. Você pode filtrar por regra, que é diferente para cada consulta.
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 build não falhará, mas os resultados de builds executados com a tarefa enquanto a Segurança Avançada estiver desabilitada estão ocultos e não foram armazenados.
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.
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.
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 que tenha sido descartado anteriormente 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 pacote de consulta security-extended
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 precisará 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 obter mais informações 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 obter mais informações, 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 do 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 arquivo qlpack.yml
. Esse arquivo declara o pacote CodeQL e as informações sobre ele. Quaisquer arquivos *.ql
no mesmo diretório (ou subdiretório) queqlpack.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
/ ignorepaths
será 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, veja este exemplo de qlpack.yml
colocado no diretório das suas consultas personalizadas:
version: 1.0.1
dependencies:
codeql/javascript-all: "*"
codeql/javascript-queries: "*"
A variável dependencies
contém todas as dependências deste pacote e seus intervalos de versões compatíveis. Cada dependência é referenciada como a scope/name
de um pacote de bibliotecas do CodeQL. Ao definir dependencies
, seu qlpack.yml
depende exatamente de um dos pacotes de idiomas principais (por exemplo, JavaScript, C#, Ruby etc.), que determina o idioma que sua consulta pode analisar.
Para obter consultoria e opções de configuração mais específicas sobre o arquivo de configuração, consulte Personalizando sua configuração avançada para verificação de código ou, para qlpack.yml
a configuração, consulte a Estrutura de pacotes 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-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 os detalhes do código de saída, confira 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.
Etapas de solução de problemas:
- Verificar se o código existe e se foi compilado
- Para linguagens compiladas, verifique se o processo de compilação está compilando código e está acontecendo entre as tarefas
AdvancedSecurity-Codeql-Init
eAdvancedSecurity-Codeql-Analyze
. Comandos de compilação comuns e sinalizadores obrigatórios (como limpar no-cache/no-daemon) podem ser encontrados aqui em Especificando comandos de compilação. - Para linguagens interpretadas, confirme se há algum código-fonte para a linguagem especificada no projeto.
- Para linguagens compiladas, verifique se o processo de compilação está compilando código e está acontecendo entre as tarefas
- Verificar erros de extração
- Verifique se os erros de extração afetam a integridade do banco de dados CodeQL.
- Examine o arquivo de log em busca de erros de extração e avisos a fim de avaliar a integridade geral do banco de dados.
- Investigar erros avassaladores
- Se a maioria dos arquivos encontrar erros de extrator, investigue minuciosamente para entender a causa raiz da extração inadequada.
Erro: script de compilação automática (1)
Esse erro descreve uma falha de compilação automática, sugerindo um problema com a instalação ou configuração da verificação de código.
Etapas de solução de problemas:
- Configurar etapas da compilação
- Remova a etapa AutoBuild e configure etapas de compilação específicas para linguagens compiladas em seus pipelines.
- Consulte as diretrizes de instalação fornecidas em Configurar o GitHub Advanced Security para Azure DevOps.
Erro: Diretórios CodeQL não encontrados no cache da ferramenta do agente
Esse erro indica um problema com a instalação do CodeQL para agentes auto-hospedados.
Etapas de solução de problemas:
- Consulte as diretrizes de instalação ou os scripts de configuração fornecidos em Configurar o GitHub Advanced Security para Azure DevOps.
Erro: variável do pipeline de linguagem não definida
Esse erro ocorre ao tentar executar o CodeQL sem definir a variável do pipeline especificando quais linguagens serão verificadas.
Etapas de solução de problemas:
- Definir variável do pipeline de linguagem
- Verifique se a variável do pipeline de linguagem está configurada corretamente. Consulte as diretrizes de instalação fornecidas em Configurar o GitHub Advanced Security para Azure DevOps.
- As linguagens permitidas são
csharp
,cpp
,go
,java
,javascript
,python
,ruby
eswift
.
CodeQL não retorna resultados
Esta seção fornece orientação para situações em que a análise do CodeQL não produz resultados.
Etapas de solução de problemas:
- Verificar vulnerabilidades detectadas
- Considere a possibilidade de que seu código possa genuinamente não ter vulnerabilidades. Se vulnerabilidades forem esperadas, mas não detectadas, prossiga para fazer outras verificações.
- Revisar a configuração do pacote de consultas
- Confirme o pacote de consultas que está sendo usado e considere alternar para um pacote mais abrangente, se necessário.
- Como alternativa, pacotes de consultas personalizados podem ser criados para análise personalizada.
- Ajustar permissões para exibir resultados
- Certifique-se de que permissões adequadas, pelo menos no nível do colaborador, sejam concedidas para acessar os resultados da análise. Para obter mais informações, consulte: Permissões de segurança avançada.
CodeQL expirando
Se a tarefa AdvancedSecurity-Codeql-Analyze@1
estiver sendo exibida This job was abandoned ... we lost contact with the agent
e você estiver usando um agente hospedado da Microsoft, a tarefa atingirá o tempo limite interno de seis horas para agentes hospedados pagos. Em vez disso, você pode tentar executar a análise em um agente auto-hospedado.
Permissões de tarefa de verificação de código
A tarefa de build de verificação de código usa a identidade do pipeline para chamar as APIs REST de Segurança Avançada. Por padrão, os pipelines no mesmo projeto têm acesso para carregar o arquivo SARIF gerado executando a análise do CodeQL. Se essas permissões forem removidas da conta de serviço de build ou se tiver uma configuração personalizada (por exemplo, um pipeline hospedado em um projeto diferente do repositório), você deverá conceder essas permissões manualmente.
Etapas de solução de problemas:
- Conceda as permissões
Advanced Security: View alerts
eAdvanced Security: Manage and dismiss alerts
à conta de serviço de build usada em seu pipeline, que para pipelines com escopo de projeto é[Project Name] Build Service ([Organization Name])
, e para pipelines com escopo de coleção éProject Collection Build Service ([Organization Name])
.
Instalação manual do pacote CodeQL no agente auto-hospedado
Instale o pacote CodeQL no cache da ferramenta do agente utilizando o script de configuração para sua arquitetura, disponível no GitHub. Esses scripts exigem que a $AGENT_TOOLSDIRECTORY
variável de ambiente seja definida como o local do diretório de ferramentas do agente no agente, por exemplo C:/agent/_work/_tool
, . Como alternativa, você pode implementar manualmente as seguintes etapas:
- Escolha o pacote de versão mais recente do CodeQL no GitHub.
- Faça download e descompacte o pacote no seguinte diretório dentro do diretório de ferramentas do agente, normalmente localizado em
_work/_tool
:./CodeQL/0.0.0-[codeql-release-bundle-tag]/x64/
. Com a versão atual dov2.16.0
, o nome da pasta será./CodeQL/0.0.0-codeql-bundle-v2.16.0/x64/
. Saiba mais sobre o diretório de ferramentas do agente. - Crie um arquivo vazio intitulado
x64.complete
dentro da pasta./CodeQL/0.0.0-[codeql-release-bundle-tag]
. Usando o exemplo anterior, o caminho do arquivo final até o arquivox64.complete
deve ser./CodeQL/0.0.0-codeql-bundle-v2.16.0/x64.complete
.