hohn/codeql
1
0
Fork 0
mirror of https://github.com/github/codeql.git synced 2026-02-10 12:11:07 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into peewee-modeling

Browse Source
This commit is contained in:
Rasmus Wriedt Larsen
2021-08-17 12:02:33 +02:00
parent 97571e0b4f 44ff623d8c
commit b649f5f38c
2085 changed files with 77183 additions and 20087 deletions
Download Patch File Download Diff File Expand all files Collapse all files

104
docs/codeql/codeql-cli/about-codeql-packs.rst Normal file
View File

@@ -0,0 +1,104 @@
.. _about-codeql-packs:
About CodeQL packs
==================
.. include:: ../reusables/beta-note-package-management.rst
CodeQL packs are used to create, share, depend on, and run CodeQL queries and libraries. You can publish your own CodeQL packs and download packs created by others. CodeQL packs contain queries, library files, query suites, and metadata.
There are two types of CodeQL packs: query packs and library packs.
* Query packs are designed to be run. When a query pack is published, the bundle includes all the transitive dependencies and a compilation cache. This ensures consistent and efficient execution of the queries in the pack.
* Library packs are designed to be used by query packs (or other library packs) and do not contain queries themselves. The libraries are not compiled and there is no compilation cache included when the pack is published.
You can use the package management commands in the CodeQL CLI to create CodeQL packs, add dependencies to packs, and install or update dependencies. For more information, see ":ref:`Creating and working with CodeQL packs <creating-and-working-with-codeql-packs>`." You can also publish and download CodeQL packs using the CodeQL CLI. For more information, see ":doc:`Publishing and using CodeQL packs <publishing-and-using-codeql-packs>`."
CodeQL pack structure
---------------------
A CodeQL pack must contain a file called ``qlpack.yml`` in its root directory. In the ``qlpack.yml`` file, the ``name:`` field must have a value that follows the format of ``<scope>/<pack>``, where ``<scope>`` is the GitHub organization or user account that the pack will be published to and ``<pack>`` is the name of the pack. The other
files and directories within the pack should be logically organized. For example, typically:
- Queries are organized into directories for specific categories.
- Queries for specific products, libraries, and frameworks are organized into
their own top-level directories.
About ``qlpack.yml`` files
--------------------------
When executing query-related commands, CodeQL first looks in siblings of the installation directory (and their subdirectories) for ``qlpack.yml`` files.
Then it checks the package cache for CodeQL packs which have been downloaded. This means that when you are developing queries locally, the local packages
in the installation directory override packages of the same name in the package cache, so that you can test your local changes.
The metadata in each `qlpack.yml`` file tells
CodeQL how to compile any queries in the pack, what libraries the pack depends on, and where to
find query suite definitions.
The contents of the CodeQL pack (queries or libraries used in CodeQL analysis) is
included in the same directory as ``qlpack.yml``, or its subdirectories.
The location of ``qlpack.yml`` defines the library path for the content
of the CodeQL pack. That is, for all ``.ql`` and ``.qll`` files in the pack,
CodeQL will resolve all import statements relative to the ``qlpack.yml`` at the
pack's root.
.. _codeqlpack-yml-properties:
``qlpack.yml`` properties
~~~~~~~~~~~~~~~~~~~~~~~~~
The following properties are supported in ``qlpack.yml`` files.
.. list-table::
:header-rows: 1
:widths: auto
* - Property
- Example
- Required
- Purpose
* - ``name``
- ``octo-org/security-queries``
- All packs
- The scope, where the CodeQL pack is published, and the name of the pack defined using alphanumeric characters and hyphens. It must be unique as CodeQL cannot differentiate between CodeQL packs with identical names. Name components cannot start or end with a hyphen. Additionally, a period is not allowed in pack names at all. Use the pack name to specify queries to run using ``database analyze`` and to define dependencies between QL packs (see examples below).
* - ``version``
- ``0.0.0``
- All packs
- A version range for this CodeQL pack. This must be a valid semantic version that meets the `SemVer v2.0.0 specification <https://semver.org/spec/v2.0.0.html>`__.
* - ``dependencies``
- ``codeql/javascript-all: ^1.2.3``
- Optional
- The names and version ranges of any CodeQL packs that this pack depends on, as a mapping. This gives the pack access to any libraries, database schema, and query suites defined in the dependency. For more information, see `SemVer ranges <https://docs.npmjs.com/cli/v6/using-npm/semver#ranges>`__ in the NPM documentation.
* - ``suites``
- ``octo-org-query-suites``
- Optional
- The path to a directory in the pack that contains the query suites you want to make known to the CLI, defined relative to the pack directory. QL pack users can run "well-known" suites stored in this directory by specifying the pack name, without providing their full path. This is not supported for CodeQL packs downloaded from a package registry. For more information about query suites, see ":doc:`Creating CodeQL query suites <creating-codeql-query-suites>`."
* - ``extractor``
- ``javascript``
- All test packs
- The CodeQL language extractor to use when the CLI creates a database in the pack. For more information about testing queries, see ":doc:`Testing custom queries <testing-custom-queries>`."
* - ``tests``
- ``.``
- Optional for test packs
- The path to a directory within the pack that contains tests, defined relative to the pack directory. Use ``.`` to specify the whole pack. Any queries in this directory are run as tests when ``test run`` is run with the ``--strict-test-discovery`` option. These queries are ignored by query suite definitions that use ``queries`` or ``qlpack`` instructions to ask for all queries in a particular pack.
* - ``dbscheme``
- ``semmlecode.python.dbscheme``
- Core language packs only
- The path to the :ref:`database schema <codeql-database-schema>` for all libraries and queries written for this CodeQL language (see example below).
* - ``upgrades``
- ``.``
- Core language packs only
- The path to a directory within the pack that contains upgrade scripts, defined relative to the pack directory. The ``database upgrade`` action uses these scripts to update databases that were created by an older version of an extractor so they're compatible with the current extractor (see `Upgrade scripts for a language <#upgrade-scripts-for-a-language>`__ below.)
* - ``authors``
- ``example@github.com``
- All packs
- Metadata that will be displayed on the packaging search page in the packages section of the account that the CodeQL pack is published to.
* - ``licenses``
- ``(LGPL-2.1 AND MIT)``
- All packs
- Metadata that will be displayed on the packaging search page in the packages section of the account that the CodeQL pack is published to. For a list of allowed licenses, see `SPDX License List <https://spdx.org/licenses/>`__ in the SPDX Specification.
* - ``description``
- ``Human-readable description of the contents of the CodeQL pack.``
- All packs
- Metadata that will be displayed on the packaging search page in the packages section of the account that the CodeQL pack is published to.

