Skip to main content

Como criar e trabalhar com pacotes do CodeQL

Você pode usar pacotes do CodeQL para criar, compartilhar, criar dependências e executar consultas e bibliotecas do CodeQL.

Quem pode usar esse recurso?

O CodeQL do GitHub é licenciado por usuário após a instalação. Você pode usar o CodeQL somente para determinadas tarefas sob as restrições de licença. Para obter mais informações, confira "Sobre a CLI do CodeQL".

Se você tiver uma licença do GitHub Advanced Security, poderá usar o CodeQL para análise automatizada, integração contínua e entrega contínua. Para obter mais informações, confira "Sobre a Segurança Avançada do GitHub".

Observação: a funcionalidade de gerenciamento de pacote do CodeQL, incluindo pacotes do CodeQL, está em versão beta no momento e sujeita a alterações. Durante a versão beta, os pacotes CodeQL estão disponíveis apenas usando pacotes GitHub – o Container registry. Para usar essa funcionalidade beta, instale a versão mais recente do pacote da CodeQL CLI de: https://github.com/github/codeql-action/releases.

Sobre os pacotes do CodeQL e a CodeQL CLI

Os pacotes do CodeQL são usados para criar, compartilhar, gerar dependência e executar consultas e bibliotecas do CodeQL. Os pacotes do CodeQL contêm consultas, arquivos de biblioteca, conjuntos de consultas e metadados. Com os pacotes do CodeQL e os comandos de gerenciamento de pacotes na CodeQL CLI, você pode publicar as consultas personalizadas e integrá-las à análise de base de código.

Existem três tipos de pacotes do CodeQL: pacotes de consultas, pacotes de bibliotecas e pacotes de modelos.

  • Os pacotes de consultas foram projetados para serem executados. Quando um pacote de consultas é publicado, ele inclui todas as dependências transitivas e representações pré-compiladas de cada consulta, além das fontes de consulta. Isso garante a execução consistente e eficiente das consultas no pacote.

  • Os pacotes de biblioteca são projetados para serem usados por pacotes de consultas (ou outros pacotes de biblioteca) e não contêm consultas. As bibliotecas não são compiladas separadamente.

  • Pacotes de modelos podem ser usados para expandir análises do code scanning para incluir dependências para as quais não há suporte por padrão. Pacotes de modelos estão atualmente em versão beta e sujeitos a alterações. Durante o beta, pacotes de modelo estão disponíveis para análise Java no nível do repositório. Para obter mais informações sobre como criar seus próprios pacotes de modelos, consulte "Criação de um pacote de modelo CodeQL."

Você pode usar o comando pack na CodeQL CLI para criar pacotes do CodeQL, adicionar dependências a pacotes e instalar ou atualizar dependências. Você também pode publicar e baixar pacotes do CodeQL usando o comando pack. Para obter mais informações, confira "Publicar e usar pacotes do CodeQL".

Para obter mais informações sobre a compatibilidade entre os pacotes de consultas publicados e as diferentes versões do CodeQL, confira "Publicar e usar pacotes do CodeQL".

Os pacotes padrão do CodeQL para todas as linguagens com suporte são publicados no Container registry. O repositório do CodeQL contém arquivos de origem dos pacotes padrão do CodeQL para todas as linguagens com suporte. Os principais pacotes de consulta, que estão incluídos no pacote da CodeQL CLI, mas que você pode baixar de outra forma, são:

  • codeql/cpp-queries
  • codeql/csharp-queries
  • codeql/go-queries
  • codeql/java-queries
  • codeql/javascript-queries
  • codeql/python-queries
  • codeql/ruby-queries

Estrutura de pacotes do CodeQL

Um pacote do CodeQL precisa conter um arquivo chamado qlpack.yml no diretório raiz. No arquivo qlpack.yml, o campo name: precisa ter um valor que siga o formato <scope>/<pack>, em que <scope> é a organização ou a conta de usuário do GitHub em que o pacote será publicado e <pack> é o nome do pacote. Além disso, pacotes de consultas e pacotes de biblioteca com testes do CodeQL contêm um arquivo codeql-pack.lock.yml com as dependências resolvidas do pacote. Esse arquivo é gerado durante uma chamada ao comando codeql pack install, não deve ser editado manualmente e deve ser adicionado ao sistema de controle de versão.

Os outros arquivos e diretórios no pacote devem ser organizados logicamente. Por exemplo, normalmente:

  • As consultas são organizadas em diretórios para categorias específicas.

  • As consultas para produtos, bibliotecas e estruturas específicas são organizadas em seus próprios diretórios de nível superior.

Como criar um pacote do CodeQL

Você pode criar um pacote do CodeQL executando o seguinte comando na raiz de check-out do projeto:

codeql pack init <scope>/<pack>

É preciso especificar:

  • <scope>: o nome da organização do GitHub ou da conta de usuário de destino da publicação.

  • <pack>: o nome do pacote que você está criando.

O comando codeql pack init cria a estrutura de diretório e os arquivos de configuração de um pacote do CodeQL. Por padrão, o comando cria um pacote de consultas. Se você quiser criar um pacote de biblioteca, edite o arquivo qlpack.yml para declará-lo explicitamente como um pacote de biblioteca, incluindo a propriedade library:true.

Como criar um pacote de modelos CodeQL

Observação: pacotes de modelos estão atualmente em versão beta e sujeitos a alterações. Durante a versão beta, os pacotes de modelos são compatíveis apenas com análises Java.

