mirror of
https://github.com/github/codeql.git
synced 2026-04-30 19:26:02 +02:00
Merge branch 'main' into lgtm-updates
This commit is contained in:
James Fletcher
@@ -58,118 +58,161 @@ The following properties are supported in ``qlpack.yml`` files.
|
||||
:widths: auto
|
||||
|
||||
* - Property
|
||||
- Example
|
||||
- Required by
|
||||
- Purpose
|
||||
- When to use
|
||||
- Explanation
|
||||
* - ``name``
|
||||
- .. code-block:: yaml
|
||||
- Required by 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. Use the pack name to specify queries to run using ``database analyze`` and to define dependencies between CodeQL packs (see examples below).
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
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. Use the pack name to specify queries to run using ``database analyze`` and to define dependencies between CodeQL packs (see examples below).
|
||||
* - ``version``
|
||||
- .. code-block:: yaml
|
||||
- Required by all packs that are published
|
||||
- A semantic version for this CodeQL pack that must adhere to the `SemVer v2.0.0 specification <https://semver.org/spec/v2.0.0.html>`__.
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
version: 0.0.0
|
||||
|
||||
- All packs
|
||||
- A semantic version for this CodeQL pack that must adhere to the `SemVer v2.0.0 specification <https://semver.org/spec/v2.0.0.html>`__.
|
||||
* - ``dependencies``
|
||||
- .. code-block:: yaml
|
||||
- Required by packs that define CodeQL package dependencies on other packs.
|
||||
- A map from pack references to the semantic version range that is compatible with this pack. Supported for CLI versions v2.6.0 and later.
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
dependencies:
|
||||
codeql/cpp-all: ^0.0.2
|
||||
|
||||
- Packs that define CodeQL package dependencies on other packs
|
||||
- A map from pack references to the semantic version range that is compatible with this pack. Supported for CLI versions v2.6.0 and later.
|
||||
* - ``defaultSuiteFile``
|
||||
- .. code-block:: yaml
|
||||
- Required by packs that export a set of default queries to run
|
||||
- The path to a query suite file relative to the package root, containing all of the queries that are run by default when this pack is passed to the ``codeql database analyze`` command. Supported from CLI version v2.6.0 and onwards. Only one of ``defaultSuiteFile`` or ``defaultSuite`` can be defined.
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
defaultSuiteFile: cpp-code-scanning.qls
|
||||
|
||||
- Packs that export a set of default queries to run
|
||||
- The path to a query suite file relative to the package root, containing all of the queries that are run by default when this pack is passed to the ``codeql database analyze`` command. Supported from CLI version v2.6.0 and onwards. Only one of ``defaultSuiteFile`` or ``defaultSuite`` can be defined.
|
||||
* - ``defaultSuite``
|
||||
- .. code-block:: yaml
|
||||
- Required by packs that export a set of default queries to run.
|
||||
- An inlined query suite containing all of the queries that are run by default when this pack is passed to the ``codeql database analyze`` command. Supported from CLI version v2.6.0 and onwards. Only one of ``defaultSuiteFile`` or ``defaultSuite`` can be defined.
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
defaultSuite:
|
||||
queries: .
|
||||
exclude:
|
||||
precision: medium
|
||||
|
||||
- Packs that export a set of default queries to run
|
||||
- An inlined query suite containing all of the queries that are run by default when this pack is passed to the ``codeql database analyze`` command. Supported from CLI version v2.6.0 and onwards. Only one of ``defaultSuiteFile`` or ``defaultSuite`` can be defined.
|
||||
* - ``library``
|
||||
- .. code-block:: yaml
|
||||
- Required by library packs
|
||||
- A boolean value that indicates whether this pack is a library pack. Library packs do not contain queries and are not compiled. Query packs can ignore this field or explicitly set it to ``false``.
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
library: true
|
||||
|
||||
- Library packs
|
||||
- A boolean value that indicates whether this pack is a library pack. Library packs do not contain queries and are not compiled. Query packs can ignore this field or explicitly set it to ``false``.
|
||||
* - ``suites``
|
||||
- .. code-block:: yaml
|
||||
- Optional for packs that define 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. CodeQL 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 the Container registry. For more information about query suites, see ":doc:`Creating CodeQL query suites <creating-codeql-query-suites>`."
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
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. CodeQL 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 the Container registry. For more information about query suites, see ":doc:`Creating CodeQL query suites <creating-codeql-query-suites>`."
|
||||
* - ``extractor``
|
||||
- .. code-block:: yaml
|
||||
|
||||
extractor: javascript
|
||||
|
||||
- All packs containing CodeQL tests
|
||||
- The CodeQL language extractor to use when running the CodeQL tests in the pack. For more information about testing queries, see ":doc:`Testing custom queries <testing-custom-queries>`."
|
||||
* - ``tests``
|
||||
- .. code-block:: yaml
|
||||
- Optional for packs containing CodeQL tests. Ignored for packs without tests.
|
||||
- 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. If this property is missing, then ``.`` is assumed.
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
tests: .
|
||||
|
||||
- Optional for packs containing CodeQL tests. Ignored for packs without tests.
|
||||
- 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. If this property is missing, then ``.`` is assumed.
|
||||
* - ``dbscheme``
|
||||
- .. code-block:: yaml
|
||||
* - ``extractor``
|
||||
- All packs containing CodeQL tests
|
||||
- The CodeQL language extractor to use when running the CodeQL tests in the pack. For more information about testing queries, see ":doc:`Testing custom queries <testing-custom-queries>`."
|
||||
|
||||
dbscheme: semmlecode.python.dbscheme
|
||||
Example:
|
||||
|
||||
- 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``
|
||||
- .. code-block:: yaml
|
||||
.. code-block:: yaml
|
||||
|
||||
upgrades: .
|
||||
extractor: javascript
|
||||
|
||||
- Core language packs only
|
||||
- The path to a directory within the pack that contains database upgrade scripts, defined relative to the pack directory. Database upgrades are used internally to ensure that a database created with a different version of the CodeQL CLI is compatible with the current version of the CLI.
|
||||
* - ``authors``
|
||||
- .. code-block:: yaml
|
||||
- Optional
|
||||
- Metadata that will be displayed on the packaging search page in the packages section of the account that the CodeQL pack is published to.
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
authors: author1@github.com,author2@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.
|
||||
* - ``license``
|
||||
- .. code-block:: yaml
|
||||
- Optional
|
||||
- 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.
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
license: 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``
|
||||
- .. code-block:: yaml
|
||||
- Optional
|
||||
- Metadata that will be displayed on the packaging search page in the packages section of the account that the CodeQL pack is published to.
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
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.
|
||||
* - ``libraryPathDependencies``
|
||||
- .. code-block:: yaml
|
||||
- Optional, deprecated
|
||||
- Use the ``dependencies`` property instead. The names of any CodeQL packs that this CodeQL pack depends on, as an array. This gives the pack access to any libraries, database schema, and query suites defined in the dependency.
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
libraryPathDependencies: codeql/javascript-all
|
||||
|
||||
- Optional, deprecated
|
||||
- Use the ``dependencies`` property instead. The names of any CodeQL packs that this CodeQL pack depends on, as an array. This gives the pack access to any libraries, database schema, and query suites defined in the dependency.
|
||||
* - ``dbscheme``
|
||||
- Required by 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).
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
dbscheme: semmlecode.python.dbscheme
|
||||
|
||||
* - ``upgrades``
|
||||
- Required by core language packs only
|
||||
- The path to a directory within the pack that contains database upgrade scripts, defined relative to the pack directory. Database upgrades are used internally to ensure that a database created with a different version of the CodeQL CLI is compatible with the current version of the CLI.
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
upgrades: .
|
||||
|
||||
.. _about-codeql-pack-lock:
|
||||
|
||||
|
||||
@@ -15,11 +15,13 @@ 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:`Set up the CodeQL CLI <getting-started-with-the-codeql-cli>` to run commands locally.
|
||||
- :doc:`Create a CodeQL database <creating-codeql-databases>` for the source
|
||||
code you want to analyze.
|
||||
|
||||
The simplest way to run ``codeql database analyze`` is using CodeQL packs. You can also
|
||||
run the command using queries from a local checkout of the CodeQL repository,
|
||||
which you may want to do if you want to customize the CodeQL core queries.
|
||||
|
||||
Running ``codeql database analyze``
|
||||
------------------------------------
|
||||
@@ -34,7 +36,7 @@ When you run ``database analyze``, it:
|
||||
|
||||
You can analyze a database by running the following command::
|
||||
|
||||
codeql database analyze <database> --format=<format> --output=<output> <queries>
|
||||
codeql database analyze <database> --format=<format> --output=<output> <query-specifiers>...
|
||||
|
||||
|
||||
You must specify:
|
||||
@@ -52,8 +54,8 @@ You must specify:
|
||||
|
||||
You can also specify:
|
||||
|
||||
- ``...<query-specifications>``: a list of queries to run over your database. This
|
||||
is a list of arguments. Where each argument can be:
|
||||
- ``<query-specifiers>...``: a space-separated list of queries to run over your database. This
|
||||
is a list of arguments, where each argument can be:
|
||||
|
||||
- a path to a query file
|
||||
- a path to a directory containing query files
|
||||
@@ -62,7 +64,7 @@ You can also specify:
|
||||
- with an optional version range
|
||||
- with an optional path to a query, directory, or query suite inside the pack
|
||||
|
||||
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.
|
||||
If omitted, the default query suite for the language of the analyzed database will be used. For the complete syntax of query specifiers, see :ref:`"Specifying which queries to run in a CodeQL pack"<specifying-which-queries>`.
|
||||
|
||||
- ``--sarif-category``: an identifying category for the results. Used when
|
||||
you want to upload more than one set of results for a commit.
|
||||
@@ -95,14 +97,77 @@ You can also specify:
|
||||
For full details of all the options you can use when analyzing databases, see
|
||||
the `database analyze reference documentation <../manual/database-analyze>`__.
|
||||
|
||||
.. _database-analyze-examples:
|
||||
|
||||
Examples
|
||||
--------
|
||||
.. _specifying-which-queries:
|
||||
|
||||
The following examples assume your CodeQL databases have been created in a
|
||||
directory that is a sibling of your local copies of the CodeQL and CodeQL for Go
|
||||
repositories.
|
||||
Specifying which queries to run in a CodeQL pack
|
||||
------------------------------------------------
|
||||
|
||||
Query specifiers are used by ``codeql database analyze`` and other commands that operate on a set of queries.
|
||||
The complete form of a query specifier is``scope/name@range:path``, where:
|
||||
|
||||
- ``scope/name`` is the qualified name of a CodeQL pack.
|
||||
- ``range`` is a `semver range <https://docs.npmjs.com/cli/v6/using-npm/semver#ranges>`_.
|
||||
- ``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
|
||||
optional. If you omit a ``range`` then the latest version of the
|
||||
specified pack is used. If you omit a ``path`` then the default query suite
|
||||
of the specified pack is used.
|
||||
|
||||
The ``path`` can be one of: a ``.ql`` query file, a directory
|
||||
containing one or more queries, or a ``.qls`` query suite file. If
|
||||
you omit a pack name, then you must provide a ``path``,
|
||||
which will be interpreted relative to the working directory
|
||||
of the current process. Glob patterns are not supported.
|
||||
|
||||
If you specify both a ``scope/name`` and ``path``, then the ``path`` cannot
|
||||
be absolute. It is considered relative to the root of the CodeQL
|
||||
pack.
|
||||
|
||||
Example query specifiers
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* ``codeql/python-queries`` - All the queries in the default query suite of the latest version of the ``codeql/python-queries`` pack.
|
||||
* ``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.
|
||||
* ``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``.
|
||||
* ``codeql/python-queries:Functions`` - All queries in the ``Functions`` directory in the latest version of the ``codeql/python-queries`` pack.
|
||||
* ``codeql/python-queries@1.2.3:Functions`` - All queries in the ``Functions`` directory in version 1.2.3 of the ``codeql/python-queries`` pack.
|
||||
* ``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.
|
||||
* ``suites/my-suite.qls`` - All queries in the ``suites/my-suite.qls`` file relative to the current working directory.
|
||||
|
||||
.. pull-quote::
|
||||
|
||||
Tip
|
||||
|
||||
The default query suite of the standard CodeQL query packs are ``codeql-suites/<lang>-code-scanning.qls``. Several other useful query suites can also be found in the ``codeql-suites`` directory of each pack. For example, the ``codeql/cpp-queries`` pack contains the following query suites:
|
||||
|
||||
* ``cpp-code-scanning.qls`` - Standard Code Scanning queries for C++. The default query suite for this pack.
|
||||
* ``cpp-security-extended.qls`` - Queries from the default ``cpp-code-scanning.qls`` suite for C++, plus lower severity and precision queries.
|
||||
* ``cpp-security-and-quality.qls`` - Queries from ``cpp-security-extended.qls``, plus maintainability and reliability queries.
|
||||
|
||||
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.
|
||||
|
||||
Examples of running database analyses
|
||||
---------------------------------------------
|
||||
|
||||
The following examples show how to run ``database analyze`` using CodeQL packs, and how to use a local checkout of the CodeQL repository. These examples assume your CodeQL databases have been created in a directory that is a sibling of your local copies of the CodeQL repository.
|
||||
|
||||
.. _run-query-pack:
|
||||
|
||||
Running a CodeQL query pack
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. include:: ../reusables/beta-note-package-management.rst
|
||||
|
||||
To run an existing CodeQL query pack from the GitHub Container registry, you can specify one or more
|
||||
pack names::
|
||||
|
||||
codeql database analyze <database> microsoft/coding-standards@1.0.0 github/security-queries --format=sarifv2.1.0 --output=query-results.sarif --download
|
||||
|
||||
This command 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 specified database. For further information about default suites, see ":ref:`Publishing and using CodeQL packs <publishing-and-using-codeql-packs>`".
|
||||
|
||||
The ``--download`` flag is optional. Using it will ensure the query pack is downloaded if it isn't yet available locally.
|
||||
|
||||
Running a single query
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
@@ -110,41 +175,23 @@ Running a single query
|
||||
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 --download <javascript-database> codeql/javascript-queries: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
|
||||
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``).
|
||||
The analysis generates a CSV file (``js-results.csv``) in a new directory (``js-analysis``).
|
||||
|
||||
Alternatively, if you have the CodeQL repository checked out, you can execute the same queries by specifying the path to the query directly::
|
||||
|
||||
codeql database analyze <javascript-database> ../ql/javascript/ql/src/Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv
|
||||
|
||||
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>`."
|
||||
|
||||
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::
|
||||
|
||||
codeql database analyze --download <javascript-database> codeql/javascript-queries:Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv
|
||||
|
||||
Use the ``--download`` flag to download the query pack if it isn't yet available locally.
|
||||
|
||||
.. _run-query-pack:
|
||||
|
||||
Running a CodeQL pack
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. include:: ../reusables/beta-note-package-management.rst
|
||||
|
||||
To run an existing CodeQL query pack from the GitHub Container registry, you can specify one or more
|
||||
pack names and use the ``--download`` flag::
|
||||
|
||||
codeql database analyze <database> microsoft/coding-standards@1.0.0 github/security-queries --format=sarifv2.1.0 --output=query-results.sarif --download
|
||||
|
||||
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.
|
||||
For further information about default suites, see ":ref:`Publishing and using CodeQL packs <publishing-and-using-codeql-packs>`".
|
||||
|
||||
Running all queries in a directory
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@@ -163,7 +210,13 @@ recursively, so any queries contained in subfolders will also be executed.
|
||||
pack's default queries in the analysis, or run one of the
|
||||
code scanning query suites.
|
||||
|
||||
For example, to execute all Python queries contained in the ``Functions`` directory you would run::
|
||||
For example, to execute all Python queries contained in the ``Functions`` directory in the
|
||||
``codeql/python-queries`` query pack you would run::
|
||||
|
||||
codeql database analyze <python-database> codeql/python-queries:Functions --format=sarif-latest --output=python-analysis/python-results.sarif --download
|
||||
|
||||
Alternatively, if you have the CodeQL repository checked out, you can execute the
|
||||
same queries by specifying the path to the directory directly::
|
||||
|
||||
codeql database analyze <python-database> ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif
|
||||
|
||||
@@ -171,8 +224,6 @@ When the analysis has finished, a SARIF results file is generated. Specifying ``
|
||||
that the results are formatted according to the most recent SARIF specification
|
||||
supported by CodeQL.
|
||||
|
||||
.. _including-query-help-for-custom-codeql-queries-in-sarif-files:
|
||||
|
||||
Running a subset of queries in a CodeQL pack
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@@ -224,13 +275,12 @@ For more information about CodeQL packs, see :doc:`About CodeQL Packs <about-cod
|
||||
Running query suites
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To run a query suite over a CodeQL database for a C/C++ codebase,
|
||||
To run a query suite on 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
|
||||
codeql database analyze <cpp-database> codeql/cpp-queries:codeql-suites/cpp-code-scanning.qls --format=sarifv2.1.0 --output=cpp-results.sarif --download
|
||||
|
||||
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.
|
||||
This command downloads the ``codeql/cpp-queries`` CodeQL query pack, runs the analysis, and generates a file in the SARIF version 2.1.0 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/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/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.
|
||||
|
||||
@@ -238,19 +288,8 @@ CodeQL query suites are ``.qls`` files that use directives to select queries to
|
||||
based on certain metadata properties. The standard CodeQL 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 CodeQL packs <standard-codeql-packs>`."
|
||||
For more information, see ":ref:`Creating CodeQL query suites <creating-codeql-query-suites>`."
|
||||
|
||||
The standard query suites are stored at the following paths in
|
||||
the CodeQL repository::
|
||||
|
||||
ql/<language>/ql/src/codeql-suites/<language>-code-scanning.qls
|
||||
|
||||
and at the following path in the CodeQL for Go repository::
|
||||
|
||||
ql/src/codeql-suites/go-code-scanning.qls
|
||||
|
||||
The repository also includes the query suites used by `LGTM.com <https://lgtm.com>`__.
|
||||
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>`."
|
||||
@@ -265,11 +304,11 @@ If the analysis found fewer results for standard queries than you expected, revi
|
||||
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>`_."
|
||||
|
||||
.. _including-query-help-for-custom-codeql-queries-in-sarif-files:
|
||||
|
||||
Including query help for custom CodeQL queries in SARIF files
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
@@ -132,7 +132,8 @@ Python
|
||||
|
||||
When creating databases for Python you must ensure:
|
||||
|
||||
- You have the all of the required versions of Python installed.
|
||||
- You have Python 3 installed and available to the CodeQL extractor.
|
||||
- You have the version of Python used by your code installed.
|
||||
- You have access to the `pip <https://pypi.org/project/pip/>`__
|
||||
packaging management system and can install any
|
||||
packages that the codebase depends on.
|
||||
|
||||
@@ -21,9 +21,9 @@
|
||||
|
||||
Eclipse compiler for Java (ECJ) [5]_",``.java``
|
||||
JavaScript,ECMAScript 2022 or lower,Not applicable,"``.js``, ``.jsx``, ``.mjs``, ``.es``, ``.es6``, ``.htm``, ``.html``, ``.xhtm``, ``.xhtml``, ``.vue``, ``.hbs``, ``.ejs``, ``.njk``, ``.json``, ``.yaml``, ``.yml``, ``.raml``, ``.xml`` [6]_"
|
||||
Python,"2.7, 3.5, 3.6, 3.7, 3.8, 3.9, 3.10",Not applicable,``.py``
|
||||
Ruby [7]_,"up to 3.0.2",Not applicable,"``.rb``, ``.erb``, ``.gemspec``, ``Gemfile``"
|
||||
TypeScript [8]_,"2.6-4.8",Standard TypeScript compiler,"``.ts``, ``.tsx``, ``.mts``, ``.cts``"
|
||||
Python [7]_,"2.7, 3.5, 3.6, 3.7, 3.8, 3.9, 3.10",Not applicable,``.py``
|
||||
Ruby [8]_,"up to 3.0.2",Not applicable,"``.rb``, ``.erb``, ``.gemspec``, ``Gemfile``"
|
||||
TypeScript [9]_,"2.6-4.8",Standard TypeScript compiler,"``.ts``, ``.tsx``, ``.mts``, ``.cts``"
|
||||
|
||||
.. container:: footnote-group
|
||||
|
||||
@@ -33,5 +33,6 @@
|
||||
.. [4] Builds that execute on Java 7 to 19 can be analyzed. The analysis understands Java 19 standard language features.
|
||||
.. [5] ECJ is supported when the build invokes it via the Maven Compiler plugin or the Takari Lifecycle plugin.
|
||||
.. [6] JSX and Flow code, YAML, JSON, HTML, and XML files may also be analyzed with JavaScript files.
|
||||
.. [7] Requires glibc 2.17.
|
||||
.. [8] TypeScript analysis is performed by running the JavaScript extractor with TypeScript enabled. This is the default for LGTM.
|
||||
.. [7] The extractor requires Python 3 to run. To analyze Python 2.7 you should install both versions of Python.
|
||||
.. [8] Requires glibc 2.17.
|
||||
.. [9] TypeScript analysis is performed by running the JavaScript extractor with TypeScript enabled. This is the default for LGTM.
|
||||
|
||||
@@ -294,7 +294,10 @@ through an additional step targeting a `PostUpdateNode`).
|
||||
|
||||
It is recommended to introduce `PostUpdateNode`s for all `ArgumentNode`s (this
|
||||
can be skipped for immutable arguments), and all field qualifiers for both
|
||||
reads and stores.
|
||||
reads and stores. Note also that in the case of compund arguments, such as
|
||||
`b ? x : y`, it is recommented to have post-update nodes for `x` and `y` (and
|
||||
not the compound argument itself), and let `[post update] x` have both `x`
|
||||
and `b ? x : y` as pre-update nodes (and similarly for `[post update] y`).
|
||||
|
||||
Remember to define local flow for `PostUpdateNode`s as well in
|
||||
`simpleLocalFlowStep`. In general out-going local flow from `PostUpdateNode`s
|
||||
@@ -416,6 +419,7 @@ class Content extends TContent {
|
||||
|
||||
newtype TContentSet =
|
||||
TSingletonContent(Content c) or
|
||||
TKnownOrUnknownArrayElementContent(TKnownArrayElementContent c) or
|
||||
TAnyArrayElementContent()
|
||||
|
||||
class ContentSet extends TContentSet {
|
||||
@@ -423,6 +427,9 @@ class ContentSet extends TContentSet {
|
||||
this = TSingletonContent(result)
|
||||
or
|
||||
// for reverse stores
|
||||
this = TKnownOrUnknownArrayElementContent(result)
|
||||
or
|
||||
// for reverse stores
|
||||
this = TAnyArrayElementContent() and
|
||||
result = TUnknownArrayElementContent()
|
||||
}
|
||||
@@ -430,6 +437,13 @@ class ContentSet extends TContentSet {
|
||||
Content getAReadContent() {
|
||||
this = TSingletonContent(result)
|
||||
or
|
||||
exists(TKnownArrayElementContent c |
|
||||
this = TKnownOrUnknownArrayElementContent(c) |
|
||||
result = c
|
||||
or
|
||||
result = TUnknownArrayElementContent()
|
||||
)
|
||||
or
|
||||
this = TAnyArrayElementContent() and
|
||||
(result = TUnknownArrayElementContent() or result = TKnownArrayElementContent(_))
|
||||
}
|
||||
@@ -444,12 +458,10 @@ a[0] = tainted
|
||||
# storeStep(not_tainted, TSingletonContent(TKnownArrayElementContent(1)), [post update] a)
|
||||
a[1] = not_tainted
|
||||
|
||||
# readStep(a, TSingletonContent(TKnownArrayElementContent(0)), a[0])
|
||||
# readStep(a, TSingletonContent(TUnknownArrayElementContent()), a[0])
|
||||
# readStep(a, TKnownOrUnknownArrayElementContent(TKnownArrayElementContent(0)), a[0])
|
||||
sink(a[0]) # bad
|
||||
|
||||
# readStep(a, TSingletonContent(TKnownArrayElementContent(1)), a[1])
|
||||
# readStep(a, TSingletonContent(TUnknownArrayElementContent()), a[1])
|
||||
# readStep(a, TKnownOrUnknownArrayElementContent(TKnownArrayElementContent(1)), a[1])
|
||||
sink(a[1]) # good
|
||||
|
||||
# readStep(a, TAnyArrayElementContent(), a[unknown])
|
||||
@@ -458,26 +470,24 @@ sink(a[unknown]) # bad; unknown may be 0
|
||||
# storeStep(tainted, TSingletonContent(TUnknownArrayElementContent()), [post update] b)
|
||||
b[unknown] = tainted
|
||||
|
||||
# readStep(b, TSingletonContent(TKnownArrayElementContent(0)), b[0])
|
||||
# readStep(b, TSingletonContent(TUnknownArrayElementContent()), b[0])
|
||||
# readStep(b, TKnownOrUnknownArrayElementContent(TKnownArrayElementContent(0)), b[0])
|
||||
sink(b[0]) # bad; unknown may be 0
|
||||
|
||||
# storeStep(tainted, TSingletonContent(TKnownArrayElementContent(0)), [post update] c[unknown])
|
||||
# storeStep(not_tainted, TSingletonContent(TKnownArrayElementContent(1)), [post update] c[unknown])
|
||||
# readStep(c, TAnyArrayElementContent(), c[unknown])
|
||||
# storeStep([post update] c[unknown], TAnyArrayElementContent(), [post update] c) # auto-generated reverse store (see Example 2)
|
||||
c[unknown][0] = tainted
|
||||
c[unknown][1] = not_tainted
|
||||
# storeStep(tainted, TSingletonContent(TUnknownArrayElementContent()), [post update] c[0])
|
||||
# storeStep(not_tainted, TSingletonContent(TUnknownArrayElementContent()), [post update] c[1])
|
||||
# readStep(c, TKnownOrUnknownArrayElementContent(TKnownArrayElementContent(0)), c[0])
|
||||
# readStep(c, TKnownOrUnknownArrayElementContent(TKnownArrayElementContent(1)), c[1])
|
||||
# storeStep([post update] c[0], TSingletonContent(TKnownArrayElementContent(0)), [post update] c) # auto-generated reverse store (see Example 2)
|
||||
# storeStep([post update] c[1], TSingletonContent(TKnownArrayElementContent(1)), [post update] c) # auto-generated reverse store (see Example 2)
|
||||
c[0][unknown] = tainted
|
||||
c[1][unknown] = not_tainted
|
||||
|
||||
|
||||
# readStep(c[0], TSingletonContent(TKnownArrayElementContent(0)), c[0][0])
|
||||
# readStep(c[0], TSingletonContent(TUnknownArrayElementContent()), c[0][0])
|
||||
# readStep(c[0], TSingletonContent(TKnownArrayElementContent(1)), c[0][1])
|
||||
# readStep(c[0], TSingletonContent(TUnknownArrayElementContent()), c[0][1])
|
||||
# readStep(c, TSingletonContent(TKnownArrayElementContent(0)), c[0])
|
||||
# readStep(c, TSingletonContent(TUnknownArrayElementContent()), c[0])
|
||||
# readStep(c[0], TKnownOrUnknownArrayElementContent(TKnownArrayElementContent(0)), c[0][0])
|
||||
# readStep(c[1], TKnownOrUnknownArrayElementContent(TKnownArrayElementContent(0)), c[1][0])
|
||||
# readStep(c, TKnownOrUnknownArrayElementContent(TKnownArrayElementContent(0)), c[0])
|
||||
# readStep(c, TKnownOrUnknownArrayElementContent(TKnownArrayElementContent(1)), c[1])
|
||||
sink(c[0][0]) # bad; unknown may be 0
|
||||
sink(c[0][1]) # good
|
||||
sink(c[1][0]) # good
|
||||
```
|
||||
|
||||
### Field flow barriers
|
||||
|
||||
Reference in New Issue
Block a user