2
docs/codeql/codeql-cli/about-ql-packs.rst
View File

@@ -87,7 +87,7 @@ The following properties are supported in ``qlpack.yml`` files.
* - ``suites``
- ``suites``
- Optional
- The path to a directory that contains the "well-known" query suites in the pack, defined relative to the pack directory. You can run "well-known" suites stored in this directory by specifying the pack name, without providing their full path. To use query suites stored in other directories in the pack, you must provide their full path. For more information about query suites, see ":doc:`Creating CodeQL query suites <creating-codeql-query-suites>`."
- The path to a directory in the pack that contains the query suites you want to make known to the CLI, defined relative to the pack directory. QL pack users can run "well-known" suites stored in this directory by specifying the pack name, without providing their full path. For more information about query suites, see ":doc:`Creating CodeQL query suites <creating-codeql-query-suites>`."
* - ``extractor``
- ``javascript``
- All test packs

116
docs/codeql/codeql-cli/analyzing-databases-with-the-codeql-cli.rst
View File

@@ -16,9 +16,9 @@ For information about writing queries to run with ``database analyze``, see
Before starting an analysis you must:
- :doc:`Set up the CodeQL CLI <getting-started-with-the-codeql-cli>` so that it can find the queries
and libraries included in the CodeQL repository.
- :doc:`Create a CodeQL database <creating-codeql-databases>` for the source
code you want to analyze.
and libraries included in the CodeQL repository.
- :doc:`Create a CodeQL database <creating-codeql-databases>` for the source
code you want to analyze.
Running ``codeql database analyze``
@@ -56,10 +56,16 @@ You must specify:
You can also specify:
- ``--sarif-category``: an identifying category for the results. Used when
you want to upload more than one set of results for a commit.
For example, when you use ``github upload-results`` to send results for more than one
language to the GitHub code scanning API. For more information about this use case,
see `Configuring CodeQL CLI 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>`__ in the GitHub documentation.
- .. include:: ../reusables/threads-query-execution.rst
.. pull-quote::
.. pull-quote::
Upgrading databases
@@ -85,10 +91,10 @@ repositories.
Running a single query
~~~~~~~~~~~~~~~~~~~~~~
To run a single query over a JavaScript codebase, you could use the following
command from the directory containing your database::
To run a single query over a CodeQL database for a JavaScript codebase,
you could use the following command from the directory containing your database::
codeql database analyze <javascript-database> ../ql/javascript/ql/src/Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv
codeql database analyze <javascript-database> ../ql/javascript/ql/src/Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv
This command runs a simple query that finds potential bugs related to unused
variables, imports, functions, or classes---it is one of the JavaScript
@@ -96,22 +102,48 @@ queries included in the CodeQL repository. You could run more than one query by
specifying a space-separated list of similar paths.
The analysis generates a CSV file (``js-results.csv``) in a new directory
(``js-analysis``).
(``js-analysis``).
You can also run your own custom queries with the ``database analyze`` command.
For more information about preparing your queries to use with the CodeQL CLI,
see ":doc:`Using custom queries with the CodeQL CLI <using-custom-queries-with-the-codeql-cli>`."
Running GitHub code scanning suites
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Running a CodeQL pack
~~~~~~~~~~~~~~~~~~~~~
The CodeQL repository also includes query suites, which can be run over your
code as part of a broader code review. CodeQL query suites are ``.qls`` files
that use directives to select queries to run based on certain metadata
properties.
.. include:: ../reusables/beta-note-package-management.rst
The CodeQL repository includes query suites that are used by the CodeQL action on
`GitHub.com <https://github.com>`__. The query suites are located at the following paths in
To run an existing CodeQL query pack from the GitHub Container registry, you need to download it first::
codeql pack download microsoft/coding-standards@1.0.0
Afterwards, you can run the pack on a specific database::
codeql database analyze <database> microsoft/coding-standards@1.0.0 <scope>/<other-pack> --format=sarifv2.1.0 --output=query-results.sarif
The ``analyze`` command above runs the default suite from ``microsoft/coding-standards v1.0.0`` and the latest version of ``scope/other-pack`` on the specified database.
For further information about default suites, see ":ref:`Publishing and using CodeQL packs <publishing-and-using-codeql-packs>`".
Running query suites
~~~~~~~~~~~~~~~~~~~~
To run a query suite over a CodeQL database for a C/C++ codebase,
you could use the following command from the directory containing your database::
codeql database analyze <cpp-database> cpp-code-scanning.qls --format=sarifv2.1.0 --output=cpp-results.sarif
The analysis 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.
For more information, see `Analyzing a CodeQL database <https://docs.github.com/en/code-security/secure-coding/configuring-codeql-cli-in-your-ci-system#analyzing-a-codeql-database>`__
or `Code scanning API <https://docs.github.com/en/rest/reference/code-scanning>`__ in the GitHub documentation.
CodeQL query suites are ``.qls`` files that use directives to select queries to run
based on certain metadata properties. The standard QL packs have metadata that specify
the location of the query suites used by code scanning, so the CodeQL CLI knows where to find these
suite files automatically, and you don't have to specify the full path on the command line.
For more information, see ":ref:`About QL packs <standard-ql-packs>`."
The standard query suites are stored at the following paths in
the CodeQL repository::
ql/<language>/ql/src/codeql-suites/<language>-code-scanning.qls
@@ -120,25 +152,8 @@ and at the following path in the CodeQL for Go repository::
ql/src/codeql-suites/go-code-scanning.qls
These locations are specified in the metadata included in the standard QL packs.
This means that the CodeQL CLI knows where to find the suite files automatically, and
you don't have to specify the full path on the command line when running an
analysis. For more information, see ":ref:`About QL packs <standard-ql-packs>`."
.. pull-quote::
Important
If you plan to upload the results to GitHub, you must generate SARIF results.
For more information, see `Analyzing a CodeQL database <https://docs.github.com/en/code-security/secure-coding/running-codeql-cli-in-your-ci-system#analyzing-a-codeql-database>`__ in the GitHub documentation.
For example, to run the code scanning query suite on a C++ codebase and generate
results in the v2.1 SARIF format supported by all versions of GitHub, you would run::
codeql database analyze <cpp-database> cpp-code-scanning.qls --format=sarifv2.1.0 --output=cpp-analysis/cpp-results.sarif
The repository also includes the query suites used by `LGTM.com <https://lgtm.com>`__.
These are stored alongside the code scanning suites with names of the form: ``<language>-lgtm.qls``.
These are stored alongside the query suites for code scanning with names of the form: ``<language>-lgtm.qls``.
For information about creating custom query suites, see ":doc:`Creating
CodeQL query suites <creating-codeql-query-suites>`."
@@ -150,12 +165,21 @@ When you create a CodeQL database, the extractor stores diagnostic data in the d
If the analysis found fewer results for standard queries than you expected, review the results of the diagnostic and summary queries to check whether the CodeQL database is likely to be a good representation of the codebase that you want to analyze.
Integrating a CodeQL pack into a code scanning workflow in GitHub
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: ../reusables/beta-note-package-management.rst
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.
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>`_."
Running all queries in a directory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can run all the queries located in a directory by providing the directory
path, rather than listing all the individual query files. Paths are searched
recursively, so any queries contained in subfolders will also be executed.
recursively, so any queries contained in subfolders will also be executed.
.. pull-quote::
@@ -165,12 +189,12 @@ recursively, so any queries contained in subfolders will also be executed.
<about-ql-packs>` when executing ``database analyze``
as it contains some special queries that aren't designed to be used with
the command. Rather, to run a wide range of useful queries, run one of the
LGTM.com query suites.
LGTM.com query suites.
For example, to execute all Python queries contained in the ``Functions``
directory you would run::
codeql database analyze <python-database> ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif
codeql database analyze <python-database> ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif
A SARIF results file is generated. Specifying ``--format=sarif-latest`` ensures
that the results are formatted according to the most recent SARIF specification
@@ -197,19 +221,19 @@ corresponds to an alert. Each line is a comma-separated list with the following
- Description
- Example
* - Name
- Name of the query that identified the result.
- Name of the query that identified the result.
- ``Inefficient regular expression``
* - Description
- Description of the query.
- ``A regular expression that requires exponential time to match certain
inputs can be a performance bottleneck, and may be vulnerable to
- Description of the query.
- ``A regular expression that requires exponential time to match certain
inputs can be a performance bottleneck, and may be vulnerable to
denial-of-service attacks.``
* - Severity
- Severity of the query.
- ``error``
* - Message
- Alert message.
- ``This part of the regular expression may cause exponential backtracking
- Alert message.
- ``This part of the regular expression may cause exponential backtracking
on strings containing many repetitions of '\\\\'.``
* - Path
- Path of the file containing the alert.
@@ -226,14 +250,14 @@ corresponds to an alert. Each line is a comma-separated list with the following
included when the same value as the start line.
- ``64``
* - End column
- Where available, the column of the end line that marks the end of the
- Where available, the column of the end line that marks the end of the
alert code. Otherwise the end line is repeated.
- ``617``
Results files can be integrated into your own code-review or debugging
infrastructure. For example, SARIF file output can be used to highlight alerts
in the correct location in your source code using a SARIF viewer plugin for your
IDE.
IDE.
Further reading
---------------

2
docs/codeql/codeql-cli/codeql-cli-reference.rst
View File

@@ -9,12 +9,14 @@ Learn more about the files you can use when running CodeQL processes and the res
:titlesonly:
:hidden:
about-codeql-packs
about-ql-packs
query-reference-files
sarif-output
exit-codes
- :doc:`About CodeQL packs <about-codeql-packs>`: CodeQL packs are created with the CodeQL CLI and are used to create, depend on, publish, and run CodeQL queries and libraries.
- :doc:`About QL packs <about-ql-packs>`: QL packs are used to organize the files used in CodeQL analysis. They
contain queries, library files, query suites, and important metadata.
- :doc:`Query reference files <query-reference-files>`: A query reference file is text file that defines the location of one query to test.

70
docs/codeql/codeql-cli/creating-and-working-with-codeql-packs.rst Normal file
View File

@@ -0,0 +1,70 @@
.. _creating-and-working-with-codeql-packs:
Creating and working with CodeQL packs
======================================
You can use CodeQL packs to create, share, depend on, and run CodeQL queries and libraries.
.. include:: ../reusables/beta-note-package-management.rst
About CodeQL packs and the CodeQL CLI
-------------------------------------
With CodeQL packs and the package management commands in the CodeQL CLI, you can publish your custom queries and integrate them into your codebase analysis.
There are two types of CodeQL packs: query packs and library packs.
* Query packs are designed to be run. When a query pack is published, the bundle includes all the transitive dependencies and a compilation cache. This ensures consistent and efficient execution of the queries in the pack.
* Library packs are designed to be used by query packs (or other library packs) and do not contain queries themselves. The libraries are not compiled and there is no compilation cache included when the pack is published.
You can use the ``pack`` command in the CodeQL CLI to create CodeQL packs, add dependencies to packs, and install or update dependencies. You can also publish and download CodeQL packs using the ``pack`` command. For more information, see ":doc:`Publishing and using CodeQL packs <publishing-and-using-codeql-packs>`."
Creating a CodeQL pack
----------------------
You can create a CodeQL pack by running the following command from the checkout root of your project:
::
codeql pack init <scope>/<pack>
You must specify:
- ``<scope>``: the name of the GitHub organization or user account that you will publish to.
- ``<pack>``: the name for the pack that you are creating.
The ``codeql pack init`` command creates the directory structure and configuration files for a CodeQL pack. By default, the command creates a query pack. If you want to create a library pack, you must edit the ``qlpack.yml`` file to explicitly declare the file as a library pack by including the ``library:true`` property.
Modifying an existing QL pack to create a CodeQL pack
-----------------------------------------------------
If you already have a ``qlpack.yml`` file, you can edit it manually to convert it into a CodeQL pack.
#. Edit the ``name`` property so that it matches the format ``<scope>/<name>``, where ``<scope>`` is the name of the GitHub organization or user account that you will publish to.
#. In the ``qlpack.yml`` file, include a ``version`` property with a semver identifier, as well as an optional ``dependencies`` block.
For more information about the properties, see ":ref:`About CodeQL packs <about-codeql-packs>`."
Adding and installing dependencies to a CodeQL pack
---------------------------------------------------
You can add dependencies on CodeQL packs using the command ``codeql pack add``. You must specify the scope, name, and version range.
::
codeql pack add <scope>/<name>@x.x.x <scope>/<other-name>
The version range is optional. If you leave off the version range, the latest version will be added. Otherwise, the latest version that satisfies the requested range will be added.
This command updates the ``qlpack.yml`` file with the requested dependencies and downloads them into the package cache. Please note that this command will reformat the file and remove all comments.
You can also manually edit the ``qlpack.yml`` file to include dependencies and install the dependencies with the command:
::
codeql pack install
This command downloads all dependencies to the shared cache on the local disk.
.. pull-quote::
Note
Running the ``codeql pack add`` and ``codeql pack install`` commands will generate or update the ``qlpack.lock.yml`` file. This file should be checked-in to version control. The ``qlpack.lock.yml`` file contains the precise version numbers used by the pack.

78
docs/codeql/codeql-cli/creating-codeql-databases.rst
View File

@@ -17,6 +17,12 @@ Before you generate a CodeQL database, you need to:
- Check out the version of your codebase you want to analyze. The directory
should be ready to build, with all dependencies already installed.
For information about using the CodeQL CLI in a third-party CI system to create results
to display in GitHub as code scanning alerts, see `Configuring CodeQL CLI 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>`__
in the GitHub documentation. For information about enabling CodeQL code scanning using GitHub Actions,
see `Setting up code scanning for a repository <https://docs.github.com/en/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/setting-up-code-scanning-for-a-repository>`__
in the GitHub documentation.
Running ``codeql database create``
----------------------------------
@@ -33,21 +39,30 @@ You must specify:
be created when you execute the command---you cannot specify an existing
directory.
- ``--language``: the identifier for the language to create a database for.
When used with ``--db-cluster``, the option accepts a comma-separated list,
or can be specified more than once.
CodeQL supports creating databases for the following languages:
.. include:: ../reusables/extractors.rst
Other options may be specified depending on the location of your source file and
the language you want to analyze:
You can specify additional options depending on the location of your source file,
if the code needs to be compiled, and if you want to create CodeQL databases for
more than one language:
- ``--source-root``: the root folder for the primary source files used in
database creation. By default, the command assumes that the current
directory is the source root---use this option to specify a different location.
- ``--command``: for compiled languages only, the build commands that invoke the
compiler. Do not specify ``--command`` options for Python and
JavaScript. Commands will be run from the current folder, or ``--source-root``
- ``--db-cluster``: use for multi-language codebases when you want to create
databases for more than one language.
- ``--command``: used when you create a database for one or more compiled languages,
omit if the only languages requested are Python and JavaScript.
This specifies the build commands needed to invoke the compiler.
Commands are run from the current folder, or ``--source-root``
if specified. If you don't include a ``--command``, CodeQL will attempt to
detect the build system automatically, using a built-in autobuilder.
- ``--no-run-unnecessary-builds``: used with ``--db-cluster`` to suppress the build
command for languages where the CodeQL CLI does not need to monitor the build
(for example, Python and JavaScript/TypeScript).
For full details of all the options you can use when creating databases,
see the `database create reference documentation <../manual/database-create>`__.
@@ -62,31 +77,13 @@ it failed. For compiled languages, the console will display the output of the
build system.
When the database is successfully created, you'll find a new directory at the
path specified in the command. This directory contains a number of
path specified in the command. If you used the ``--db-cluster`` option to create
more than one database, a subdirectory is created for each language.
Each CodeQL database directory contains a number of
subdirectories, including the relational data (required for analysis) and a
source archive---a copy of the source files made at the time the database was
created---which is used for displaying analysis results.
Obtaining databases from LGTM.com
---------------------------------
`LGTM.com <https://lgtm.com>`__ analyzes thousands of open-source projects using
CodeQL. For each project on LGTM.com, you can download an archived CodeQL
database corresponding to the most recently analyzed revision of the code. These
databases can also be analyzed using the CodeQL CLI.
.. include:: ../reusables/download-lgtm-database.rst
Before running an analysis, unzip the databases and try :doc:`upgrading <upgrading-codeql-databases>` the
unzipped databases to ensure they are compatible with your local copy of the
CodeQL queries and libraries.
.. pull-quote::
Note
.. include:: ../reusables/index-files-note.rst
Creating databases for non-compiled languages
---------------------------------------------
@@ -99,9 +96,11 @@ are available.
.. pull-quote:: Important
When running ``database create`` for JavaScript, TypeScript, and Python, you must not
specify a ``--command`` option. If you do, you will override the normal
extractor invocation, which will create an empty database.
When you run ``database create`` for JavaScript, TypeScript, and Python, you should not
specify a ``--command`` option. Otherwise this overrides the normal
extractor invocation, which will create an empty database. If you create
databases for multiple languages and one of them is a compiled language,
use the ``--no-run-unnecessary-builds`` option to skip the command for the languages that don't need to be compiled.
JavaScript and TypeScript
~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -229,6 +228,27 @@ commands that you can specify for compiled languages.
This command runs a custom script that contains all of the commands required
to build the project.
Obtaining databases from LGTM.com
---------------------------------
`LGTM.com <https://lgtm.com>`__ analyzes thousands of open-source projects using
CodeQL. For each project on LGTM.com, you can download an archived CodeQL
database corresponding to the most recently analyzed revision of the code. These
databases can also be analyzed using the CodeQL CLI or used with the CodeQL
extension for Visual Studio Code.
.. include:: ../reusables/download-lgtm-database.rst
Before running an analysis, unzip the databases and try :doc:`upgrading <upgrading-codeql-databases>` the
unzipped databases to ensure they are compatible with your local copy of the
CodeQL queries and libraries.
.. pull-quote::
Note
.. include:: ../reusables/index-files-note.rst
Further reading
---------------

