# Como personalizar a análise com pacotes CodeQL

Você pode usar CodeQL pacotes para executar CodeQL consultas mantidas por outras pessoas ou para compartilhar CodeQL consultas que você desenvolveu.

Você pode personalizar sua CodeQL análise baixando pacotes criados por outras pessoas e executando-os em sua base de código. Para obter mais informações, consulte [Pacotes de consulta CodeQL](/pt/enterprise-server@3.19/code-security/concepts/code-scanning/codeql/codeql-query-packs).

## Baixar e usar CodeQL pacotes de consulta

Antes de usar um CodeQL pacote de consultas para analisar um banco de dados, você deve baixar todos os pacotes necessários.GitHubContainer registry Isso pode ser feito usando o sinalizador `--download` como parte do comando `codeql database analyze` ou executando `codeql pack download`. Se um pacote não estiver disponível ao público, você precisará usar um GitHub App ou personal access token para autenticar. Para obter mais informações e um exemplo, confira [Carregando resultados da análise do CodeQL para GitHub](/pt/enterprise-server@3.19/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github#uploading-results-to-github).

| Opção                                                                              |                                                                                                                                                                                                           Obrigatório                                                                                                                                                                                                          | Uso                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <code><span style="white-space: nowrap;">\<scope/name\@version:path></span></code> |                                                     <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-check" aria-label="Required" role="img"><path d="M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 0 1-1.06 0L2.22 9.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018L6 10.94l6.72-6.72a.75.75 0 0 1 1.06 0Z"></path></svg>                                                    | Especifique o escopo e o nome de um ou mais CodeQL pacotes de consulta a serem baixados usando uma lista separada por vírgulas. Opcionalmente, inclua a versão para fazer o download e descompactar. Por padrão, a versão mais recente deste pacote foi baixada. Opcionalmente, inclua um caminho para um conjunto de consultas, diretórios ou consultas a serem executadas. Se nenhum caminho for incluído, execute as consultas padrão deste pacote. |
| <code><span style="white-space: nowrap;">--github-auth-stdin</span></code>         | <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-x" aria-label="Optional" role="img"><path d="M3.72 3.72a.75.75 0 0 1 1.06 0L8 6.94l3.22-3.22a.749.749 0 0 1 1.275.326.749.749 0 0 1-.215.734L9.06 8l3.22 3.22a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L8 9.06l-3.22 3.22a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042L6.94 8 3.72 4.78a.75.75 0 0 1 0-1.06Z"></path></svg> | Passe a CLI, a GitHub App ou a personal access token criada para autenticação com a API REST de GitHub a partir do seu armazenamento de segredos, por meio de entrada padrão. Isso não será necessário se o comando tiver acesso a uma variável de ambiente `GITHUB_TOKEN` definida com esse token.                                                                                                                                                    |

> \[!NOTE]
> Se você especificar uma versão específica de um pacote de consultas para usar, lembre-se de que a versão que você especificar pode, com o tempo, ficar antiga demais para que a versão mais recente de CodeQL consiga usá-la com eficiência. Para garantir o desempenho ideal, se você precisar especificar versões exatas do pacote de consultas, deverá reavaliar quais versões fixar sempre que atualizar o CodeQL CLI que está usando.
>
> Para obter mais informações sobre a compatibilidade de pacotes, confira [Referência de pacotes de consulta CodeQL](/pt/enterprise-server@3.19/code-security/reference/code-scanning/codeql/codeql-cli/codeql-query-packs#codeql-pack-compatibility).

### Exemplo básico do download e uso de pacotes de consulta

Este exemplo executa o comando `codeql database analyze` com a opção `--download` para:

1. Baixar a versão mais recente do pacote `octo-org/security-queries`.
2. Baixar uma versão do pacote `octo-org/optional-security-queries` que seja *compatível* com a versão 1.0.1 (nesse caso, é a versão 1.0.2). Para obter mais informações sobre compatibilidade semver, confira a [documentação do intervalo de versão semântica do npm](https://github.com/npm/node-semver#ranges).
3. Execute todas as consultas padrão em `octo-org/security-queries`.
4. Executar somente a consulta `queries/csrf.ql` de `octo-org/optional-security-queries`

```shell
$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \
    octo-org/security-queries \
    octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/security-queries@1.0.0
> Installed fresh octo-org/optional-security-queries@1.0.2
> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> Starting evaluation of octo-org/security-queries/query1.ql.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql.
> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.
```

### Download direto de CodeQL pacotes

Se você quiser baixar um CodeQL pacote sem executá-lo imediatamente, poderá usar o `codeql pack download` comando. Isso é útil se você quiser evitar acessar a Internet ao executar CodeQL consultas. Ao executar a CodeQL análise, você pode especificar pacotes, versões e caminhos da mesma maneira que no exemplo anterior:

```shell
echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...
```

### CodeQL Baixar pacotes de vários GitHub registros de contêiner

Se os pacotes CodeQL estiverem em vários registros de contêineres, você deverá instruir o CodeQL CLI sobre onde encontrar cada pacote. Para obter mais informações, consulte [Opções de configuração de fluxo de trabalho para verificação de código](/pt/enterprise-server@3.19/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#downloading-codeql-packs-from-github-enterprise-server).

## Especificando quais consultas serão executadas em um CodeQL pacote

Os especificadores de consulta são usados por `codeql database analyze` e outros comandos que operam em um conjunto de consultas.
A forma completa de um especificador de consulta é `scope/name@range:path`, em que:

* `scope/name` é o nome qualificado de um CodeQL pacote.
* `range` é um [intervalo semver](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges).
* `path` é um caminho do sistema de arquivos para uma só consulta, um diretório que contém consultas ou um arquivo de conjunto de consultas.

Quando você especifica `scope/name`, `range` e `path` são opcionais. Se você omitir um `range`, a versão mais recente do pacote especificado será usada. Se você omitir um `path`, o conjunto de consultas padrão do pacote especificado será usado.

O `path` pode ser: um arquivo de consulta `.ql`, um diretório que contém uma ou mais consultas ou um arquivo de conjunto de consultas `.qls`. Se você omitir um nome de pacote, precisará fornecer um `path`, que será interpretado em relação ao diretório de trabalho do processo atual. Não há suporte para padrões glob.

Se você especificar `scope/name` e `path`, o `path` não poderá ser absoluto. Ele é considerado relativo à raiz do CodeQL
Pacote.

### Especificadores de consulta de exemplo

* `codeql/python-queries` – Todas as consultas no pacote de consultas padrão da versão mais recente do pacote `codeql/python-queries`.

* `codeql/python-queries@1.2.3` – Todas as consultas no pacote de consultas padrão da versão `1.2.3` do pacote `codeql/python-queries`.

* `codeql/python-queries@~1.2.3` – Todas as consultas no conjunto de consultas padrão da versão mais recente do pacote `codeql/python-queries` que são >= `1.2.3` e < `1.3.0`.

* `codeql/python-queries:Functions` – Todas as consultas no diretório `Functions` na versão mais recente do pacote `codeql/python-queries`.

* `codeql/python-queries@1.2.3:Functions` – Todas as consultas no diretório `Functions` da versão 1.2.3 do pacote `codeql/python-queries`.

* `codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls` – Todas as consultas no diretório `codeql-suites/python-code-scanning.qls` da versão 1.2.3 do pacote `codeql/python-queries`.

* `suites/my-suite.qls` – Todas as consultas no arquivo `suites/my-suite.qls` relativas ao diretório de trabalho atual.

> \[!TIP]
> O conjunto de consultas padrão dos pacotes de consulta padrão CodeQL é `codeql-suites/<lang>-code-scanning.qls`. Vários outros pacotes de consultas úteis também podem ser encontrados no diretório `codeql-suites`de cada pacote. Por exemplo, o pacote `codeql/cpp-queries` contém os seguintes conjuntos de consultas:
>
> *

`cpp-code-scanning.qls` – Consultas de verificação de código padrão para C++. O conjunto de consultas padrão desse pacote.

> \*
> `cpp-security-extended.qls` – Consultas do conjunto padrão `cpp-code-scanning.qls` para C++, além de consultas de gravidade e precisão inferiores.
> \*
> `cpp-security-and-quality.qls` – Consultas de `cpp-security-extended.qls`, além de consultas de capacidade de manutenção e confiabilidade.
>
> Você pode ver as fontes desses conjuntos de consultas no [CodeQL repositório](https://github.com/github/codeql/tree/main/cpp/ql/src/codeql-suites). Os pacotes de consultas para outras linguagens são semelhantes.

## Usando pacotes de modelo para analisar chamadas a dependências personalizadas

Você pode incluir pacotes de modelos publicados em uma code scanning análise com a opção `--model-packs` . Por exemplo:

```shell
$ codeql database analyze /codeql-dbs/my-company --format=sarif-latest \
  --model-packs my-repo/my-java-model-pack \
  --output=/temp/my-company.sarif codeql/java-queries
```

Neste exemplo, as consultas relevantes no pacote de consultas padrão `codeql/java-queries` usarão as informações de dependência do pacote de modelos, `my-repo/my-java-model-pack`, para verificar vulnerabilidades no código que chama essas dependências.

Você pode especificar vários pacotes de modelos publicados em uma análise.

Para obter mais informações sobre como gravar seus próprios pacotes de modelos, consulte [Como criar e trabalhar com pacotes do CodeQL](/pt/enterprise-server@3.19/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#creating-a-model-pack).

### Sobre pacotes publicados

Quando um pacote é publicado para uso em análises, o comando `codeql pack create` ou `codeql pack publish` verifica se o conteúdo está completo e também adiciona mais conteúdo a ele:

* Para pacotes de consulta, uma cópia de cada um dos pacotes de biblioteca dos quais eles dependem, nas versões precisas com as quais eles foram desenvolvidos. Os usuários do pacote de consultas não precisarão baixar esses pacotes de biblioteca separadamente.

* Para pacotes de consulta, representações pré-compiladas de cada uma das consultas. É mais rápido executá-las do que compilar a origem do QL para a consulta em cada análise.

A maioria desses dados está localizada em um diretório chamado `.codeql` no pacote publicado, mas as consultas pré-compiladas estão em arquivos com um sufixo `.qlx` ao lado da origem `.ql` de cada consulta. Ao analisar um banco de dados com uma consulta de um pacote publicado, CodeQL carregará esses arquivos em vez da origem `.ql` . Se você precisar modificar o conteúdo de um pacote *publicado*, remova todos os arquivos `.qlx`, pois eles podem impedir que as modificações nos arquivos `.ql` entrem em vigor.