Como criar e trabalhar com pacotes do CodeQL

Sobre CodeQL pacotes e o CodeQL CLI

          CodeQL os pacotes são usados para criar, compartilhar, depender e executar CodeQL consultas e bibliotecas.

Você pode usar o comando pack no CodeQL CLI para criar pacotes CodeQL, adicionar dependências a pacotes e instalar ou atualizar dependências. Você também pode publicar e baixar CodeQL pacotes usando o pack comando.

Criando um CodeQL pacote

Você pode criar um CodeQL pacote executando o seguinte comando na pasta raiz do checkout do seu projeto:

codeql pack init <scope>/<pack>

É preciso especificar:

•         `<scope>`: o nome da GitHub organização ou da conta de usuário na qual você publicará.
  

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

O codeql pack init comando cria a estrutura de diretório e os arquivos de configuração para um CodeQL pacote. 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.

Criando um CodeQL pacote de modelos

Os pacotes de modelos podem ser usados para expandir code scanning a análise para reconhecer bibliotecas e estruturas que não têm 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 à code scanning análise automaticamente. Para obter mais informações sobre CodeQL pacotes de modelos e extensões de dados, consulte Usar o editor de modelos do CodeQL.

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

• 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, consulte Usando versionamento semântico na documentação do npm e a Especificação de versionamento semântico.

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

Adicionando e instalando dependências em um CodeQL pacote

Você pode adicionar dependências em CodeQL pacotes 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.

Organizando a estrutura de diretório de um CodeQL pacote

Um CodeQL pacote deve conter um arquivo chamado qlpack.yml em seu diretório raiz. No arquivo qlpack.yml, o campo name: deve ter um valor que siga o formato de <scope>/<pack>, onde <scope> é a organização ou a conta de usuário GitHub em que o pacote será publicado e <pack> é o nome do pacote.

Além disso, pacotes de consulta e pacotes de biblioteca que incluem CodeQL testes contêm um arquivo codeql-pack.lock.yml que lista 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.

Personalizando um pacote baixado CodeQL

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 Container registry estiver disponível e você precisar basear as modificações em um pacote baixado de uma fonte, lembre-se de que esses pacotes não devem ser modificados ou personalizados após o download, e seu formato poderá mudar no futuro sem muito 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 CodeQL , as usarão em preferência à fonte QL que você modificou.