31
docs/codeql/codeql-cli/getting-started-with-the-codeql-cli.rst
View File

@@ -18,9 +18,14 @@ structures. To get started quickly, we recommend adopting a relatively simple
setup, as outlined in the steps below.
If you use Linux, Windows, or macOS version 10.14 ("Mojave") or earlier, simply
follow the steps below. For macOS version 10.15 ("Catalina"), steps 1 and 4 are
slightly different---for further details, see the sections labeled **Information
for macOS "Catalina" users**.
follow the steps below. For macOS version 10.15 ("Catalina") or newer, steps 1
and 4 are slightly different---for further details, see the sections labeled
**Information for macOS "Catalina" (or newer) users**.
For information about installing the CodeQL CLI in a CI system to create results
to display in GitHub as code scanning alerts, see
`Installing CodeQL CLI in your CI system <https://docs.github.com/en/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system>`__
in the GitHub documentation.
1. Download the CodeQL CLI zip package
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -61,13 +66,14 @@ Alternatively, you can download ``codeql.zip``, which contains the CLI for all s
.. container:: name
**Information for macOS "Catalina" users**
**Information for macOS "Catalina" (or newer) users**
.. pull-quote:: macOS "Catalina"
.. pull-quote:: macOS "Catalina" (or newer)
If you use macOS version 10.15 ("Catalina"), you need to ensure that your web
browser does not automatically extract zip files. If you use Safari,
complete the following steps before downloading the CodeQL CLI zip archive:
If you use macOS version 10.15 ("Catalina"), version 11 ("Big Sur"), or the upcoming
version 12 ("Monterey"), you need to ensure that your web browser does not automatically
extract zip files. If you use Safari, complete the following steps before downloading
the CodeQL CLI zip archive:
i. Open Safari.
ii. From the Safari menu, select **Preferences...**.
@@ -159,16 +165,17 @@ For example, if the path to your copy of the CodeQL repository is
.. container:: name
**Information for macOS "Catalina" users**
**Information for macOS "Catalina" (or newer) users**
.. pull-quote:: macOS "Catalina"
macOS "Catalina" users should run the following commands in the Terminal,
where ``${install_loc}`` is the path to the directory you created in step 2:
macOS "Catalina", "Big Sur", or "Monterey" users should run the following
commands in the Terminal, where ``${install_loc}`` is the path to the
directory you created in step 2:
i. ``mv ~/Downloads/codeql*.zip ${install_loc}``
ii. ``cd ${install_loc}``
iii. ``xattr -c codeql*.zip``
iii. ``/usr/bin/xattr -c codeql*.zip``
iv. ``unzip codeql*.zip``
5. Launch ``codeql``

