Observação: este artigo foi migrado do site de documentação do CodeQL em janeiro de 2023.
About custom queries and the CodeQL CLI
You can customize your CodeQL analyses by writing your own queries to highlight specific vulnerabilities or errors.
This topic is specifically about writing queries to use with the database analyze command to produce interpreted results.
Observação: as consultas executadas com database analyze têm requisitos estritos de metadados. Você também pode executar consultas usando os seguintes subcomandos no nível do plumbing:
- Consultas de execução de banco de dados, que gera resultados não interpretados em um formato binário intermediário chamado BQRS.
- execução de consulta, que produzirá arquivos BQRS ou imprimirá tabelas de resultados diretamente na linha de comando. Pode ser útil ver os resultados diretamente na linha de comando no caso de desenvolvimento de consultas iterativas usando a CLI.
As consultas executadas com esses comandos não têm os mesmos requisitos de metadados. No entanto, para salvar dados legíveis por pessoas, você precisa processar cada arquivo de resultados BQRS usando o subcomando de plumbing bqrs decode. Portanto, para a maioria dos casos de uso, é mais fácil usar a análise de banco de dados para gerar diretamente resultados interpretados.
Writing a valid query
Before running a custom analysis you need to write a valid query, and save it in a file with a .ql extension. There is extensive documentation available to help you write queries. For more information, see “CodeQL queries.”
Including query metadata
Query metadata is included at the top of each query file. It provides users with information about the query, and tells the CodeQL CLI how to process the query results.
When running queries with the database analyze command, you must include the following two properties to ensure that the results are interpreted correctly:
-
Query identifier (
@id): a sequence of words composed of lowercase letters or digits, delimited by/or-, identifying and classifying the query. -
Query type (
@kind): identifies the query as a simple alert (@kind problem), an alert documented by a sequence of code locations (@kind path-problem), for extractor troubleshooting (@kind diagnostic), or a summary metric (@kind metricand@tags summary).
For more information about these metadata properties, see “Metadata for CodeQL queries” and the Query metadata style guide.
Note: Metadata requirements may differ if you want to use your query with other applications. For more information, see “Metadata for CodeQL queries.”
Packaging custom QL queries
Observação: a funcionalidade de gerenciamento de pacotes do CodeQL, incluindo os pacotes do CodeQL, está em beta no momento e sujeita a alterações. Durante a versão beta, os pacotes do CodeQL estão disponíveis apenas usando pacotes do GitHub – O Container registry. Para usar essa funcionalidade beta, instale a versão mais recente do pacote da CLI do CodeQL de: https://github.com/github/codeql-action/releases.
When you write your own queries with the intention to share them with others, you should save them in a custom CodeQL pack. You can publish the pack as a CodeQL pack to GitHub Packages - the GitHub Container registry. For more information, see “About CodeQL packs.”
CodeQL packs organize the files used in CodeQL analysis and can store queries, library files, query suites, and important metadata. Their root directory must contain a file named qlpack.yml. Your custom queries should be saved in the CodeQL pack root, or its subdirectories.
For each CodeQL pack, the qlpack.yml file includes information that tells the CodeQL CLI how to compile the queries, which other CodeQL packs and libraries the pack depends on, and where to find query suite definitions. For more information about what to include in this file, see “About CodeQL packs.”
Contributing to the CodeQL repository
If you would like to share your query with other CodeQL users, you can open a pull request in the CodeQL repository. For more information, see Contributing to CodeQL.