Personalizar o fluxo de trabalho de varredura de código com CodeQL – parte 2

8 minutos

Os fluxos de trabalho de varredura de código que usam CodeQL têm várias opções de configuração que podem ser ajustadas para atender melhor às necessidades da sua organização.

Nesta unidade, veremos como referenciar consultas adicionais em um arquivo de configuração personalizado.

Consultas adicionais em um arquivo de configuração personalizado

Um arquivo de configuração personalizado é uma maneira alternativa de especificar pacotes e consultas adicionais a serem executados. Você também pode usar o arquivo para desabilitar as consultas padrão e especificar quais diretórios examinar durante a análise.

No arquivo de fluxo de trabalho, use o parâmetro config-file da ação init para especificar o caminho para o arquivo de configuração que você deseja usar. Este exemplo carrega o arquivo de configuração ./.github/codeql/codeql-config.yml.

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml

O arquivo de configuração pode estar localizado no repositório que você está analisando ou em um repositório externo. O uso de um repositório externo permite que você especifique opções de configuração para vários repositórios em um único local. Ao fazer referência a um arquivo de configuração localizado em um repositório externo, você poderá usar a sintaxe OWNER/REPOSITORY/FILENAME@BRANCH. Por exemplo: octo-org/shared/codeql-config.yml@main.

Se o arquivo de configuração estiver localizado em um repositório privado externo, use o parâmetro external-repository-token da ação init para especificar um token que tenha acesso ao repositório privado.

- uses: github/codeql-action/init@v3
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

As configurações no arquivo de configuração são gravadas no formato YAML.

Especificar pacotes de consulta CodeQL em arquivos de configuração personalizados

Observação

A funcionalidade de gerenciamento de pacotes CodeQL, incluindo os pacotes do CodeQL, está atualmente em beta e está sujeita a alterações.

Você pode especificar pacotes de consulta do CodeQL em uma matriz. O formato é diferente do formato usado pelo arquivo de fluxo de trabalho.

packs:
packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/pack2@1.2.3
  # Use the latest version of 'pack3' compatible with 3.2.1
  - scope/pack3@~3.2.1
  # Use pack4 and restrict it to queries found in the 'path/to/queries' directory
  - scope/pack4:path/to/queries
  # Use pack5 and restrict it to the query 'path/to/single/query.ql'
  - scope/pack5:path/to/single/query.ql
  # Use pack6 and restrict it to the query suite 'path/to/suite.qls'
  - scope/pack6:path/to/suite.qls

O formato completo para especificar um pacote de consultas é scope/name[@version][:path]. version e path são opcionais. version é o intervalo de versão semver. Se ele estiver ausente, a versão mais recente será usada.

Se você tiver um fluxo de trabalho que gere mais de um banco de dados CodeQL, poderá especificar quaisquer pacotes de consulta do CodeQL a serem executados em um arquivo de configuração personalizado usando um mapa aninhado de pacotes.

packs:
  # Use these packs for JavaScript and TypeScript analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java and Kotlin analysis
  java:
    - scope/java-pack1
    - scope/java-pack2@v1.0.0

Especificar consultas adicionais em uma configuração personalizada

Você pode especificar consultas adicionais em uma matriz queries. Cada elemento da matriz contém um parâmetro uses com um valor que identifica um arquivo de consulta individual, um diretório contendo arquivos de consulta ou um arquivo de definição de conjunto de consultas.

queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./query-suites/my-security-queries.qls

Opcionalmente, você pode dar um nome a cada elemento da matriz, conforme mostrado no seguinte arquivo de configuração de exemplo:

name: "My CodeQL config"

disable-default-queries: true

queries:
  - name: Use an in-repository QL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript QL pack (run queries from an external repo)
    uses: octo-org/javascript-qlpack@main
  - name: Use an external query (run a single query from an external QL pack)
    uses: octo-org/python-qlpack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

Desabilitar as consultas padrão

Se você quiser apenas executar consultas personalizadas, poderá desabilitar as consultas de segurança padrão usando disable-default-queries: true. Você deve usar esse sinalizador se estiver tentando criar um conjunto de consultas personalizado que exclua uma regra em particular. Isso evita que todas as consultas sejam executadas duas vezes.

Como excluir consultas específicas da análise

Você pode adicionar os filtros exclude e include ao arquivo de configuração personalizado para especificar as consultas que deseja excluir ou incluir na análise, como:

Consultas específicas dos pacotes padrão (security, security-extended e security-and-quality).
Consultas específicas cujos resultados não lhe interessam.
Todas as consultas que geram avisos e recomendações.

Você pode usar filtros exclude semelhantes aos da configuração do arquivo a seguir para excluir as consultas que deseja remover da análise padrão. No exemplo a seguir de um arquivo de configuração, tanto as consultas js/redundant-assignment quanto as consultas js/useless-assignment-to-local são excluídas da análise.

query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

Para encontrar a ID de uma consulta, clique no alerta na lista de alertas na guia Segurança. A página de detalhes do alerta será aberta. O campo ID da Regra contém a ID da consulta.

Considerações sobre o uso do filtro excludes:

A ordem dos filtros faz diferença. A primeira instrução de filtro exibida após as instruções sobre as consultas e os pacotes de consulta determina se as consultas são incluídas ou excluídas por padrão.
As instruções subsequentes são executadas em ordem e as instruções que aparecem posteriormente no arquivo têm precedência sobre as instruções anteriores.

Especificar os diretórios a serem verificados

Para as linguagens interpretadas às quais o CodeQL dá suporte (Python, Ruby e JavaScript/TypeScript), você pode restringir a verificação de código a arquivos de diretórios específicos adicionando uma matriz paths ao arquivo de configuração. Você pode excluir os arquivos de diretórios específicos da análise ao adicionar uma matriz paths-ignore.

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

Observação

As palavras-chave paths e paths-ignore, usadas no contexto do arquivo de configuração de verificação de código, não devem ser confundidas com as mesmas quando utilizadas em um fluxo de trabalho on.<push|pull_request>.paths. Quando são usadas para modificar on.<push|pull_request> em um fluxo de trabalho, elas determinam se as ações serão executadas quando alguém modificar o código nos diretórios especificados.
Os caracteres de padrão de filtro ?, +, [, ] e ! não têm suporte e serão correspondidos literalmente.
Os caracteres ** só podem estar no início ou no final de uma linha, ou circundados por barras, e você não pode misturar ** e outros caracteres. Por exemplo, foo/**, **/foo e foo/**/bar são todas sintaxes permitidas, mas **foo não é. No entanto, você pode usar estrelas simples junto com outros caracteres, conforme mostrado no exemplo. Você precisará citar qualquer coisa que contenha um caractere *.

Para linguagens compiladas, se você quiser limitar a varredura de código para diretórios específicos em seu projeto, deverá especificar as etapas de compilação apropriadas no fluxo de trabalho. Os comandos que você precisará usar para excluir um diretório da compilação dependerão do seu sistema de compilação.

Você pode analisar rapidamente pequenas partes de um repositório único quando modifica o código em diretórios específicos. Você precisará excluir os diretórios em suas etapas de compilação e usar as palavras-chave paths-ignore e paths para on.<push|pull_request> em seu fluxo de trabalho.

Comentários

Esta página foi útil?