74
docs/codeql/codeql-cli/publishing-and-using-codeql-packs.rst Normal file
View File

@@ -0,0 +1,74 @@
.. _publishing-and-using-codeql-packs:
Publishing and using CodeQL packs
=================================
You can publish your own CodeQL packs and use packs published by other people.
.. include:: ../reusables/beta-note-package-management.rst
Configuring the ``qlpack.yml`` file before publishing
-----------------------------------------------------
You can check and modify the configuration details of your CodeQL pack prior to publishing. Open the ``qlpack.yml`` file in your preferred text editor.
.. code-block:: none
library: # set to true if the pack is a library. Set to false or omit for a query pack
name: <scope>/<pack>
version: <x.x.x>
description: <Description to publish with the package>
default-suite: # optional, one or more queries in the pack to run by default
- query: <relative-path>/query-file>.ql
default-suite-file: default-queries.qls # optional, a pointer to a query-suite in this pack
license: # optional, the license under which the pack is published
dependencies: # map from CodeQL pack name to version range
- ``name:`` must follow the <scope>/<pack> format, where <scope> is the GitHub organization that you will publish to and <pack> is the name for the pack.
- A maximum of one of ``default-suite`` or ``default-suite-file`` is allowed. These are two different ways to define a default query suite to be run, the first by specifying queries directly in the `qlpack.yml` file and the second by specifying a query suite in the pack.
Running ``codeql pack publish``
-------------------------------
When you are ready to publish a pack to the GitHub Container registry, you can run the following command in the root of the pack directory:
::
codeql pack publish
The published package will be displayed in the packages section of GitHub organization specified by the scope in the ``qlpack.yml`` file.
Running ``codeql pack download <scope>/<pack>``
-----------------------------------------------
To run a pack that someone else has created, you must first download it by running the following command:
::
codeql pack download <scope>/<pack>@x.x.x
- ``<scope>``: the name of the GitHub organization that you will download from.
- ``<pack>``: the name for the pack that you want to download.
- ``@x.x.x``: an optional version number. If omitted, the latest version will be downloaded.
This command accepts arguments for multiple packs.
Using a CodeQL pack to analyze a CodeQL database
------------------------------------------------
To analyze a CodeQL database with a CodeQL pack, run the following command:
::
codeql database analyze <database> <scope>/<pack>@x.x.x
- ``<database>``: the CodeQL database to be analyzed.
- ``<scope>``: the name of the GitHub organization that the pack is published to.
- ``<pack>``: the name for the pack that you are using.
- ``@x.x.x``: an optional version number. If omitted, the latest version will be used.
The ``analyze`` command will run the default suite of any specified CodeQL packs. You can specify multiple CodeQL packs to be used for analyzing a CodeQL database. For example:
::
codeql <database> analyze <scope>/<pack> <scope>/<other-pack>

