Sobre os pacotes do CodeQL

Sobre os pacotes do CodeQL

Os pacotes do CodeQL são usados para criar, compartilhar, gerar dependência e executar consultas e bibliotecas do CodeQL. Você pode publicar os próprios pacotes do CodeQL e baixar pacotes criados por outras pessoas. Os pacotes do CodeQL contêm consultas, arquivos de biblioteca, conjuntos de consultas e metadados.

Há dois tipos de pacotes do CodeQL: pacotes de consultas e pacotes de biblioteca.

• Os pacotes de consultas foram projetados para serem executados. Quando um pacote de consultas é publicado, ele inclui todas as dependências transitivas e um cache de compilação. Isso garante a execução consistente e eficiente das consultas no pacote.

• Os pacotes de biblioteca são projetados para serem usados por pacotes de consultas (ou outros pacotes de biblioteca) e não contêm consultas. As bibliotecas não são compiladas e não há nenhum cache de compilação incluído quando o pacote é publicado.

Você pode usar os comandos de gerenciamento de pacotes na CodeQL CLI para criar pacotes do CodeQL, adicionar dependências a pacotes e instalar ou atualizar dependências. Para obter mais informações, confira "Como criar e trabalhar com pacotes do CodeQL". Você também pode publicar e baixar pacotes do CodeQL usando a CodeQL CLI. Para obter mais informações, confira "Como publicar e usar pacotes CodeQL".

Os pacotes padrão do CodeQL para todas as linguagens com suporte são publicados no Container registry. O repositório do CodeQL contém arquivos de origem dos pacotes padrão do CodeQL para todas as linguagens com suporte.

Estrutura de pacotes do CodeQL

Um pacote do CodeQL precisa conter um arquivo chamado qlpack.yml no diretório raiz. No arquivo qlpack.yml, o campo name: precisa ter um valor que siga o formato <scope>/<pack>, em que <scope> é a organização ou a conta de usuário do GitHub em que o pacote será publicado e <pack> é o nome do pacote. Além disso, pacotes de consultas e pacotes de biblioteca com testes do CodeQL contêm um arquivo codeql-pack.lock.yml com as dependências resolvidas do pacote. Esse arquivo é gerado durante uma chamada ao comando codeql pack install, não deve ser editado manualmente e deve ser adicionado ao sistema de controle de versão.

Os outros arquivos e diretórios no pacote devem ser organizados logicamente. Por exemplo, normalmente:

• As consultas são organizadas em diretórios para categorias específicas.

• As consultas para produtos, bibliotecas e estruturas específicas são organizadas em seus próprios diretórios de nível superior.

Sobre os arquivos qlpack.yml

Ao executar comandos relacionados à consulta, o CodeQL primeiro procura arquivos qlpack.yml em irmãos do diretório de instalação (e nos subdiretórios). Depois, ele verifica o cache de pacotes do CodeQL em busca daqueles que foram baixados. Isso significa que, quando você está desenvolvendo consultas localmente, os pacotes locais no diretório de instalação substituem os pacotes com o mesmo nome no cache de pacotes, para que você possa testar as alterações locais.

Os metadados em cada arquivo qlpack.yml informam ao CodeQL como compilar consultas no pacote, de quais bibliotecas o pacote depende e onde encontrar as definições do conjunto de consultas.

O conteúdo do pacote do CodeQL (consultas ou bibliotecas usadas na análise do CodeQL) está incluído no mesmo diretório que o qlpack.yml ou em nos subdiretórios.

O diretório que contém o arquivo qlpack.yml funciona como o diretório raiz do conteúdo do pacote do CodeQL. Ou seja, para todos os arquivos .ql e .qll no pacote, o CodeQL resolverá todas as instruções de importação relativas ao diretório que contém o arquivo qlpack.yml na raiz do pacote.

Propriedades qlpack.yml

As propriedades a seguir são compatíveis com arquivos qlpack.yml.

name

• Exigido por todos os pacotes.
• Define o escopo do pacote, em que o pacote do CodeQL é publicado e o nome do pacote é definido usando caracteres alfanuméricos e hifens. Esse campo precisa ser exclusivo, pois o CodeQL não pode diferenciar pacotes do CodeQL com nomes idênticos. Use o nome do pacote para especificar as consultas a serem executadas usando database analyze e para definir dependências entre pacotes do CodeQL (veja os exemplos abaixo). Por exemplo:

  name: octo-org/security-queries
  

version

• Exigido por todos os pacotes publicados.
• Define uma versão semântica desse pacote do CodeQL que precisa seguir à especificação SemVer v2.0.0. Por exemplo:

  version: 0.0.0
  

dependencies

