Using custom queries with the CodeQL CLI

You can write your own CodeQL queries to find specific vulnerabilities and errors.

누가 이 기능을 사용할 수 있나요?

CodeQL은(는) 다음 리포지토리 유형에 사용할 수 있습니다.

이 문서의 내용

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.

참고 항목

쿼리는 엄격한 메타데이터 요구 사항으로 database analyze와(과) 실행됩니다. 다음 배관 수준 하위 명령을 사용하여 쿼리를 실행할 수도 있습니다.

  • database run-queries- 해석되지 않은 결과를 BQRS라는 중간 이진 형식으로 출력합니다.
  • query run- BQRS 파일을 출력하거나 결과 테이블을 명령줄에 직접 출력합니다. 명령줄에서 직접 결과를 보는 것은 CLI를 사용하여 반복 쿼리를 개발하는 데 유용할 수 있습니다.

이러한 명령으로 실행되는 쿼리에는 동일한 메타데이터 요구 사항이 없습니다. 그러나 사람이 읽을 수 있는 데이터를 저장하려면 bqrs decode 배관 하위 명령을 사용하여 각 BQRS 결과 파일을 처리해야 합니다. 따라서 대부분의 사용 사례에서는 데이터베이스 분석을 사용하여 해석된 결과를 직접 생성하는 것이 가장 쉽습니다.

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 metric and @tags summary).

For more information about these metadata properties, see Metadata for CodeQL queries and the Query metadata style guide.

참고 항목

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

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 Customizing analysis with 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 Customizing analysis with CodeQL packs.

Including query help for custom CodeQL queries in SARIF files

If you use the CodeQL CLI to run code scanning analyses on third party CI/CD systems, you can include the query help for your custom queries in SARIF files generated during an analysis. After uploading the SARIF file to GitHub, the query help is shown in the code scanning UI for any alerts generated by the custom queries.

From CodeQL CLI v2.7.1 onwards, you can include markdown-rendered query help in SARIF files by providing the --sarif-add-query-help option when running codeql database analyze.

You can write query help for custom queries directly in a markdown file and save it alongside the corresponding query. Alternatively, for consistency with the standard CodeQL queries, you can write query help in the .qhelp format. Query help written in .qhelp files can’t be included in SARIF files, and they can’t be processed by code scanning so must be converted to markdown before running the analysis. For more information, see Query help files and Testing query help files.

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.

Further reading