40
docs/codeql/codeql-cli/using-custom-queries-with-the-codeql-cli.rst
View File

@@ -8,7 +8,7 @@ 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>`.
command to produce :ref:`interpreted results <interpret-query-results>`.
.. include:: ../reusables/advanced-query-execution.rst
@@ -26,16 +26,16 @@ 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.
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.
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
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
@@ -47,22 +47,30 @@ For more information about these metadata properties, see ":ref:`Metadata for Co
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
---------------------------
Creating a custom QL pack
-------------------------
.. include:: ../reusables/beta-note-package-management.rst
When writing your own queries, you should save them in a custom QL pack
directory. QL packs provide a way of organizing
the files used in CodeQL analysis. This directory must contain a file
named ``qlpack.yml`` at the root. Your custom queries should be saved in the QL
pack root, or its subdirectories.
When you write your own queries, you should save them in a custom QL pack
directory. When you are ready to share your queries with other users, you can publish the pack as a CodeQL pack to GitHub Packages - the GitHub Container registry.
QL 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
QL pack root, or its subdirectories.
For each QL pack, the ``qlpack.yml`` file includes information that tells CodeQL
how to compile the queries, what 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 QL packs <custom-ql-packs>`."
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 QL packs <about-ql-packs>`."
CodeQL packages are used to create, share, depend on, and run CodeQL queries and
libraries. You can publish your own CodeQL packages and download ones created by
others via the the Container registry. For further information see
":ref:`About CodeQL packs <about-codeql-packs>`."
Contributing to the CodeQL repository
-------------------------------------

