{"meta":{"title":"Como criar e trabalhar com pacotes do CodeQL","intro":"Você pode usar CodeQL pacotes para criar, compartilhar, depender e executar CodeQL consultas e bibliotecas.","product":"Qualidade de segurança e código","breadcrumbs":[{"href":"/pt/code-security","title":"Qualidade de segurança e código"},{"href":"/pt/code-security/tutorials","title":"Tutorials"},{"href":"/pt/code-security/tutorials/customize-code-scanning","title":"Personalizar a verificação de código"},{"href":"/pt/code-security/tutorials/customize-code-scanning/creating-and-working-with-codeql-packs","title":"Como criar e trabalhar com pacotes do CodeQL"}],"documentType":"article"},"body":"# Como criar e trabalhar com pacotes do CodeQL\n\nVocê pode usar CodeQL pacotes para criar, compartilhar, depender e executar CodeQL consultas e bibliotecas.\n\n## Sobre CodeQL pacotes e o CodeQL CLI\n\n```\n          CodeQL os pacotes são usados para criar, compartilhar, depender e executar CodeQL consultas e bibliotecas.\n```\n\nVocê 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.\n\n## Criando um CodeQL pacote\n\nVocê pode criar um CodeQL pacote executando o seguinte comando na pasta raiz do checkout do seu projeto:\n\n```shell\ncodeql pack init <scope>/<pack>\n```\n\nÉ preciso especificar:\n\n* `<scope>`: o nome da GitHub organização ou da conta de usuário na qual você publicará.\n\n* `<pack>`: o nome do pacote que você está criando.\n\nO `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`.\n\n## Criando um CodeQL pacote de modelos\n\n> \\[!NOTE]\n> 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.\n>\n> 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.\n\nOs 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).\n\nUm pacote de modelos é um CodeQL pacote com as seguintes características no `qlpack.yml` arquivo:\n\n* Ele define `library: true`.\n* Ele não tem dependências.\n* Ele tem um ou mais `extensionTargets`.\n* Ele tem uma propriedade `dataExtensions` que aponta para um ou mais arquivos de extensão de dados.\n\nUm 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:\n\n```yaml\nname: my-repo/my-java-model-pack\nversion: 1.2.3\nextensionTargets:\n  codeql/java-all: ~1.2.3\n  codeql/util: ~4.5.6\ndataExtensions:\n  - models/**/*.yml\n```\n\nNeste 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/).\n\nDepois 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).\n\n## Adicionando e instalando dependências em um CodeQL pacote\n\n> \\[!NOTE]\n> Isso só tem suporte para CodeQL pacotes de consulta e biblioteca.\n\nVocê 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.\n\n```shell\ncodeql pack add <scope>/<name>@x.x.x <scope>/<other-name>\n```\n\nSe 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.\n\nEsse 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.\n\nVocê também pode editar manualmente o arquivo `qlpack.yml` para incluir dependências e instalá-las com o comando:\n\n```shell\ncodeql pack install\n```\n\nEsse comando baixa todas as dependências no cache compartilhado no disco local.\n\n> \\[!NOTE]\n>\n> * 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).\n> * 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.\n\n## Organizando a estrutura de diretório de um CodeQL pacote\n\nUm 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.\n\nAlé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.\n\nOs outros arquivos e diretórios no pacote devem ser organizados logicamente. Por exemplo, normalmente:\n\n* As consultas são organizadas em diretórios para categorias específicas.\n* As consultas para produtos, bibliotecas e estruturas específicas são organizadas em seus próprios diretórios de nível superior.\n\n## Personalizando um pacote baixado CodeQL\n\nA maneira recomendada de experimentar as alterações em um pacote é clonar o repositório que contém o código-fonte.\n\nSe 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:\n\n* Altere o *nome* do pacote em `qlpack.yml` para evitar confusão com os resultados do pacote não modificado.\n\n* 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."}