From 0923d1fdc197c8ae3205d153e3d75fece374d20b Mon Sep 17 00:00:00 2001 From: Andrew Eisenberg Date: Tue, 31 Aug 2021 13:39:04 -0700 Subject: [PATCH] Docs: Update documentation for query suites Adds some clarification around the `qlpack` directive. The semantics has changed. This provides a new example and some description. --- .../creating-codeql-query-suites.rst | 58 ++++++++++++------- 1 file changed, 36 insertions(+), 22 deletions(-) diff --git a/docs/codeql/codeql-cli/creating-codeql-query-suites.rst b/docs/codeql/codeql-cli/creating-codeql-query-suites.rst index ba164a40da0..39b99e224d4 100644 --- a/docs/codeql/codeql-cli/creating-codeql-query-suites.rst +++ b/docs/codeql/codeql-cli/creating-codeql-query-suites.rst @@ -4,8 +4,8 @@ Creating CodeQL query suites ============================ CodeQL query suites provide a way of selecting queries, based on their -filename, location on disk or in a QL pack, or metadata properties. -Create query suites for the queries that you want to frequently use in +filename, location on disk or in a QL pack, or metadata properties. +Create query suites for the queries that you want to frequently use in your CodeQL analyses. Query suites allow you to pass multiple queries to @@ -19,7 +19,7 @@ suite definition have been executed, the result is a set of selected queries. .. pull-quote:: Note Any custom queries that you want to add to a query suite must be in a :doc:`QL - pack ` and contain the correct query metadata. + pack ` and contain the correct query metadata. For more information, see ":doc:`Using custom queries with the CodeQL CLI `." @@ -50,10 +50,15 @@ queries using: - queries: from: -- A ``qlpack`` instruction---tells CodeQL to look for queries in a named QL pack:: +- A ``qlpack`` instruction---tells CodeQL to resolve queries in the default suite of the + named QL pack:: - qlpack: + The default suite of a query pack includes all of the common and recommended queries + inside of that suite. Not all query packs have a default suite. Those that do not + define a default suite will resolve all of the queries in all of their subdirectories. + .. pull-quote:: Note When pathnames appear in query suite definitions, they must always @@ -73,7 +78,7 @@ Filtering the queries in a query suite After you have defined the initial set of queries to add to your suite by specifying ``query``, ``queries``, or ``qlpack`` instructions, you can add ``include`` and ``exclude`` instructions. These instructions define selection -criteria based on specific properties: +criteria based on specific properties: - When you execute an ``include`` instruction on a set of queries, any queries that match your conditions are retained in the selection, and queries @@ -99,12 +104,12 @@ For both instructions, the argument is a constraint block---that is, a YAML map representing the constraints. Each constraint is a map entry, where the key is typically a query metadata property. The value can be: -- A single string. +- A single string. - A ``/``\ -enclosed `regular expression `__. - A list containing strings, regular expressions, or both. To match a constraint, a metadata value must match one of the strings or -regular expressions. When there is more than one metadata key, each key must be matched. +regular expressions. When there is more than one metadata key, each key must be matched. For more information about query metadata properties, see ":ref:`Metadata for CodeQL queries `." @@ -112,7 +117,7 @@ In addition to metadata tags, the keys in the constraint block can also be: - ``query filename``---matches on the last path component of the query file name. - ``query path``---matches on the path to the query file relative to its - enclosing QL pack. + enclosing QL pack. - ``tags contain``---one of the given match strings must match one of the space-separated components of the value of the ``@tags`` metadata property. - ``tags contain all``---each of the given match strings must match one of the @@ -121,6 +126,14 @@ In addition to metadata tags, the keys in the constraint block can also be: Examples ~~~~~~~~ +To define a suite that selects all queries in the default suite of the +``codeql/cpp-queries`` QL pack, and then refines them to only include +security queries, use:: + + - queries: codeql/cpp-queries + - include: + tags contain: security + To define a suite that selects all queries with ``@kind problem`` and ``@precision high`` from the ``my-custom-queries`` directory, use:: @@ -136,34 +149,35 @@ recommendation``, use:: - queries: my-custom-queries - include: kind: problem - - exclude: + - exclude: problem.severity: recommendation To create a suite that selects all queries with ``@tag security`` and -``@problem.severity high`` or ``very-high`` from the ``codeql-cpp`` QL pack, +``@problem.severity high`` or ``very-high`` from the ``codeql/cpp-queries`` QL pack, use:: - - qlpack: codeql-cpp - - include: + - queries: . + from: codeql/cpp-queries + - include: tags contain: security - problem.severity: + problem.severity: - high - very-high Reusing existing query suite definitions ----------------------------------------- -Existing query suite definitions can be reused by specifying: +Existing query suite definitions can be reused by specifying: - An ``import`` instruction---adds the queries selected by a previously defined ``.qls`` file to the current suite:: - + - import: The path to the imported suite must be relative to the QL pack containing the current suite definition. If the imported query suite is in a different QL pack you can use:: - + - import: from: @@ -175,12 +189,12 @@ Existing query suite definitions can be reused by specifying: applied ``.qls`` file are executed as if they appear in place of ``apply``. Any ``include`` and ``exclude`` instructions from the applied suite also act on queries added by any earlier instructions:: - + - apply: The ``apply`` instruction can also be used to apply a set of reusable conditions, saved in a ``.yml`` file, to multiple query definitions. For more - information, see the `example <#example>`__ below. + information, see the `example <#example>`__ below. - An ``eval`` instruction---performs the same function as an ``import`` instruction, but takes a full suite definition as the argument, rather than the @@ -236,7 +250,7 @@ instruction:: This value is displayed when you run `codeql resolve queries <../manual/resolve-queries>`__, if the suite is added to a "well-known" directory. For more information, see "`Specifying well-known query suites -<#specifying-well-known-query-suites>`__." +<#specifying-well-known-query-suites>`__." Saving a query suite -------------------- @@ -248,8 +262,8 @@ Specifying well-known query suites ---------------------------------- You can use QL packs to declare directories that contain "well-known" query -suites. You can use "well-known" query suites on the command line by referring -to their file name, +suites. You can use "well-known" query suites on the command line by referring +to their file name, without providing their full path. This gives you a simple way of specifying a set of queries, without needing to search inside QL packs and distributions. To declare a directory that contains "well-known" query suites, add the directory @@ -263,7 +277,7 @@ You can specify query suites on the command line for any command that accepts ``.qls`` files. For example, you can compile the queries selected by a suite definition using ``query compile``, or use the queries in an analysis using ``database analyze``. For more information about analyzing CodeQL databases, see -":doc:`Analyzing databases with the CodeQL CLI `." +":doc:`Analyzing databases with the CodeQL CLI `." Viewing the query suites used on LGTM.com -----------------------------------------