8
docs/codeql/codeql-cli/using-the-codeql-cli.rst
View File

@@ -41,6 +41,12 @@ See the following links to learn how to get set up and run CodeQL commands:
Test query help files by rendering them as markdown to ensure they are valid
before adding them to the CodeQL repository or using them in code scanning.
- :doc:`Creating and working with CodeQL packs <creating-and-working-with-codeql-packs>`:
Create, share, depend on, and run CodeQL queries and libraries.
- :doc:`Publishing and using CodeQL packs <publishing-and-using-codeql-packs>`:
Publish your own or use others CodeQL packs for code scanning.
- :doc:`Specifying command options in a CodeQL configuration file <specifying-command-options-in-a-codeql-configuration-file>`:
You can save default or frequently used options for your commands in a per-user configuration file.
@@ -57,4 +63,6 @@ See the following links to learn how to get set up and run CodeQL commands:
creating-codeql-query-suites
testing-custom-queries
testing-query-help-files
creating-and-working-with-codeql-packs
publishing-and-using-codeql-packs
Specifying command options <specifying-command-options-in-a-codeql-configuration-file>

2
docs/codeql/codeql-for-visual-studio-code/customizing-settings.rst
View File

@@ -62,6 +62,8 @@ Configuring settings for testing queries
To increase the number of threads used for testing queries, you can update the **Running Tests > Number Of Threads** setting.
To pass additional arguments to the CodeQL CLI when running tests, you can update the **Running Tests > Additional Test Arguments** setting. For more information about the available arguments, see "`test run <https://codeql.github.com/docs/codeql-cli/manual/test-run/>`_" in the CodeQL CLI help.
Configuring settings for telemetry and data collection
--------------------------------------------------------

4
docs/codeql/codeql-for-visual-studio-code/index.rst
View File

