Publicar e usar pacotes do CodeQL

Trabalhando com CodeQL pacotes em GitHub Enterprise Server

Por padrão, a CodeQL CLI espera baixar pacotes CodeQL e publicar pacotes no Container registry no GitHub.com. No entanto, você também pode trabalhar com CodeQL pacotes em um ambiente Container registryGitHub Enterprise Server criando um arquivo qlconfig.yml para informar à CLI qual Container registry usar para cada pacote.

Crie um arquivo ~/.codeql/qlconfig.yml no Linux/MacOS ou %HOMEPATH%\.codeql\qlconfig.yml em Windows usando seu editor de texto preferencial e adicione entradas para especificar qual registro usar para um ou mais padrões de nome de pacote. Por exemplo, o arquivo a seguir qlconfig.yml associa todos os pacotes com o Container registry em https://GHE_HOSTNAME, exceto os pacotes que correspondem a codeql/\* ou à organização other-org/*, que estão associados com o Container registry em GitHub.com:

registries:
- packages:
  - 'codeql/*'
  - 'other-org/*'
  # Container registry on GitHub.com
  url: https://ghcr.io/v2/
- packages: '*'
  # Container registry hosted at `https://GHE_HOSTNAME`
  url: https://containers.GHE_HOSTNAME/v2/

Ele CodeQL CLI determinará qual registro usar para um determinado nome de pacote localizando o primeiro item na registries lista com uma packages propriedade que coincide com 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 possam ser compartilhados entre outros CodeQL usuários 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 em GitHub Enterprise Server.

Autenticando em GitHubContainer registries

Você pode publicar pacotes e baixar pacotes privados autenticando-se no apropriado GitHubContainer registry.

Autenticando em Container registries no GitHub.com

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

1. Passe a opção --github-auth-stdin para o CodeQL CLI, então forneça um token GitHub Apps ou personal access token por meio de entrada padrão.
2. Defina a variável de ambiente GITHUB_TOKEN como um token GitHub Apps ou personal access token.

Autenticando em Container registries no GitHub Enterprise Server

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

1. Passe a opção --registries-auth-stdin para o CodeQL CLI e forneça uma cadeia de caracteres de autenticação do registro por meio da 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 do Registro é uma lista separada por vírgulas de <registry-url>=<token> pares, onde registry-url é uma Container registry URL, como https://containers.GHE_HOSTNAME/v2/, e token é um GitHub Apps token ou personal access token para esse Container registry. Isso garante que cada token seja passado apenas para o Container registry especificado.

Por exemplo, a seguinte cadeia de caracteres de autenticação do Registro especifica que o CodeQL CLI deve ser autenticado da seguinte maneira:

• Use o token <token1> para autenticar Container registry em GitHub.com.
• Use o token <token2> para autenticar para a Container registry empresa em https://containers.GHE_HOSTNAME/v2/.

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

Publicando seu CodeQL pacote

Para compartilhar seu CodeQL pacote com outras pessoas, você pode publicá-lo no Container registry.

Como configurar o arquivo qlpack.yml antes da publicação

Você pode verificar e modificar os detalhes de configuração do pacote 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:` deve seguir o `<scope>/<pack>` formato, onde `<scope>` está a GitHub organização na qual você publicará e `<pack>` é o nome do pacote.
  

• É permitido no máximo um defaultSuite ou um defaultSuiteFile. 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ção codeql pack publish

Quando estiver pronto para publicar um pacote no GitHubContainer registry, 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 GitHub, conforme especificado pelo escopo no arquivo qlpack.yml.

Baixando um pacote existente CodeQL

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 da GitHub qual você irá baixar.
  

•         `<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 especifique um número de versão específico de um pacote de consultas a ser baixado, tenha em mente que, ao atualizar sua 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. Versões mais recentes CodeQL_podem_ fornecer desempenho degradado quando usadas com pacotes de consulta que foram fixados em uma versão muito antiga. Para obter mais informações, consulte Referência de pacotes de consulta CodeQL.

Usando um CodeQL pacote para analisar um CodeQL banco de dados

Para analisar um CodeQL banco de dados com um CodeQL pacote, execute o seguinte comando:

codeql database analyze <database> <scope>/<pack>@x.x.x:<path>

•         `<database>`: o CodeQL banco de dados a ser analisado.
  

•         `<scope>`: o nome da GitHub organização 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 qualquer pacote especificado CodeQL. Você pode especificar vários CodeQL pacotes a serem usados para analisar um CodeQL banco de dados. Por exemplo:

codeql <database> analyze <scope>/<pack> <scope>/<other-pack>