You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- ``...<query-specifications>``: a list of queries to run over your database. This
59
+
- ``...<query-specifiers>``: a list of queries to run over your database. This
56
60
is a list of arguments. Where each argument can be:
57
61
58
62
- a path to a query file
@@ -62,7 +66,7 @@ You can also specify:
62
66
- with an optional version range
63
67
- with an optional path to a query, directory, or query suite inside the pack
64
68
65
-
If omitted, the default query suite for the language of the database being analyzed will be used. For more information, see the :ref:`examples <database-analyze-examples>` below.
69
+
If omitted, the default query suite for the language of the database being analyzed will be used. For the complete syntax of query specifiers, see the :ref:`examples <specifying-which-queries>` below.
66
70
67
71
- ``--sarif-category``: an identifying category for the results. Used when
68
72
you want to upload more than one set of results for a commit.
@@ -97,53 +101,92 @@ the `database analyze reference documentation <../manual/database-analyze>`__.
97
101
98
102
.. _database-analyze-examples:
99
103
100
-
Examples
101
-
--------
104
+
.. _specifying-which-queries:
102
105
103
-
The following examples assume your CodeQL databases have been created in a
104
-
directory that is a sibling of your local copies of the CodeQL and CodeQL for Go
105
-
repositories.
106
+
Specifying which queries to run in a CodeQL pack
107
+
------------------------------------------------
106
108
107
-
Running a single query
108
-
~~~~~~~~~~~~~~~~~~~~~~
109
+
*Query specifiers* are used by ``codeql database analyze`` and other commands that operate on a set of queries.
110
+
The complete way to specify a set of queries is in the form ``scope/name@range:path``, where:
109
111
110
-
To run a single query over a CodeQL database for a JavaScript codebase,
111
-
you could use the following command from the directory containing your database::
112
+
- ``scope/name`` is the qualified name of a CodeQL pack.
113
+
- ``range`` is a `semver range <https://docs.npmjs.com/cli/v6/using-npm/semver#ranges>`_.
114
+
- ``path`` is a file system path to a single query, a directory containing queries, or a query suite file.
When you specify a ``scope/name``, the ``range`` and ``path`` are
117
+
optional. If you omit a ``range`` then the latest version of the
118
+
specified pack is used. If you omit a ``path`` then the default query suite
119
+
of the specified pack is used.
114
120
115
-
This command runs a simple query that finds potential bugs related to unused
116
-
variables, imports, functions, or classes---it is one of the JavaScript
117
-
queries included in the CodeQL repository. You could run more than one query by
118
-
specifying a space-separated list of similar paths.
121
+
The ``path`` can be one of a ``.ql`` query file, a directory
122
+
containing one or more queries, or a ``.qls`` query suite file. If
123
+
you omit a pack name, then you must provide a ``path``,
124
+
which will be interpreted relative to the working directory
125
+
of the current process. Glob patterns are not supported.
119
126
120
-
The analysis generates a CSV file (``js-results.csv``) in a new directory
121
-
(``js-analysis``).
127
+
If you specify a ``scope/name`` and ``path``, then the ``path`` cannot
128
+
be absolute. It is considered relative to the root of the CodeQL
129
+
pack.
122
130
123
-
You can also run your own custom queries with the ``database analyze`` command.
124
-
For more information about preparing your queries to use with the CodeQL CLI,
125
-
see ":doc:`Using custom queries with the CodeQL CLI <using-custom-queries-with-the-codeql-cli>`."
131
+
Example query specifiers
132
+
------------------------
126
133
127
-
If you do not have the CodeQL repository checked out, you can execute the same queries by specifying the query pack name and the path to the queries::
134
+
* ``codeql/python-queries`` - All the queries in the default query suite of the latest version of the ``codeql/python-queries`` pack.
135
+
* ``codeql/python-queries@1.2.3`` - All the queries in the default query suite of version ``1.2.3`` of the ``codeql/python-queries`` pack.
136
+
* ``codeql/python-queries@~1.2.3`` - All the queries in the default query suite of the latest version of the ``codeql/python-queries`` pack that is >= ``1.2.3`` and < ``1.3.0``.
137
+
* ``codeql/python-queries:Functions`` - All queries in the ``Functions`` directory in the latest version of the ``codeql/python-queries`` pack.
138
+
* ``codeql/python-queries@1.2.3:Functions`` - All queries in the ``Functions`` directory in version 1.2.3 of the ``codeql/python-queries`` pack.
139
+
* ``codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls`` - All queries in the ``codeql-suites/python-code-scanning.qls`` directory in version 1.2.3 of the ``codeql/python-queries`` pack.
140
+
* ``suites/my-suite.qls`` - All queries in the ``suites/my-suite.qls`` file relative to the current working directory.
The ``analyze`` command above runs the default suite from ``microsoft/coding-standards v1.0.0`` and the latest version of ``github/security-queries`` on the specified database.
146
-
For further information about default suites, see ":ref:`Publishing and using CodeQL packs <publishing-and-using-codeql-packs>`".
162
+
The ``analyze`` command above runs the default query suite of two CodeQL query packs: ``microsoft/coding-standards`` version 1.0.0 and the latest version of ``github/security-queries`` on the
163
+
specified database. For further information about default suites, see
164
+
":ref:`Publishing and using CodeQL packs <publishing-and-using-codeql-packs>`".
165
+
166
+
The ``--download`` flag is optional. Using it will ensure the query pack is downloaded if it isn't yet available locally.
167
+
168
+
Running a single query
169
+
~~~~~~~~~~~~~~~~~~~~~~
170
+
171
+
To run a single query over a CodeQL database for a JavaScript codebase,
172
+
you could use the following command from the directory containing your database::
If you are using CodeQL CLI v2.8.1 or later, you can include a path at the end of a pack specification to run a subset of queries inside the pack. This applies to any command that locates or runs queries within a pack.
180
-
181
-
The complete way to specify a set of queries is in the form ``scope/name@range:path``, where:
182
-
183
-
- ``scope/name`` is the qualified name of a CodeQL pack.
184
-
- ``range`` is a `semver range <https://docs.npmjs.com/cli/v6/using-npm/semver#ranges>`_.
185
-
- ``path`` is a file system path to a single query, a directory containing queries, or a query suite file.
186
-
187
-
When you specify a ``scope/name``, the ``range`` and ``path`` are
188
-
optional. If you omit a ``range`` then the latest version of the
189
-
specified pack is used. If you omit a ``path`` then the default query suite
190
-
of the specified pack is used.
191
-
192
-
The ``path`` can be one of a ``*.ql`` query file, a directory
193
-
containing one or more queries, or a ``.qls`` query suite file. If
194
-
you omit a pack name, then you must provide a ``path``,
195
-
which will be interpreted relative to the working directory
196
-
of the current process.
197
-
198
-
If you specify a ``scope/name`` and ``path``, then the ``path`` cannot
199
-
be absolute. It is considered relative to the root of the CodeQL
200
-
pack.
201
-
202
-
To analyze a database using all queries in the `experimental/Security` folder within the `codeql/cpp-queries` CodeQL pack you can use::
To analyze your database using the `cpp-security-and-quality.qls` query suite from a version of the `codeql/cpp-queries` CodeQL pack that is >= 0.0.3 and < 0.1.0 (the highest compatible version will be chosen) you can use::
The analysis generates a file in the v2.1.0 SARIF format that is supported by all versions of GitHub.
228
-
This file can be uploaded to GitHub by executing ``codeql github upload-results`` or the code scanning API.
231
+
This command downloads the ``codeql/cpp-queries`` CodeQL query pack, runs the analysis, and generates a file in the v2.1.0 SARIF format that is supported by all versions of GitHub. This file can be uploaded to GitHub by executing ``codeql github upload-results`` or the code scanning API.
229
232
For more information, see `Analyzing a CodeQL database <https://docs.github.com/en/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system#analyzing-a-codeql-database>`__
230
233
or `Code scanning API <https://docs.github.com/en/rest/reference/code-scanning>`__ in the GitHub documentation.
231
234
232
235
CodeQL query suites are ``.qls`` files that use directives to select queries to run
233
236
based on certain metadata properties. The standard CodeQL packs have metadata that specify
234
237
the location of the query suites used by code scanning, so the CodeQL CLI knows where to find these
235
238
suite files automatically, and you don't have to specify the full path on the command line.
236
-
For more information, see ":ref:`About CodeQL packs <standard-codeql-packs>`."
237
-
238
-
The standard query suites are stored at the following paths in
239
-
the CodeQL repository::
239
+
For more information, see ":ref:`Creating CodeQL query suites <creating-codeql-query-suites>`."
Query suites in the core CodeQL query packs are all stored in the ``codeql-suites`` directory of the pack. For example, the ``codeql/cpp-queries`` pack contains the following query suites:
242
242
243
-
and at the following path in the CodeQL for Go repository::
243
+
* ``cpp-code-scanning.qls`` - Standard Code Scanning queries for C++.
244
+
* ``cpp-security-and-quality`` - Security-and-quality queries for C++.
245
+
* ``cpp-security-extended`` - Security-extended queries for C++. This suite contains queries that are less precise than the standard security queries, and may find more false-positives.
246
+
* ``cpp-lgtm.qls`` - Standard LGTM queries for C++.
247
+
* ``cpp-lgtm-full.qls`` - Standard LGTM queries for C++, including less precise queries.
244
248
245
-
ql/src/codeql-suites/go-code-scanning.qls
246
-
247
-
The repository also includes the query suites used by `LGTM.com <https://lgtm.com>`__.
248
-
These are stored alongside the query suites for code scanning with names of the form: ``<language>-lgtm.qls``.
249
+
You can see the sources for these query suites in the `CodeQL repository <https://github.com/github/codeql/tree/main/cpp/ql/src/codeql-suites>`. Query suites for other languages are similar.
249
250
250
251
For information about creating custom query suites, see ":doc:`Creating
You can use CodeQL query packs in your code scanning setup. This allows you to select query packs published by various sources and use them to analyze your code.
266
265
For more information, see "`Using CodeQL query packs in the CodeQL action <https://docs.github.com/en/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-codeql-query-packs/>`_" or "`Downloading and using CodeQL query packs in your CI system <https://docs.github.com/en/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system#downloading-and-using-codeql-query-packs>`_."
0 commit comments