Compartilhar via

Usando consultas personalizadas com CodeQL

  • Artigo

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) que 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 / 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