Publicar e usar pacotes do CodeQL

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>
default-suite: # optional, one or more queries in the pack to run by default
    - query: <relative-path>/query-file>.ql
default-suite-file: 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 /, em que é a organização do GitHub de destino da publicação e é o nome do pacote.

• É permitido no máximo um default-suite ou um default-suite-file. 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.

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 específico de um pacote de consultas a ser baixado, lembre-se de que, ao atualizar 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 obter mais informações, 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>

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 exceção do indicado acima, os pacotes publicados com versões do CodeQL anteriores à 2.12.0 não são compatíveis com versões anteriores ou posteriores. Essas versões antigas não gravavam consultas pré-compiladas em um formato com suporte à compatibilidade entre versões. Os pacotes publicados por essas versões ainda podem ser usados por versões mais recentes, mas a análise será mais lenta porque as consultas precisam ser recompiladas primeiro.

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 da CLI do CodeQL 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.

Autenticação no GitHub Container registries

Você pode publicar pacotes e baixar pacotes privados se autenticando no Container registry do GitHub.

Você pode se autenticar no Container registry no GitHub.com de duas maneiras:

1. 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.
2. Defina a variável de ambiente GITHUB_TOKEN como um token do GitHub Apps ou um personal access token.