Referência de pacotes de consulta CodeQL

CodeQL Compatibilidade do pacote

Quando um pacote de consultas é publicado, ele inclui representações pré-compiladas de todas as consultas nele para aumentar a velocidade da análise. No entanto, se a versão do CodeQL que realiza a análise for mais de 6 meses mais recente do que a versão que executou codeql pack publish, talvez seja necessário compilar as consultas a partir do código-fonte durante a análise, tornando o processo significativamente mais lento.

Um pacote publicado pelo lançamento público mais recente de CodeQL poderá ser usado pela versão de CodeQL que é usada por code scanning e GitHub Actions, embora essa geralmente seja uma versão um pouco mais antiga.

Se sua análise contiver linhas como as seguintes, então CodeQL estará usando consultas pré-compiladas com êxito:

[42/108] Loaded /long/path/to/query/Filename.qlx.

Se a sua análise contiver linhas semelhantes às seguintes, então CodeQL você recompilou manualmente as consultas a partir do código-fonte:

Compiling query plan for /long/path/to/query/Filename.ql.
[42/108 comp 25s] Compiled /long/path/to/query/Filename.ql.

Para ajudar os usuários do seu pacote de consultas a aproveitarem consultas pré-compiladas, recomendamos usar uma versão recente de CodeQL para publicar seus pacotes. Além disso, você deve publicar uma nova versão do pacote com uma versão atualizada CodeQL a cada 6 meses.

Se você publicar pacotes de consulta com a intenção de usá-los em uma instalação do GitHub Enterprise Server que usa seus binários CodeQL incluídos, use a mesma versão do CodeQL para executar codeql pack publish.

`qlpack.yml` arquivos

Ao executar comandos relacionados a consultas, CodeQL primeiro procura arquivos qlpack.yml nos diretórios irmãos do diretório de instalação (e em seus subdiretórios) e, em seguida, verifica no cache de pacotes se há pacotes CodeQL baixados. Isso significa que, quando seus pacotes locais no diretório de instalação substituem pacotes com o mesmo nome no cache de pacotes, você pode testar suas alterações locais.

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

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

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

`qlpack.yml` propriedades

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 CodeQL pacote é publicado e o nome do pacote definido usando caracteres alfanuméricos e hifens. Ele deve ser exclusivo, pois CodeQL não pode diferenciar entre CodeQL pacotes com nomes idênticos. Use o nome do pacote para especificar consultas a serem executadas usando database analyze e definir dependências entre CodeQL pacotes (veja exemplos abaixo). Por exemplo:
```
name: octo-org/security-queries
```

`version`

Exigido por todos os pacotes publicados.
Define uma versão semântica para este CodeQL pacote que deve seguir a especificação SemVer v2.0.0. Por exemplo:
```
version: 0.0.0
```

`dataExtensions`

Exigido por pacotes de modelos.
Obtém uma lista de padrões glob que especificam onde os arquivos de extensão de dados estão localizados em relação à raiz do pacote de consulta ou pacote de bibliotecas.

`dependencies`

Necessário para pacotes de consulta e pacotes de biblioteca que definem dependências de pacote CodeQL de outros pacotes. Pacotes de modelos não podem definir dependências e, em vez disso, usam extensionTargets.
Define um mapa de referências de pacote para o intervalo de versão semântica compatível com esse pacote. Com suporte para CodeQL CLI versões v2.6.0 e posteriores. Por exemplo:
```
dependencies:
  codeql/cpp-all: ^0.0.2
```
Se você não tiver certeza ou não importa qual versão deve ser usada, então pode usar "*", o que indica que qualquer versão dessa dependência é compatível com este pacote. Na prática, isso geralmente será resolvido para a versão publicada mais alta da dependência.

Há um marcador de versão especial, ${workspace}, que indica que este pacote CodeQL depende da versão da dependência que estiver no mesmo workspace. Para saber mais, confira Workspaces do CodeQL.

`defaultSuiteFile`

Exigido por pacotes que exportam um conjunto de consultas padrão para execução.
Define o caminho para um arquivo de pacote de consultas em relação à raiz do pacote, contendo 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:
```
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
```

`extensionTargets`

Exigido por pacotes de modelos.
Declara a quais pacotes de consultas as extensões no pacote de modelos se aplicam. O pacote de extensões injetará suas extensões de dados em cada pacote nomeado no dicionário extensionTargets, se o pacote estiver dentro do intervalo de versão especificado e for usado na avaliação.

`groups`

Opcional.
Define agrupamentos lógicos de pacotes em um CodeQL workspace. Usar grupos é uma maneira de aplicar operações de pacote a subconjuntos de pacotes em um espaço de trabalho. Por exemplo, o pacote a seguir é definido para fazer parte dos grupos java e experimental:
```
groups:
  - java
  - experimental
```
A execução de codeql pack publish --groups java,-experimental publicará todos os pacotes no grupo java, exceto os pacotes experimental. Você pode executar o comando codeql pack ls --groups [-]<group>[,[-]<group>...] para listar os pacotes em um espaço de trabalho que correspondem ao conjunto especificado de grupos.

Um pacote CodeQL no espaço de trabalho determinado estará incluído na lista se:
- Ele estiver em, pelo menos, um dos grupos listados sem um sinal de subtração (essa condição será atendida automaticamente se não houver grupos listados sem um sinal de subtração) e
- Ele não estiver em nenhum grupo listado com um sinal de subtração.

