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.

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>

Como trabalhar cm pacotes do CodeQL no GitHub Enterprise Server

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 Server criando um arquivo qlconfig.yml para informar à CLI qual Container registry usar para cada pacote.

Crie um arquivo ~/.codeql/qlconfig.yml usando seu editor de texto preferido e adicione entradas para especificar qual registro usar para um ou mais padrões de nome de pacote. Por exemplo, o arquivo qlconfig.yml a seguir associa todos os pacotes ao Container registry para o GitHub Enterprise Server em GHE_HOSTNAME, exceto os pacotes correspondentes a codeql/\*, que estão associados ao Container registry no GitHub.com:

registries:
- packages:
  - 'codeql/*'
  - 'other-org/*'
  url: https://ghcr.io/v2/
- packages: '*'
  url: https://containers.GHE_HOSTNAME/v2/

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 Server.

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.

Da mesma forma, você pode se autenticar em um Container registry do GitHub Enterprise Server ou em vários registros simultaneamente (por exemplo, para baixar ou executar pacotes privados de vários registros) de duas maneiras:

1. 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.
2. 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írgulas, em que registry-url é uma URL de Container registry, como https://containers.GHE_HOSTNAME/v2/, e token é um token do GitHub Apps ou um personal access token desse Container registry do GitHub. Isso garante que cada token seja passado apenas para o Container registry que você especifica. Por exemplo, a cadeia de caracteres de autenticação do registro a seguir especifica que a CodeQL CLI deve se autenticar no Container registry no GitHub.com usando o token <token1> e no Container registry da instância do GHES em GHE_HOSTNAME usando o token <token2>:

https://ghcr.io/v2/=<token1>,https://containers.GHE_HOSTNAME/v2/=<token2>