• Exigido por pacotes que definem as dependências de pacote do CodeQL em outros pacotes.
• Define um mapa de referências de pacote para o intervalo de versão semântica compatível com esse pacote. Compatível com a CodeQL CLI versões v2.6.0 e posteriores. Por exemplo:

  dependencies:
    codeql/cpp-all: ^0.0.2`
  

defaultSuiteFile

• Required by packs that export a set of default queries to run.
• Defines the path to a query suite file relative to the package root, containing all of the queries that are run by default when this pack is passed to the codeql database analyze command. Supported from CLI version v2.6.0 and onwards. Only one of defaultSuiteFile or defaultSuite can be defined. For example:

  defaultSuiteFile: cpp-code-scanning.qls
  

defaultSuite

• Exigido por pacotes que exportam um conjunto de consultas padrão para execução.
• Define um conjunto de consultas embutidas que contém todas as consultas que são executadas por padrão quando esse pacote é passado para o comando codeql database analyze. Compatível com a CLI versão v2.6.0 e posteriores. Só é possível definir defaultSuiteFile ou defaultSuite. Por exemplo:

  defaultSuite:
    queries: .
    exclude:
      precision: medium
  

library

• Exigido por pacotes de biblioteca.
• Define um valor booliano que indica se esse pacote é ou não um pacote de biblioteca. Os pacotes de biblioteca não contêm consultas e não são compilados. Os pacotes de consultas podem ignorar esse campo ou defini-lo explicitamente como false. Por exemplo:

  library: true
  

suites

• Opcional para pacotes que definem conjuntos de consultas.
• Define o caminho para um diretório no pacote que contém os conjuntos de consultas que a CodeQL CLI precisa reconhecer, em relação ao diretório do pacote. Os usuários de pacote do CodeQL podem executar pacotes "conhecidos" armazenados nesse diretório especificando o nome do pacote, sem fornecer o caminho completo. Sem suporte para pacotes do CodeQL baixados do registro de contêiner. Para obter mais informações sobre os conjuntos de consultas, confira "Como criar conjuntos de consultas do CodeQL". Por exemplo:

  suites: octo-org-query-suites
  

tests

• Opcional para pacotes que contêm testes do CodeQL. Ignorado para pacotes sem testes.
• Define o caminho para um diretório dentro do pacote que contém testes, definido em relação ao diretório do pacote. Use . para especificar o pacote inteiro. Todas as consultas nesse diretório são executadas como testes quando test run é executado com a opção --strict-test-discovery. Essas consultas são ignoradas por definições de conjunto de consultas que usam instruções queries ou qlpack para solicitar todas as consultas em um pacote específico. Se essa propriedade estiver ausente, . será assumido. Por exemplo:

  tests: .
  

extractor

• Exigido por todos os pacotes que contêm testes do CodeQL.
• Define o extrator de linguagem do CodeQL a ser usado ao executar os testes do CodeQL no pacote. Para obter mais informações de como testar consultas, confira "Como testar consultas personalizadas". Por exemplo:

  extractor: javascript
  

authors

• Opcional.
• Define os metadados que serão exibidos na página de pesquisa de empacotamento na seção de pacotes da conta em que o pacote do CodeQL foi publicado. Por exemplo:

  authors: author1@github.com,author2@github.com 
  

license

• Opcional.
• Define os metadados que serão exibidos na página de pesquisa de empacotamento na seção de pacotes da conta em que o pacote do CodeQL foi publicado. Para obter uma lista de licenças permitidas, confira Lista de licenças SPDX na Especificação SPDX. Por exemplo:

  license: MIT
  

description

• Opcional.
• Define os metadados que serão exibidos na página de pesquisa de empacotamento na seção de pacotes da conta em que o pacote do CodeQL foi publicado. Por exemplo:

  description: Human-readable description of the contents of the CodeQL pack.
  

libraryPathDependencies

• Opcional, preterido. Use a propriedade dependencies.
• Usado anteriormente para definir os nomes de qualquer pacote do CodeQL dos quais esse pacote do CodeQL depende, como uma matriz. Fornece ao pacote acesso a todas as bibliotecas, esquemas de banco de dados e conjuntos de consultas definidos na dependência. Por exemplo:

  libraryPathDependencies: codeql/javascript-all 
  

dbscheme

• Exigido apenas por pacotes de linguagens principais.
• Define o caminho para o esquema de banco de dados para todas as bibliotecas e consultas escritas para essa linguagem do CodeQL (veja o exemplo abaixo). Por exemplo:

  dbscheme: semmlecode.python.dbscheme
  

upgrades

• Exigido apenas por pacotes de linguagens principais.
• Define o caminho para um diretório dentro do pacote que contém scripts de atualização de banco de dados, definidos em relação ao diretório do pacote. As atualizações de banco de dados são usadas internamente para garantir que um banco de dados criado com uma versão diferente da CodeQL CLI seja compatível com a versão atual da CLI. Por exemplo:

  upgrades: .
  

Sobre os arquivos codeql-pack.lock.yml

Os arquivos codeql-pack.lock.yml armazenam as versões das dependências transitivas resolvidas de um pacote do CodeQL. Esse arquivo será criado pelo comando codeql pack install se ele ainda não existir e deverá ser adicionado ao sistema de controle de versão. A seção dependencies do arquivo qlpack.ymlcontém intervalos de versão compatíveis com o pacote. O arquivo codeql-pack.lock.yml bloqueia as versões para dependências precisas. Isso garante que a execução de codeql pack install nesse pacote sempre recupere as mesmas versões de dependências, mesmo que existam versões compatíveis mais recentes.

Por exemplo, se um arquivo qlpack.yml contiver as seguintes dependências:

dependencies:
  codeql/cpp-all: ^0.1.2
  my-user/my-lib: ^0.2.3
  other-dependency/from-source: "*"

O arquivo codeql-pack.lock.yml conterá algo semelhante ao seguinte:

dependencies:
  codeql/cpp-all:
    version: 0.1.4
  my-user/my-lib:
    version: 0.2.4
  my-user/transitive-dependency:
    version: 1.2.4

A dependência codeql/cpp-all está bloqueada para a versão 0.1.4. A dependência my-user/my-lib está bloqueada para a versão 0.2.4. O my-user/transitive-dependency, que é uma dependência transitiva e não é especificado no arquivo qlpack.yml, está bloqueado para a versão 1.2.4. O other-dependency/from-source está ausente do arquivo de bloqueio, pois é resolvido da origem. Essa dependência precisa estar disponível no mesmo workspace do CodeQL que o pacote. Para obter mais informações sobre os workspaces do CodeQL e resolver dependências por meio da origem, confira "Sobre os workspaces do CodeQL".

Na maioria dos casos, o arquivo codeql-pack.lock.yml só é relevante para pacotes de consulta, pois os pacotes de biblioteca não são executáveis e geralmente não precisam que as dependências transitivas sejam corrigidas. A exceção a isso é para pacotes de biblioteca que contêm testes. Nesse caso, o arquivo codeql-pack.lock.yml é usado para garantir que os testes sejam sempre executados com as mesmas versões de dependências para evitar falhas falsas quando houver dependências incompatíveis.

Exemplos de pacotes personalizados do CodeQL

Ao escrever consultas ou testes personalizados, você deve salvá-los em pacotes personalizados do CodeQL. Para simplificar, tente organizar cada pacote logicamente. Para obter mais informações, confira "Sobre a estrutura de pacotes do CodeQL". Salve arquivos para consultas e testes em pacotes separados e, sempre que possível, organize pacotes personalizados em pastas específicas para cada linguagem de destino. Isso é muito útil quando você pretende publicar os pacotes do CodeQL para que eles possam ser compartilhados com outras pessoas ou usados na verificação de código. Para obter mais informações, confira "Sobre a varredura de código com CodeQL".

Pacotes do CodeQL para bibliotecas personalizadas

Um pacote personalizado do CodeQL que contém bibliotecas C++ personalizadas, sem consultas ou testes, pode ter um arquivo qlpack.yml contendo:

name: my-github-user/my-custom-libraries
version: 1.2.3
library: true
dependencies:
  codeql/cpp-all: ^0.1.2

em que codeql/cpp-all é o nome do pacote do CodeQL para análise do C/C++ incluído no repositório do CodeQL. O intervalo de versão ^0.1.2 indica que esse pacote é compatível com todas as versões do codeql/cpp-all iguais ou superiores à 0.1.2 e inferiores a 0.2.0. Qualquer arquivo de biblioteca do CodeQL (um arquivo com uma extensão .qll) definido nesse pacote estará disponível para consultas definidas em qualquer pacote de consultas que inclua esse pacote no bloco de dependências.

A propriedade library indica que esse pacote é um pacote de biblioteca e não contém nenhuma consulta.

Pacotes do CodeQL para consultas personalizadas

Um pacote personalizado do CodeQL que contém consultas e bibliotecas C++ personalizadas pode ter um arquivo qlpack.yml contendo:

name: my-github-user/my-custom-queries
version: 1.2.3
dependencies:
  codeql/cpp-all: ^0.1.2
  my-github-user/my-custom-libraries: ^1.2.3
suites: my-custom-suites

em que codeql/cpp-all é o nome do pacote do CodeQL para análise do C/C++ incluído no repositório do CodeQL. O intervalo de versão ^0.1.2 indica que esse pacote é compatível com todas as versões do codeql/cpp-all iguais ou superiores à 0.1.2 e inferiores a 0.2.0. my-github-user/my-custom-libraries é o nome de um pacote do CodeQL que contém bibliotecas personalizadas do CodeQL para C++. Qualquer arquivo de biblioteca do CodeQL (um arquivo com uma extensão .qll) definido neste pacote estará disponível para consultas no pacote my-github-user/my-custom-queries.

A propriedade suites indica um diretório em que podem ser encontrados conjuntos de consultas "conhecidos". Esses pacotes podem ser usados na linha de comando se referindo apenas ao nome, em vez do caminho completo. Para obter mais informações sobre os conjuntos de consultas, confira "Como criar conjuntos de consultas do CodeQL".

Pacotes do CodeQL para testes personalizados

Para pacotes personalizados do CodeQL que contêm arquivos de teste, você também precisa incluir uma propriedade extractor para que o comando test run saiba como criar bancos de dados de teste. Você também pode especificar a propriedade tests.

O arquivo qlpack.yml a seguir informa que my-github-user/my-query-tests depende de my-github-user/my-custom-queries em uma versão igual ou superior a 1.2.3 e inferior a 2.0.0. Ele também declara que a CLI deve usar o Java extractor ao criar bancos de dados de teste. A linha tests: . declara que todos os arquivos .ql no pacote devem ser executados como testes quando codeql test run é executado com a opção --strict-test-discovery. Normalmente, os pacotes de teste não contêm uma propriedade version. Isso impede que você os publique acidentalmente.

  name: my-github-user/my-query-tests
  dependencies:
    my-github-user/my-custom-queries: ^1.2.3
  extractor: java
  tests: .

Para obter mais informações de como executar testes, confira "Como testar consultas personalizadas".

Exemplos de pacotes do CodeQL no repositório do CodeQL

Cada uma das linguagens no repositório do CodeQL tem quatro pacotes principais do CodeQL:

• Pacote de biblioteca principal da linguagem, com o esquema de banco de dados usado pela linguagem e as bibliotecas e consultas do CodeQL em <language>/ql/lib

• Pacote de consultas principal para a linguagem que inclui as consultas padrão das linguagens, juntamente com os conjuntos de consultas em <language>/ql/src

• Testes para as principais bibliotecas e consultas de linguagem em <language>/ql/test

• Exemplo de consultas para a linguagem em <language>/ql/examples

Pacote de biblioteca principal

Veja um arquivo de exemplo qlpack.yml do pacote de linguagem principal das bibliotecas de análise do C/C++:

name: codeql/cpp-all
version: x.y.z-dev
dbscheme: semmlecode.cpp.dbscheme
library: true
upgrades: upgrades

Algumas observações adicionais sobre as seguintes propriedades:

• library: indica que esse é um pacote de biblioteca sem consultas executáveis. Ele só deve ser usado como uma dependência de outros pacotes.

• dbscheme e upgrades: essas propriedades são internas da CodeQL CLI e só devem ser definidas no pacote do QL principal de uma linguagem.

Pacote de consultas principal

Veja um arquivo de exemplo qlpack.yml de pacote de consultas principal de consultas de análise do C/C++:

name: codeql/cpp-queries
version: x.y.z-dev
dependencies:
    codeql/cpp-all: "*"
    codeql/suite-helpers: "*"
suites: codeql-suites
defaultSuiteFile: codeql-suites/cpp-code-scanning.qls

Algumas observações adicionais sobre as seguintes propriedades:

• dependencies: esse pacote de consultas depende de codeql/cpp-all e codeql/suite-helpers. Como essas dependências são resolvidas na origem, não importa com qual versão do pacote do CodeQL elas são compatíveis. Para obter mais informações de como resolver as dependências por meio da origem, confira "Dependências de origem".

• suites: indica o diretório que contém conjuntos de consultas "conhecidos".

• defaultSuiteFile: o nome do arquivo do pacote de consultas padrão usado quando nenhum pacote de consultas é especificado.

Testes para o pacote principal do CodeQL

Veja um arquivo de exemplo qlpack.yml do pacote de teste principal para testes de análise do C/C++:

name: codeql/cpp-tests
dependencies:
  codeql/cpp-all: "*"
  codeql/cpp-queries: "*"
extractor: cpp
tests: .

Algumas observações adicionais sobre as seguintes propriedades:

• dependencies: esse pacote depende da consulta principal do CodeQL e dos pacotes de biblioteca para C++.

• extractor: especifica que todos os testes usarão o mesmo extrator C++ para criar o banco de dados para os testes.

• tests: especifica o local dos testes. Nesse caso, os testes estão na pasta raiz (e em todas as subpastas) do pacote.

• version: não há nenhuma propriedade version para o pacote de testes. Isso impede que os pacotes de teste sejam publicados acidentalmente.