@@ -31,6 +31,9 @@ The CodeQL extension for Visual Studio Code adds rich language support for CodeQ
<testing-codeql-queries-in-visual-studio-code>`: You can run unit tests for
CodeQL queries using the Visual Studio Code extension.
- :doc:`Working with CodeQL packs in Visual Studio Code
<working-with-codeql-packs-in-visual-studio-code>`: You can view and edit CodeQL packs in Visual Studio Code.
- :doc:`Customizing settings
<customizing-settings>`: You can edit the settings for the
CodeQL extension to suit your needs.
@@ -51,6 +54,7 @@ The CodeQL extension for Visual Studio Code adds rich language support for CodeQ
exploring-the-structure-of-your-source-code
exploring-data-flow-with-path-queries
testing-codeql-queries-in-visual-studio-code
working-with-codeql-packs-in-visual-studio-code
customizing-settings
troubleshooting-codeql-for-visual-studio-code
about-telemetry-in-codeql-for-visual-studio-code

30
docs/codeql/codeql-for-visual-studio-code/working-with-codeql-packs-in-visual-studio-code.rst Normal file
View File

@@ -0,0 +1,30 @@
:tocdepth: 1
.. _working-with-codeql-packs-in-visual-studio-code:
Working with CodeQL packs in Visual Studio Code
===============================================
.. include:: ../reusables/beta-note-package-management.rst
You can view CodeQL packs and write and edit queries for them in Visual Studio Code.
About CodeQL packs
------------------
CodeQL packs are used to create, share, depend on, and run CodeQL queries and libraries. You can publish your own CodeQL packs and download packs created by others. For more information, see ":ref:`About CodeQL packs <about-codeql-packs>`."
Creating and editing CodeQL packs in Visual Studio Code
-------------------------------------------------------
To create a new CodeQL pack, you will need to use the CodeQL CLI from a terminal, which you can do within Visual Studio Code or outside of it with the ``codeql pack init`` command. Once you create an empty pack, you can edit the ``qlpack.yml`` file or run the ``codeql pack add`` command to add dependencies or change the name or version. For more information, see ":ref:`Creating and working with CodeQL packs <creating-and-working-with-codeql-packs>`."
You can create or edit queries in a CodeQL pack in Visual Studio Code as you would with any CodeQL query, using the standard code editing features such as autocomplete suggestions to find elements to use from the pack's dependencies.
You can then use the CodeQL CLI to publish your pack to share with others. For more information, see ":ref:`Publishing and using CodeQL packs <publishing-and-using-codeql-packs>`."
Viewing CodeQL packs and their dependencies in Visual Studio Code
-----------------------------------------------------------------
Whether you have used the CodeQL CLI to download a CodeQL pack that someone else has created, or created your own, you can open the ``qlpack.yml`` file in the root of a CodeQL pack directory in Visual Studio Code and view the dependencies section to see what libraries the pack depends on.
If you want to understand a query in a CodeQL pack better, you can open the query file and view the code, using the IntelliSense code editing features of Visual Studio Code. For example, if you hover over an element from a library depended on by the pack, Visual Studio Code will resolve it so you can see documentation about the element.
To view the full definition of an element of a query, you can right-click and choose **Go to Definition**. If the library pack is present within the same Visual Studio Code workspace, this will take you to the definition within the workspace. Otherwise it will take you to the definition within your package cache, the shared location where downloaded dependencies are stored, which is in your home directory by default.

2
docs/codeql/ql-language-reference/ql-language-specification.rst
View File

@@ -497,6 +497,7 @@ The following sequences of characters are keyword tokens:
max
min
module
newtype
none
not
or
@@ -514,6 +515,7 @@ The following sequences of characters are keyword tokens:
then
this
true
unique
where
Operators

2
docs/codeql/ql-language-reference/variables.rst
View File

@@ -57,7 +57,7 @@ As an aside, note that the following query leads to a compile-time error:
select i
In theory, it would have infinitely many results, as the variable ``i`` is not constrained to a
finite number of possible values. For more informaion, see ":ref:`binding`."
finite number of possible values. For more information, see ":ref:`binding`."
.. index:: variable; free, variable; bound
.. _free-variables:

25
docs/codeql/query-help/codeql-cwe-coverage.md
View File

@@ -1,25 +0,0 @@
# CodeQL CWE coverage
An overview of the coverage of MITRE's Common Weakness Enumeration (CWE) for the latest release of CodeQL.
## About CWEs
The CWE categorization contains several types of entity, collectively known as CWEs. The CWEs that we consider in this report are only those of the types:
- Weakness Class
- Weakness Base
- Weakness Variant
- Compound Element
Other types of CWE do not correspond directly to weaknesses, so are omitted.
The CWE categorization includes relationships between entities, in particular a parent-child relationship.
These relationships are associated with Views (another kind of CWE entity). For the purposes of coverage claims, we use the "[Research View](https://cwe.mitre.org/data/definitions/1000.html)."
Every security query is associated with one or more CWEs, which are the most precise CWEs that are covered by that query.
Overall coverage is claimed for the most-precise CWEs, as well as for any of their ancestors in the View.
## Overview
<!-- autogenerated CWE coverage table will be added below -->

35
docs/codeql/query-help/codeql-cwe-coverage.rst Normal file
View File

@@ -0,0 +1,35 @@
CodeQL CWE coverage
===================
You can view the full coverage of MITRE's Common Weakness Enumeration (CWE) or coverage by language for the latest release of CodeQL.
About CWEs
##########
The CWE categorization contains several types of entity, collectively known as CWEs. The CWEs that we consider in this report are only those of the types:
- Weakness Class
- Weakness Base
- Weakness Variant
- Compound Element
Other types of CWE that do not correspond directly to weaknesses are omitted.
The CWE categorization includes relationships between entities, in particular a parent-child relationship.
These relationships are associated with Views (another kind of CWE entity). For the purposes of coverage claims, we use the "`Research View <https://cwe.mitre.org/data/definitions/1000.html>`_."
Every security query is associated with one or more CWEs, which are the most precise CWEs that are covered by that query.
Overall coverage is claimed for the most-precise CWEs, as well as for any of their ancestors in the View.
Note that the CWE coverage includes both "`supported queries <https://github.com/github/codeql/blob/main/docs/supported-queries.md>`_" and "`experimental queries <https://github.com/github/codeql/blob/main/docs/experimental.md>`_."
.. toctree::
:titlesonly:
full-cwe
cpp-cwe
csharp-cwe
go-cwe
java-cwe
javascript-cwe
python-cwe

8
docs/codeql/query-help/cpp-cwe.md Normal file
View File

@@ -0,0 +1,8 @@
# CWE coverage for C and C++
An overview of CWE coverage for C and C++ in the latest release of CodeQL.
## Overview
<!-- autogenerated CWE coverage table will be added below -->

8
docs/codeql/query-help/csharp-cwe.md Normal file
View File

@@ -0,0 +1,8 @@
# CWE coverage for C#
An overview of CWE coverage for C# in the latest release of CodeQL.
## Overview
<!-- autogenerated CWE coverage table will be added below -->

