Como trabalhar com pacotes do CodeQL no GitHub Enterprise Cloud com residência de dados
Por padrão, o CodeQL CLI espera baixar pacotes do CodeQL e publicá-los no Container registry no GitHub.com. No entanto, você também pode trabalhar com pacotes do CodeQL em um Container registry no GitHub Enterprise Cloud com residência de dados criando um arquivo qlconfig.yml
para instruir a CLI sobre o Container registry que será usado para cada pacote.
Crie um arquivo ~/.codeql/qlconfig.yml
no Linux/macOS ou %HOMEPATH%\.codeql\qlconfig.yml
no Windows usando seu editor de texto preferido e adicione entradas para especificar o registro que será usado para um ou mais padrões de nomes de pacotes.
Por exemplo, o seguinte arquivo qlconfig.yml
associa todos os pacotes ao Container registry no SUBDOMAIN.ghe.com
, exceto os pacotes correspondentes a codeql/\*
ou à organização other-org/*
, que estão associados ao Container registry no GitHub.com:
registries:
- packages:
- 'codeql/*'
- 'other-org/*'
# Container registry on GitHub.com
url: https://ghcr.io/v2/
- packages: '*'
# Container registry hosted at `SUBDOMAIN.ghe.com`
url: https://containers.SUBDOMAIN.ghe.com
A CodeQL CLI determinará qual registro usar para um determinado nome de pacote localizando o primeiro item na lista registries
com uma propriedade packages
que corresponda a esse nome de pacote.
Isso significa que é melhor definir os padrões de nome de pacote mais específicos primeiro. A propriedade packages
pode ser um só nome de pacote, um padrão glob ou uma lista YAML de nomes de pacote e padrões glob.
A lista registries
também pode ser colocada dentro de um arquivo codeql-workspace.yml
. Isso permitirá que você defina os registros a serem usados em um workspace específico, para que eles possam ser compartilhados entre outros usuários do CodeQL do workspace. A lista registries
no codeql-workspace.yml
será mesclada e terá precedência sobre a lista no qlconfig.yml
global. Para obter mais informações sobre codeql-workspace.yml
, confira Sobre os workspaces do CodeQL.
Agora você pode usar codeql pack publish
, codeql pack download
e codeql database analyze
para gerenciar pacotes no GitHub Enterprise Cloud com residência de dados.
Como se autenticar nos Container registries do GitHub
Você pode publicar pacotes e baixar pacotes privados autenticando-se no Container registry apropriado do GitHub.
Como se autenticar nos Container registries do GitHub.com
Você pode se autenticar no Container registry de duas maneiras:
- Passe a opção
--github-auth-stdin
para a CodeQL CLI e forneça um token do GitHub Apps ou um personal access token por meio de entrada padrão. - Defina a variável de ambiente
GITHUB_TOKEN
como um token do GitHub Apps ou um personal access token.
Como se autenticar nos Container registries no GitHub Enterprise Cloud com residência de dados
Da mesma forma, você pode se autenticar em um Container registry do GitHub Enterprise Cloud com residência de dados ou em vários registros simultaneamente (por exemplo, para baixar ou executar pacotes privados de vários registros) de duas maneiras:
- Passe a opção
--registries-auth-stdin
para a CodeQL CLI e forneça uma cadeia de caracteres de autenticação do registro por meio de entrada padrão. - Defina a variável de ambiente
CODEQL_REGISTRIES_AUTH
como uma cadeia de caracteres de autenticação do registro.
Uma cadeia de caracteres de autenticação de registro é uma lista de pares de <registry-url>=<token>
separados por vírgula, em que registry-url
é uma URL do Container registry, como https://containers.SUBDOMAIN.ghe.com
, e token
é um token do GitHub Apps ou um personal access token desse Container registry.
Isso garante que cada token seja passado apenas para o Container registry que você especifica.
Por exemplo, a seguinte cadeia de caracteres de autenticação do registro especifica que a CodeQL CLI deve ser autenticada da seguinte maneira:
- Use o token
<token1>
para se autenticar no Container registry no GitHub.com. - Use o token
<token2>
para se autenticar no Container registry da empresa nohttps://containers.SUBDOMAIN.ghe.com
.
https://ghcr.io/v2/=<token1>,https://containers.SUBDOMAIN.ghe.com=<token2>
Como configurar o arquivo qlpack.yml
antes da publicação
Você pode verificar e modificar os detalhes de configuração do pacote do CodeQL antes da publicação. Abra o arquivo qlpack.yml
em seu editor de texto preferido.
library: # set to true if the pack is a library. Set to false or omit for a query pack
name: <scope>/<pack>
version: <x.x.x>
description: <Description to publish with the package>
defaultSuite: # optional, one or more queries in the pack to run by default
- query: <relative-path>/query-file>.ql
defaultSuiteFile: default-queries.qls # optional, a pointer to a query-suite in this pack
license: # optional, the license under which the pack is published
dependencies: # map from CodeQL pack name to version range
-
name:
precisa seguir o formato<scope>/<pack>
, em que<scope>
é a organização do GitHub de destino da publicação e<pack>
é o nome do pacote. -
É permitido no máximo um
defaultSuite
ou umdefaultSuiteFile
. Essas são duas maneiras diferentes de definir um conjunto de consultas padrão a ser executado, a primeira especificando consultas diretamente no arquivo qlpack.yml e a segunda especificando um conjunto de consultas no pacote.
Em execuçãocodeql pack publish
Quando estiver pronto para publicar um pacote no Container registry do GitHub, você poderá executar o seguinte comando na raiz do diretório do pacote:
codeql pack publish
O pacote publicado será exibido na seção de pacotes da organização do GitHub especificada pelo escopo no arquivo qlpack.yml
.
Note
Se você estiver publicando pacotes de modelos no GitHub Container registry para estender a cobertura a todos os repositórios em uma organização como parte de uma configuração de instalação padrão, será necessário garantir que os repositórios que executam a verificação de código possam acessar esses pacotes de modelo. Para saber mais, confira Editar as definições da configuração padrão e Configurando o controle de acesso e visibilidade de um pacote.
Em execuçãocodeql pack download <scope>/<pack>
Para executar um pacote que outra pessoa criou, primeiro você precisa baixá-lo executando o seguinte comando:
codeql pack download <scope>/<pack>@x.x.x
<scope>
: o nome da organização do GitHub de origem do download.<pack>
: o nome do pacote que você quer baixar.@x.x.x
: um número de versão opcional. Se omitido, a versão mais recente será baixada.
Esse comando aceita argumentos para vários pacotes.
Se você escrever scripts que especifiquem um número de versão determinado de um pacote de consultas a ser baixado, lembre-se de que, ao atualizar a versão CodeQL para uma versão mais recente, talvez você também precise mudar para uma versão mais recente do pacote de consultas. As versões mais recentes do CodeQL podem apresentar degradação do desempenho quando usadas com pacotes de consultas fixados em uma versão muito antiga. Para saber mais, confira Sobre a compatibilidade de pacotes do CodeQL.
Como usar um pacote do CodeQL para analisar um banco de dados do CodeQL
Para analisar um banco de dados do CodeQL com um pacote do CodeQL, execute o seguinte comando:
codeql database analyze <database> <scope>/<pack>@x.x.x:<path>
<database>
: o banco de dados do CodeQL a ser analisado.<scope>
: o nome da organização do GitHub na qual o pacote foi publicado.<pack>
: o nome do pacote que você está usando.@x.x.x
: um número de versão opcional. Se omitido, a versão mais recente será usada.:<path>
: um caminho opcional para uma consulta, um diretório ou um pacote de consultas. Se omitido, o conjunto de consultas padrão do pacote será usado.
O comando analyze
executará o conjunto padrão de todos os pacotes do CodeQL especificados. Você pode especificar vários pacotes do CodeQL a serem usados para analisar um banco de dados do CodeQL. Por exemplo:
codeql <database> analyze <scope>/<pack> <scope>/<other-pack>
Note
O comando codeql pack download
armazena o pacote baixado em um local interno que não se destina à modificação local. Um comportamento inesperado (e difícil de solucionar) poderá ocorrer se o pacote for modificado após o download. Para obter mais informações sobre pacotes de personalização, confira Como criar e trabalhar com pacotes do CodeQL.
Sobre a compatibilidade de pacotes do CodeQL
Quando um pacote de consultas é publicado, ele inclui representações pré-compiladas de todas as consultas que contém. É mais rápido executar essas consultas pré-compiladas do que compilar a fonte QL do zero durante a análise. No entanto, as consultas pré-compiladas também dependem de certos recursos internos do avaliador de QL, portanto, se a versão do CodeQL que executa a análise for muito diferente da versão que executou codeql pack publish
, poderá ser necessário compilar as consultas da fonte durante a análise. A recompilação ocorre automaticamente e não afeta os resultados da análise, mas aumentar significativamente a lentidão da análise.
Geralmente, supõe-se que quando um pacote é publicado com uma versão do CodeQL, as consultas pré-compiladas nele podem ser usadas diretamente por versões posteriores do CodeQL, desde que não haja mais de seis meses entre as datas de lançamento. Faremos esforços significativos para manter as novas versões compatíveis por mais tempo, mas não podemos prometer isso.
Também é possível supor que um pacote publicado pela última versão pública do CodeQL seja usado pela versão do CodeQL que é usada pela code scanning e pelo GitHub Actions, mesmo que seja uma versão um pouco mais antiga.
Como usuário de um pacote de consultas publicado, você pode verificar se o CodeQL usa as consultas pré-compiladas que contém inspecionando a saída do terminal de uma execução de análise que usa o pacote de consultas. Se ele contiver linhas semelhantes às seguintes, as consultas pré-compiladas terão sido usadas com êxito:
[42/108] Loaded /long/path/to/query/Filename.qlx.
No entanto, se elas forem semelhantes às seguintes, o uso das consultas pré-compiladas terá falhado:
Compiling query plan for /long/path/to/query/Filename.ql.
[42/108 comp 25s] Compiled /long/path/to/query/Filename.ql.
Os resultados da análise ainda serão bons nesse caso, mas para obter o desempenho ideal, talvez seja necessário atualizar para uma versão mais recente do CodeQL CLI e/ou do pacote de consultas.
Se você publicar pacotes de consultas no Container registry no GitHub.com para outras pessoas usarem, recomendamos o uso de uma versão recente do CodeQL para executar codeql pack publish
e a publicação de uma nova versão do pacote com uma versão atualizada do CodeQL antes que a versão usada fique com seis meses. Dessa forma, você pode garantir que os usuários do pacote que mantêm o próprio CodeQL atualizado se beneficiem das consultas pré-compiladas no pacote.
Se você publicar pacotes de consultas com a intenção de usá-los em uma instalação do GitHub Enterprise Server que usa os binários agrupados do CodeQL, use a mesma versão do CodeQL para executar codeql pack publish
. Versões mais recentes podem produzir consultas pré-compiladas que talvez não sejam reconhecidas por aquela que o GitHub Enterprise Server contém. O administrador do GitHub Enterprise Server pode optar por atualizar para uma versão mais recente do CodeQL periodicamente. Nesse caso, siga a orientação dele.
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
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
-
Exigido por pacotes de consultas e bibliotecas que definem as dependências de pacote do CodeQL em 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. Compatível com a 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 espaço reservado de versão especial,
${workspace}
, que indica que esse pacote do CodeQL depende de qualquer versão da dependência no mesmo espaço de trabalho. Para saber mais, confira Sobre os 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 definirdefaultSuiteFile
oudefaultSuite
. 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 definirdefaultSuiteFile
oudefaultSuite
. 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 espaço de trabalho do CodeQL. 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
eexperimental
:groups: - java - experimental
A execução de
codeql pack publish --groups java,-experimental
publicará todos os pacotes no grupojava
, exceto os pacotesexperimental
. Você pode executar o comandocodeql pack ls --groups [-]<group>[,[-]<group>...]
para listar os pacotes em um espaço de trabalho que correspondem ao conjunto especificado de grupos.Um pacote do CodeQL no espaço de trabalho fornecido será 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 se
- 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 com suporte apenas para os pacotes de consulta padrão incluídos no pacote da CLI do CodeQL.
- Esta opção não tem suporte para pacotes do CodeQL baixados do registro de contêiner do GitHub.
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 quandotest run
é executado com a opção--strict-test-discovery
. Essas consultas são ignoradas por definições de conjunto de consultas que usam instruçõesqueries
ouqlpack
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 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 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: .
warnOnImplicitThis
-
Opcional. O padrão será definido como
false
se a propriedadewarnOnImplicitThis
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 v2.13.2. Por exemplo:warnOnImplicitThis: true
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.yml
conté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 saber mais, confira Como criar e trabalhar com 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 saber mais, 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
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
.
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-kotlin
tests: .
Para obter mais informações sobre como executar testes, confira 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
eupgrades
: essas propriedades são internas à CodeQL CLI e só devem ser definidas no pacote principal de consultas do CodeQL para 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 decodeql/cpp-all
ecodeql/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 propriedadeversion
para o pacote de testes. Isso impede que os pacotes de teste sejam publicados acidentalmente.