Partilhar via

Usando consultas personalizadas com o 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 security-extended pacote de consultas para analisar seu código. Você pode utilizar consultas CodeQL personalizadas para escrever suas próprias consultas para 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 localizar consultas personalizadas existentes 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 com 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 um ID de regra. Para obter mais informações sobre como escrever sua própria consulta CodeQL, consulte Escrevendo consultas CodeQL. Você também pode agrupar várias consultas em um pacote de consultas ou utilizar pacotes publicados por outras pessoas. Para obter mais informações, consulte Publicando e usando pacotes CodeQL.

Usando um arquivo de configuração personalizado

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

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

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

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

Gorjeta

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

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

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

Gorjeta

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 AdvancedSecurity-Codeql-Init@1 tarefa. includepaths / ignorepathsserão ignorados ou, se paths/paths-ignore estiverem presentes, substituídos por valores de .paths/paths-ignore querysuite será substituído por valores especificados no queries arquivo de configuração 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ões compatíveis. Cada dependência é referenciada como o scope/name de um pacote de biblioteca CodeQL. Ao definir dependencieso , você qlpack.yml depende exatamente de um dos principais pacotes de idiomas (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 configuração, consulte Estrutura do pacote CodeQL.

Depois de ter seu arquivo de configuração, você precisa personalizar seu pipeline executando a análise CodeQL para utilizar seu novo arquivo. Aqui está 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