8
docs/codeql/query-help/full-cwe.md Normal file
View File

@@ -0,0 +1,8 @@
# CodeQL full CWE coverage
An overview of the full coverage of MITRE's Common Weakness Enumeration (CWE) for the latest release of CodeQL.
## Overview
<!-- autogenerated CWE coverage table will be added below -->

8
docs/codeql/query-help/go-cwe.md Normal file
View File

@@ -0,0 +1,8 @@
# CWE coverage for Go
An overview of CWE coverage for Go in the latest release of CodeQL.
## Overview
<!-- autogenerated CWE coverage table will be added below -->

8
docs/codeql/query-help/java-cwe.md Normal file
View File

@@ -0,0 +1,8 @@
# CWE coverage for Java
An overview of CWE coverage for Java in the latest release of CodeQL.
## Overview
<!-- autogenerated CWE coverage table will be added below -->

8
docs/codeql/query-help/javascript-cwe.md Normal file
View File

@@ -0,0 +1,8 @@
# CWE coverage for JavaScript
An overview of CWE coverage for JavaScript in the latest release of CodeQL.
## Overview
<!-- autogenerated CWE coverage table will be added below -->

8
docs/codeql/query-help/python-cwe.md Normal file
View File

@@ -0,0 +1,8 @@
# CWE coverage for Python
An overview of CWE coverage for Python in the latest release of CodeQL.
## Overview
<!-- autogenerated CWE coverage table will be added below -->

6
docs/codeql/query-help/readme.md
View File

@@ -2,7 +2,9 @@ CodeQL query help Sphinx documentation
--------------------------------------
This project supplies the configuration and some boiler plate
index files for the CodeQL query help documentation.
index files for the CodeQL query help and CWE coverage documentation.
The query help itself is automatically generated by the
"Generate CodeQL query help documentation using Sphinx" workflow.
"Generate CodeQL query help documentation using Sphinx" workflow.
The CWE coverage tables are generated and appended to pages by the "Docs generate query help" workflow in the `semmle-code` repository.

5
docs/codeql/reusables/beta-note-package-management.rst Normal file
View File

@@ -0,0 +1,5 @@
.. pull-quote::
Note
The CodeQL package management functionality, including CodeQL packs, is currently available as a beta release and is subject to change. During the beta release, CodeQL packs are available only using GitHub Packages - the GitHub Container registry. To use this beta functionality, install the beta release of the CodeQL CLI bundle from: https://github.com/github/codeql-action/releases/tag/codeql-bundle-v2.6.0-beta.1.

3
docs/codeql/support/reusables/frameworks.rst
View File

@@ -95,6 +95,7 @@ Java built-in support
Guava, Utility and collections library
Hibernate, Database
iBatis / MyBatis, Database
Jackson, Serialization
Java Persistence API (JPA), Database
JDBC, Database
Protobuf, Serialization
@@ -172,6 +173,7 @@ Python built-in support
mysql-connector-python, Database
mysql-connector, Database
MySQL-python, Database
mysqlclient, Database
psycopg2, Database
sqlite3, Database
peewee, Database ORM
@@ -179,3 +181,4 @@ Python built-in support
pycryptodome, Cryptography library
pycryptodomex, Cryptography library
rsa, Cryptography library
MarkupSafe, Escaping Library

2
docs/codeql/writing-codeql-queries/about-codeql-queries.rst
View File

@@ -13,7 +13,7 @@ CodeQL includes queries to find the most relevant and interesting problems for e
- **Alert queries**: queries that highlight issues in specific locations in your code.
- **Path queries**: queries that describe the flow of information between a source and a sink in your code.
You can add custom queries to :doc:`QL packs <../codeql-cli/about-ql-packs>` to analyze your projects with "`Code scanning <https://docs.github.com/github/finding-security-vulnerabilities-and-errors-in-your-code>`__", use them to analyze a database with the ":ref:`CodeQL CLI <codeql-cli>`," or you can contribute to the standard CodeQL queries in our `open source repository on GitHub <https://github.com/github/codeql>`__.
You can add custom queries to :doc:`QL packs <../codeql-cli/about-ql-packs>` to analyze your projects with "`Code scanning <https://docs.github.com/en/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning>`__", use them to analyze a database with the ":ref:`CodeQL CLI <codeql-cli>`," or you can contribute to the standard CodeQL queries in our `open source repository on GitHub <https://github.com/github/codeql>`__.
This topic is a basic introduction to query files. You can find more information on writing queries for specific programming languages in the ":ref:`CodeQL language guides <codeql-language-guides>`," and detailed technical information about QL in the ":ref:`QL language reference <ql-language-reference>`."
For more information on how to format your code when contributing queries to the GitHub repository, see the `CodeQL style guide <https://github.com/github/codeql/blob/main/docs/ql-style-guide.md>`__.

4
docs/codeql/writing-codeql-queries/metadata-for-codeql-queries.rst
View File

@@ -45,10 +45,12 @@ The following properties are supported by all query files:
| | | ``high`` | |
| | | ``very-high`` | |
+-----------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``@problem.severity`` | | ``error`` | Defines the level of severity of any alerts generated by the query. This, along with the ``@precision`` property, determines whether the results are displayed by default on LGTM. |
| ``@problem.severity`` | | ``error`` | Defines the level of severity of any alerts generated by a non-security query. This, along with the ``@precision`` property, determines whether the results are displayed by default on LGTM. |
| | | ``warning`` | |
| | | ``recommendation`` | |
+-----------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``@security-severity``| ``<score>`` | Defines the level of severity, between 0.0 and 10.0, for queries with ``@tags security``. For more information about calculating ``@security-severity``, see the `GitHub changelog <https://github.blog/changelog/2021-07-19-codeql-code-scanning-new-severity-levels-for-security-alerts/>`__. |
+-----------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Additional properties for filter queries
----------------------------------------