mirror of
https://github.com/github/codeql.git
synced 2025-12-22 11:46:32 +01:00
ed66388551
This moves the following three PRs to the 3.7 branch: - https://github.com/github/codeql/pull/10182 - https://github.com/github/codeql/pull/10146 - https://github.com/github/codeql/pull/10105
85 lines
3.5 KiB
ReStructuredText
85 lines
3.5 KiB
ReStructuredText
.. _using-custom-queries-with-the-codeql-cli:
|
|
|
|
Using custom queries with 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 <../manual/database-analyze>`__
|
|
command to produce :ref:`interpreted results <interpret-query-results>`.
|
|
|
|
.. include:: ../reusables/advanced-query-execution.rst
|
|
|
|
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 ":ref:`CodeQL queries
|
|
<codeql-queries>`."
|
|
|
|
.. _including-query-metadata:
|
|
|
|
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 ":ref:`Metadata for CodeQL queries
|
|
<metadata-for-codeql-queries>`" and the `Query metadata style guide
|
|
<https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md>`__.
|
|
|
|
.. pull-quote:: Note
|
|
|
|
Metadata requirements may differ if you want to use your query with other
|
|
applications. For more information, see ":ref:`Metadata for CodeQL queries
|
|
<metadata-for-codeql-queries>`
|
|
."
|
|
|
|
Packaging custom QL queries
|
|
---------------------------
|
|
|
|
.. include:: ../reusables/beta-note-package-management.rst
|
|
|
|
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 further information see
|
|
":ref:`About CodeQL packs <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 ":ref:`About CodeQL packs <codeqlpack-yml-properties>`."
|
|
|
|
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 <https://github.com/github/codeql>`__. For
|
|
further information, see `Contributing to CodeQL
|
|
<https://github.com/github/codeql/blob/main/CONTRIBUTING.md>`__.
|
|
|
|
Further reading
|
|
---------------
|
|
|
|
- ":ref:`CodeQL queries
|
|
<codeql-queries>`"
|