Pacotes de modelos podem ser usados para expandir análises do code scanning para reconhecer bibliotecas e estruturas para as quais não há suporte por padrão. Os pacotes de modelos usam extensões de dados, que são implementadas como YAML e descrevem como adicionar dados para novas dependências. Quando um pacote de modelos é especificado, as extensões de dados nesse pacote serão adicionadas às análises do code scanning automaticamente. Para obter mais informações sobre extensões de dados e pacotes de modelos do CodeQL, consulte Usando o editor de modelos do CodeQL, na documentação do CodeQL.

Um pacote de modelos é um pacote de dados do CodeQL com as seguintes características no arquivo qlpack.yml:

  • Ele define library: true.
  • Ele não tem dependências.
  • Ele tem um ou mais extensionTargets.
  • Ele tem uma propriedade dataExtensions que aponta para um ou mais arquivos de extensão de dados.

Um pacote de modelos injetará suas extensões de dados especificadas em cada pacote de consultas nomeado em extensionTargets, se ele estiver dentro do intervalo de versões especificado. Por exemplo:

name: my-repo/my-java-model-pack
version: 1.2.3
extensionTargets:
  codeql/java-all: ~1.2.3
  codeql/util: ~4.5.6
dataExtensions:
  - models/**/*.yml

Neste exemplo, o pacote de modelos injetará todas as extensões de dados em models/**/ em um pacote de consultas codeql/java-all que está em uma versão de 1.2.3 até e incluindo 1.3.0, e um pacote de consultas codeql/util que está em uma versão de 4.5.6 até e incluindo 4.6.0. Para obter mais informações, confira "Usando o controle de versão semântico" na documentação do npm e "Especificação de controle de versão semântico".

Depois de criar um pacote de modelos, você pode publicá-lo da mesma forma que outros pacotes do CodeQL. Para obter mais informações, confira "Publicar e usar pacotes do CodeQL". Em seguida, pode usar pacotes de modelos publicados em uma análise do code scanning com a opção --model-packs. Para obter mais informações, confira "Como personalizar a análise com pacotes CodeQL".

Modificando um pacote QL herdado existente para criar um pacote de consultas do CodeQL

Se você já tiver um arquivo qlpack.yml, edite-o manualmente para convertê-lo em um pacote do CodeQL.

  1. Edite a propriedade name para que ela corresponda ao formato <scope>/<name>, em que <scope> é o nome da organização do GitHub ou da conta de usuário de destino da publicação.

  2. No arquivo qlpack.yml, inclua uma propriedade version com um identificador semver, bem como um bloco opcional dependencies.

  3. Migre a lista de dependências no libraryPathDependencies para o bloco dependencies. Especifique o intervalo de versão de cada dependência. Se o intervalo não for importante ou você não tiver certeza da compatibilidade, especifique "\*" para indicar que qualquer versão é aceitável e o padrão será a mais recente quando codeql pack install for executado.

Para obter mais informações sobre as propriedades, confira "Como personalizar a análise com pacotes CodeQL".

Adicionando e instalando dependências em um pacote do CodeQL

Observação: isso apenas tem suporte para pacotes de consultas e bibliotecas do CodeQL.

Você pode adicionar dependências em pacotes do CodeQL usando o comando codeql pack add. Você precisa especificar o escopo, o nome e (opcionalmente) um intervalo de versão compatível.

codeql pack add <scope>/<name>@x.x.x <scope>/<other-name>

Se você não especificar um intervalo de versão, a versão mais recente será adicionada. Caso contrário, a versão mais recente que atenda ao intervalo solicitado será adicionada.

Esse comando atualiza o arquivo qlpack.yml com as dependências solicitadas e as baixa no cache de pacote. Observe que esse comando reformatará o arquivo e removerá todos os comentários.

Você também pode editar manualmente o arquivo qlpack.yml para incluir dependências e instalá-las com o comando:

codeql pack install

Esse comando baixa todas as dependências no cache compartilhado no disco local.

Observações:

  • A execução dos comandos codeql pack add e codeql pack install vai gerar ou atualizar o arquivo codeql-pack.lock.yml. O check-in desse arquivo deve ser feito no controle de versão. O arquivo codeql-pack.lock.yml contém os números de versão precisos usados pelo pacote. Para obter mais informações, confira "Sobre os arquivos codeql-pack.lock.yml".

  • Por padrão, codeql pack install instalará as dependências do Container registry no GitHub.com. Você pode instalar as dependências de um Container registry do GitHub Enterprise Server criando um arquivo qlconfig.yml. Para obter mais informações, consulte "Publicar e usar pacotes do CodeQL" na documentação do GitHub Enterprise Server.

Como personalizar um pacote do CodeQL baixado

A maneira recomendada de experimentar as alterações em um pacote é clonar o repositório que contém o código-fonte.

Se nenhum repositório de origem estiver disponível e você precisar basear as modificações em um pacote baixado do Container registry, lembre-se de que esses pacotes não devem ser modificados nem personalizados após o download e o formato pode mudar no futuro sem aviso prévio. Recomendamos executar as seguintes etapas depois de baixar um pacote se você precisar modificar o conteúdo:

  • Altere o nome do pacote em qlpack.yml para evitar confusão com os resultados do pacote não modificado.

  • Remova todos os arquivos chamados *.qlx em qualquer lugar na estrutura de diretório descompactada. Esses arquivos contêm versões pré-compiladas das consultas e, em algumas situações, o CodeQL os usará em preferência à fonte QL que você modificou.