Publicar e usar pacotes do CodeQL

Compartilhe ou baixe um CodeQL pacote e analise seu CodeQL banco de dados.

Quem pode usar esse recurso?

O CodeQL está disponível para os seguintes tipos de repositórios:

Neste artigo

Autenticando em GitHubContainer registries

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

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.

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.

Observação

Se você estiver publicando pacotes de modelo para o GitHubContainer registry a fim de estender a cobertura a todos os repositórios em uma organização como parte de uma configuração padrão, precisará garantir que os repositórios que executam o escaneamento de código possam acessar esses pacotes de modelos. Para obter mais informações, consulte Editar as definições da configuração padrão e Configurando o controle de acesso e visibilidade de um pacote.

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>

Observação

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.