Skip to main content
설명서에 자주 업데이트를 게시하며 이 페이지의 번역이 계속 진행 중일 수 있습니다. 최신 정보는 영어 설명서를 참조하세요.

CodeQL CLI에서 사용자 지정 쿼리 사용

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

GitHub CodeQL은(는) 설치 시 사용자별로 라이선스가 부여됩니다. 라이선스 제한에 따라 특정 작업에만 CodeQL을(를) 사용할 수 있습니다. 자세한 내용은 "CodeQL CLI 정보"을 참조하세요.

GitHub Enterprise 계정 및 GitHub Advanced Security 라이선스가 있는 경우 자동화된 분석, 연속 통합 및 지속적인 업데이트에 CodeQL를 사용할 수 있습니다. 영업 팀에 문의하여 엔터프라이즈 계정을 만들 수 있습니다. 자세한 내용은 "GitHub Advanced Security 정보"을 참조하세요.

Note: This article was migrated from the CodeQL documentation website in January 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.

Note: Queries run with database analyze have strict metadata requirements. You can also execute queries using the following plumbing-level subcommands:

  • database run-queries, which outputs non-interpreted results in an intermediate binary format called BQRS.
  • query run, which will output BQRS files, or print results tables directly to the command line. Viewing results directly in the command line may be useful for iterative query development using the CLI.

Queries run with these commands don’t have the same metadata requirements. However, to save human-readable data you have to process each BQRS results file using the bqrs decode plumbing subcommand. Therefore, for most use cases it’s easiest to use database analyze to directly generate interpreted results.

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.

Note: Metadata requirements may differ if you want to use your query with other applications. For more information, see “Metadata for CodeQL queries.”

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