# Como criar e trabalhar com pacotes do CodeQL Você pode usar CodeQL pacotes para criar, compartilhar, depender e executar CodeQL consultas e bibliotecas. ## 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: ```shell codeql pack init / ``` É preciso especificar: * ``: o nome da GitHub organização ou da conta de usuário na qual você publicará. * ``: 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 > \[!NOTE] > Atualmente, os pacotes de modelo do CodeQL estão em versão prévia pública e estão sujeitos a alterações. Os pacotes de modelos são compatíveis com a análise do C/C++, C#, Java/Kotlin, Python, Ruby e Rust. > > O editor de modelos do CodeQL na extensão CodeQL para Visual Studio Code dá suporte a dependências de modelagem para C#, Java/Kotlin, Python e Ruby. 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](/pt/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor). 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: ```yaml 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](https://docs.npmjs.com/about-semantic-versioning#using-semantic-versioning-to-specify-update-types-your-package-can-accept) na documentação do npm e a [Especificação de versionamento semântico](https://semver.org/). 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](/pt/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs). 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](/pt/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#using-model-packs-to-analyze-calls-to-custom-dependencies). ## Adicionando e instalando dependências em um CodeQL pacote > \[!NOTE] > Isso só tem suporte para CodeQL pacotes de consulta e biblioteca. 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. ```shell codeql pack add /@x.x.x / ``` 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: ```shell codeql pack install ``` Esse comando baixa todas as dependências no cache compartilhado no disco local. > \[!NOTE] > > * 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, consulte [Sobre os arquivos codeql-pack.lock.yml](/pt/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs##about-codeql-packlockyml-files). > * Por padrão, `codeql pack install` instalará dependências de Container registry em GitHub.com. Você pode instalar dependências de um GitHub Enterprise ServerContainer registry criando um `qlconfig.yml` arquivo. Para obter mais informações, consulte [Publicar e usar pacotes do CodeQL](/pt/enterprise-server@3.20/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs) na GitHub Enterprise Server documentação. ## 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 `/`, onde `` é a organização ou a conta de usuário GitHub em que o pacote será publicado e `` é 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.