From a9202b5c374ecf18fc91e925b68f2f5d9929d1d8 Mon Sep 17 00:00:00 2001 From: Andrew Eisenberg Date: Mon, 12 Sep 2022 13:07:32 -0700 Subject: [PATCH] Tweak the query suites documentation - Add examples to filter on `@id` - Add examples that include regexes - Add examples that include both lists and single elements - Add some `import` examples - Remove mention of `eval` since it is not a user-facing instruction --- .../creating-codeql-query-suites.rst | 88 ++++++++++++++++--- 1 file changed, 76 insertions(+), 12 deletions(-) diff --git a/docs/codeql/codeql-cli/creating-codeql-query-suites.rst b/docs/codeql/codeql-cli/creating-codeql-query-suites.rst index 1e212755367..a99cd4bbfa3 100644 --- a/docs/codeql/codeql-cli/creating-codeql-query-suites.rst +++ b/docs/codeql/codeql-cli/creating-codeql-query-suites.rst @@ -118,8 +118,10 @@ typically a query metadata property. The value can be: 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. -For more information about query metadata properties, see ":ref:`Metadata for CodeQL queries -`." +The standard metadata keys available to match on are: ``description``, ``id``, ``kind``, +``name``, ``tags``, ``precision``, ``problem.severity``, and ``security-severity``. +For more information about query metadata properties, see +":ref:`Metadata for CodeQL queries `." In addition to metadata tags, the keys in the constraint block can also be: @@ -131,8 +133,36 @@ In addition to metadata tags, the keys in the constraint block can also be: - ``tags contain all``---each of the given match strings must match one of the components of the ``@tags`` metadata property. -Examples -~~~~~~~~ +Filtering Examples +~~~~~~~~~~~~~~~~~~ + +A common use case is to create a query suite that runs all queries in a CodeQL pack, +except for a few that are known to be problematic. The following three query suite +definitions are semantically identical: + +Matches all queries in ``codeql/cpp-queries``, except for the two queries with either given ``id``:: + + - qlpack: codeql/cpp-queries + - exclude: + id: + - cpp/cleartext-transmission + - cpp/cleartext-storage-file + +As above, but splits the matching into two ``exclude`` instructions:: + + - qlpack: codeql/cpp-queries + - exclude: + id: cpp/cleartext-transmission + - exclude: + id: cpp/cleartext-storage-file + +As above, but uses a regular expression to match the ``id`` (assuming +that the regular expression matches exactly the previous queries):: + + - qlpack: codeql/cpp-queries + - exclude: + id: + - /^cpp\/cleartext-.*/ To define a suite that selects all queries in the default suite of the ``codeql/cpp-queries`` CodeQL pack, and then refines them to only include @@ -150,6 +180,15 @@ and ``@precision high`` from the ``my-custom-queries`` directory, use:: kind: problem precision: very-high +Note that the following query suite definition is not equivalent. This definition will select +queries that are ``@kind problem`` *or* are ``@precision very-high``:: + + - queries: my-custom-queries + - include: + kind: problem + - include: + precision: very-high + To create a suite that selects all queries with ``@kind problem`` from the ``my-custom-queries`` directory except those with ``@problem.severity recommendation``, use:: @@ -172,6 +211,13 @@ use:: - high - very-high +.. pull-quote:: + + Tip + + You can use the ``codeql resolve queries /path/to/suite.qls`` command to see + which queries are selected by a query suite definition. + Reusing existing query suite definitions ----------------------------------------- @@ -208,14 +254,8 @@ Existing query suite definitions can be reused by specifying: conditions, saved in a ``.yml`` file, to multiple query definitions. For more 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 - path to a ``.qls`` file on disk. - -To see what queries are included in a query suite, you can run the ``codeql resolve queries my-suite.qls`` command. - -Example -~~~~~~~ +Reusability Examples +~~~~~~~~~~~~~~~~~~~~ To use the same conditions in multiple query suite definitions, create a separate ``.yml`` file containing your instructions. For example, save the @@ -252,6 +292,30 @@ instruction:: from: my-org/my-custom-instructions version: ^1.2.3 # optional +A common use case an ``import`` instruction is to apply a further filter to queries from another +query suite. For example, this suite will further filter the ``cpp-security-and-quality`` suite +and exclude ``low`` and ``medium`` precision queries:: + + - import: codeql-suites/cpp-security-and-quality.qls + from: codeql/cpp-queries + - exclude: + precision: + - low + - medium + +If you want to ``include`` queries imported from another suite, the syntax is a little different:: + + - import: codeql-suites/cpp-security-and-quality.qls + from: codeql/cpp-queries + - exclude: {} + - include: + precision: + - very-high + - high + +Notice the empty ``exclude`` instruction. This is required to ensure that the subsequent ``include`` +instruction is able to filter queries from the imported suite. + Naming a query suite --------------------