`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. Isso permite que os usuários executem conjuntos de consultas armazenados no diretório especificado especificando o nome do pacote, sem fornecer o caminho completo.
Atualmente, há suporte apenas para os pacotes de consulta padrão incluídos no CodeQL pacote da CLI.
Essa opção não tem suporte para CodeQL pacotes baixados do GitHub registro de contêiner.

`tests`

Opcional para pacotes que contêm CodeQL testes. 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`

Obrigatório para todos os pacotes que contêm testes CodeQL.
Define o CodeQL extrator de idioma a ser usado ao executar os CodeQL testes no pacote. Para obter mais informações sobre como testar as consultas, confira Testar consultas personalizadas. Por exemplo:
```
extractor: javascript-typescript
```

`authors`

Opcional.
Define os metadados que serão exibidos na página de pesquisa de pacotes, na seção de pacotes da conta na qual o pacote CodeQL é publicado. Por exemplo:
```
authors: [email protected],[email protected]
```

`license`

Opcional.
Define os metadados que serão exibidos na página de pesquisa de pacotes, na seção de pacotes da conta na qual o pacote CodeQL é 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 pacotes, na seção Pacotes da conta na qual o pacote CodeQL foi publicado. Por exemplo:
```
description: Human-readable description of the contents of the CodeQL pack.
```

`libraryPathDependencies`

Opcional, encerrando. Use a propriedade dependencies.
Usado anteriormente para definir os nomes de todos CodeQL os pacotes dos quais esse CodeQL pacote 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 esse CodeQL idioma (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 do banco de dados são usadas internamente para garantir que um banco de dados criado com uma versão diferente do CodeQL CLI seja compatível com a versão atual da CLI. Por exemplo:
```
upgrades: .
```

`warnOnImplicitThis`

Opcional. O padrão será definido como false se a propriedade warnOnImplicitThis não for definida.
Define um booliano que especifica se o compilador deve ou não emitir avisos sobre chamadas de predicado de membro com receptores de chamada this implícitos, ou seja, sem um receptor explícito. Disponível desde CodeQL CLI versão v2.13.2. Por exemplo:
```
warnOnImplicitThis: true
```

`codeql-pack.lock.yml` arquivos

arquivos codeql-pack.lock.yml armazenam as versões das dependências transitivas resolvidas de um pacote 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 deve estar disponível no mesmo espaço de trabalho CodeQL que o pacote. Para obter mais informações sobre os espaços de trabalho CodeQL e como resolver dependências a partir do código-fonte, consulte 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.

Exemplo de pacotes personalizados CodeQL

Você deve salvar arquivos para consultas e testes personalizados em pacotes separados e organizar pacotes personalizados em pastas específicas para cada idioma de destino.

CodeQL pacotes para bibliotecas personalizadas

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

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

onde codeql/cpp-all está o nome do CodeQL pacote para análise C/C++ incluído no CodeQL repositório. 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 CodeQL arquivo de biblioteca (um arquivo com uma .qll extensão) definido neste pacote estará disponível para consultas definidas em qualquer pacote de consultas que inclua esse pacote em seu bloco de dependências.

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

CodeQL pacotes para consultas personalizadas

Um pacote personalizado CodeQL que contém consultas e bibliotecas C++ personalizadas pode ter um qlpack.yml arquivo 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

onde codeql/cpp-all está o nome do CodeQL pacote para análise C/C++ incluído no CodeQL repositório. 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 CodeQL pacote que contém bibliotecas personalizadas CodeQL para C++. Qualquer CodeQL arquivo de biblioteca (um arquivo com uma .qll extensão) definido neste pacote estará disponível para consultas no my-github-user/my-custom-queries pacote.

CodeQL pacotes para testes personalizados

Para pacotes personalizados CodeQL que contêm arquivos de teste, você também precisa incluir uma extractor propriedade para que o test run comando 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-kotlin
tests: .

Para obter mais informações sobre como executar testes, confira Testar consultas personalizadas.

Pacotes de exemplo CodeQL no CodeQL repositório

Cada um dos idiomas no CodeQL repositório tem quatro pacotes principais CodeQL :

Pacote da biblioteca principal para a linguagem, com o esquema do banco de dados usado pela linguagem, e bibliotecas em CodeQL, e consultas 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 CodeQL CLI e devem ser definidas apenas no pacote de consultas principal CodeQL de um idioma.

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 da origem, não importa com qual versão do CodeQL pacote 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 do pacote principal 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 dos principais CodeQL pacotes de consulta e 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.

Quem pode usar esse recurso?

Neste artigo

CodeQL Compatibilidade do pacote

`qlpack.yml` arquivos

`qlpack.yml` propriedades

`name`

`version`

`dataExtensions`

`dependencies`

`defaultSuiteFile`

`defaultSuite`

`extensionTargets`

`groups`

`library`

`suites`

`tests`

`extractor`

`authors`

`license`

`description`

`libraryPathDependencies`

`dbscheme`

`upgrades`

`warnOnImplicitThis`

`codeql-pack.lock.yml` arquivos

Exemplo de pacotes personalizados CodeQL

CodeQL pacotes para bibliotecas personalizadas

CodeQL pacotes para consultas personalizadas

CodeQL pacotes para testes personalizados

Pacotes de exemplo CodeQL no CodeQL repositório

Pacote de biblioteca principal

Pacote de consultas principal

Testes do pacote principal CodeQL