このバージョンの GitHub Enterprise サーバーはこの日付をもって終了となります: 2026-03-17. 重大なセキュリティの問題に対してであっても、パッチリリースは作成されません。 パフォーマンスの向上、セキュリティの向上、新機能の向上を図るために、最新バージョンの GitHub Enterprise サーバーにアップグレードしてください。 アップグレードに関するヘルプについては、GitHub Enterprise サポートにお問い合わせください。

Custom CodeQL queries

Custom queries extend CodeQL's built-in security analysis to detect vulnerabilities and enforce coding standards specific to your codebase.

この機能を使用できるユーザーについて

CodeQL は、次の種類のリポジトリで使用できます:

この記事の内容

What are custom CodeQL queries?

Custom queries extend CodeQL's built-in security analysis to detect vulnerabilities, coding standards, and patterns specific to your codebase.

メモ

database analyze で実行されるクエリには、厳密なメタデータ要件があります。 次のプラミング レベルのサブコマンドを使用してクエリを実行することもできます。

  • データベース実行クエリ は、解釈されていない結果を BQRS と呼ばれる中間バイナリ形式で出力します
  • クエリの実行 は、BQRS ファイルを出力するか、結果テーブルをコマンド ラインに直接出力します。 コマンド ラインで結果を直接表示すると、CLI を使用した反復クエリ開発に役立つ場合があります。

これらのコマンドを使用して実行されるクエリについては、メタデータの要件は同じではありません。 ただし、人間が判読できるデータを保存するには、bqrs をデコードする プラミング サブコマンドを使って各 BQRS 結果ファイルを処理する必要があります。 そのため、ほとんどのユース ケースの場合、データベース分析を使用して、解釈された結果を直接生成するのが最も簡単です。

When to use custom queries

Use custom queries to:

  • Detect vulnerabilities specific to your application's architecture or frameworks
  • Enforce organization-specific coding standards or best practices
  • Find patterns not covered by standard CodeQL query packs
  • Analyze CodeQL databases with the database analyze command using the CodeQL CLI to produce interpreted results

Query structure

Custom queries are written in query files, which are saved with the .ql extension. These files also contain important metadata that provides information about the query's purpose and tells the CodeQL CLI how to process results. Required properties include:

  • Query identifier (@id): Lowercase letters or digits, delimited by / or -
  • Query type (@kind): One of:
    • problem - Simple alert
    • path-problem - Alert with code location sequence
    • diagnostic - Extractor troubleshooting
    • metric - Summary metric (requires @tags summary)

メモ

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

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

Query documentation

Query documentation helps users understand what a query detects and how to address identified issues. You can include documentation for your custom queries in two formats:

  • Markdown files: Saved alongside the query, can be included in SARIF files and displayed in the code scanning UI
  • .qhelp files: Consistent with standard CodeQL queries, but must be converted to Markdown for use with code scanning

When SARIF files containing query help are uploaded to GitHub, the documentation appears in the code scanning UI for any alerts generated by the query.

For more information, see Query help files.

Sharing custom queries

You can share custom queries with the community by publishing your own query packs. See CodeQL パックを発行して使用する.

Further reading