mirror of
https://github.com/github/codeql.git
synced 2026-04-24 16:25:15 +02:00
Merge branch 'main' into aeisenberg/update-analyzing-databases
This commit is contained in:
Andrew Eisenberg
@@ -1,6 +1,6 @@
|
||||
.. _about-codeql-workspaces:
|
||||
|
||||
About CodeQL Workspaces
|
||||
About CodeQL workspaces
|
||||
=======================
|
||||
|
||||
.. include:: ../reusables/beta-note-package-management.rst
|
||||
@@ -12,16 +12,17 @@ The main benefit of a CodeQL workspace is that it makes it easier for you to dev
|
||||
In most cases, you should store the CodeQL workspace and the CodeQL packs contained in it in one git repository. This makes it easier to share your CodeQL development environment.
|
||||
|
||||
The ``codeql-workspace.yml`` file
|
||||
----------------------------------
|
||||
---------------------------------
|
||||
|
||||
A CodeQL workspace is defined by a ``codeql-workspace.yml`` yaml file. This file contains a ``provide`` block, and optionally an ``ignore`` block.
|
||||
A CodeQL workspace is defined by a ``codeql-workspace.yml`` yaml file. This file contains a ``provide`` block, and optionally ``ignore`` and ``registries`` blocks.
|
||||
|
||||
* The ``provide`` block contains a list of glob patterns that define the CodeQL packs that are available in the workspace.
|
||||
* The ``ignore`` block contains a list of glob patterns that define CodeQL packs that are not available in the workspace.
|
||||
* The ``registries`` block contains a list of GHES URLs and package patterns that control which container registry is used for publishing CodeQL packs. For more information, see :ref:`Working with CodeQL packs on GitHub Enterprise Server <working-with-codeql-packs-on-ghes>`.
|
||||
|
||||
Each entry in the ``provide`` or ``ignore`` section must map to the location of a ``qlpack.yml`` file. All glob patterns are defined relative to the directory that contains the workspace file. For a list of patterns accepted in this file, see "`@actions/glob <https://github.com/actions/toolkit/tree/main/packages/glob#patterns>`__ ."
|
||||
|
||||
For example, the following ``codeql-workspace.yml`` file defines a workspace that contains all the CodeQL packs recursively found in the ``codeql-packs`` directory, except for the packs in the ``experimental`` directory:
|
||||
For example, the following ``codeql-workspace.yml`` file defines a workspace that contains all the CodeQL packs recursively found in the ``codeql-packs`` directory, except for the packs in the ``experimental`` directory. The ``registries`` block specifies that ``codeql/*`` packs should be downloaded from https://ghcr.io/v2/, which is GitHub's default container registry. All other packs should be downloaded from and published to the regsitry at ``GHE_HOSTNAME``.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@@ -30,6 +31,13 @@ For example, the following ``codeql-workspace.yml`` file defines a workspace tha
|
||||
ignore:
|
||||
- "*/codeql-packs/**/experimental/**/qlpack.yml"
|
||||
|
||||
registries:
|
||||
- packages: 'codeql/*'
|
||||
url: https://ghcr.io/v2/
|
||||
|
||||
- packages: '*'
|
||||
url: https://containers.GHE_HOSTNAME/v2/
|
||||
|
||||
To verify that your ``codeql-workspace.yml`` file includes the CodeQL packs that you expect, run the ``codeql pack ls`` command in the same directory as your workspace. The result of the command is a list of all CodeQL packs in the workspace.
|
||||
|
||||
.. _source-dependencies:
|
||||
|
||||
12
docs/codeql/codeql-cli/about-ql-packs.rst
Normal file
12
docs/codeql/codeql-cli/about-ql-packs.rst
Normal file
@@ -0,0 +1,12 @@
|
||||
.. _about-ql-packs:
|
||||
|
||||
About QL packs
|
||||
==============
|
||||
|
||||
This page has been moved to ":doc:`About CodeQL packs <about-codeql-packs>`."
|
||||
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
about-ql-packs
|
||||
@@ -219,6 +219,56 @@ 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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you are using CodeQL CLI v2.8.1 or later, you can include a path at the end of a pack specification to run a subset of queries inside the pack. This applies to any command that locates or runs queries within a pack.
|
||||
|
||||
The complete way to specify a set of queries is in the form ``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.
|
||||
|
||||
If you specify a ``scope/name`` and ``path``, then the ``path`` cannot
|
||||
be absolute. It is considered relative to the root of the CodeQL
|
||||
pack.
|
||||
|
||||
To analyze a database using all queries in the `experimental/Security` folder within the `codeql/cpp-queries` CodeQL pack you can use::
|
||||
|
||||
codeql database analyze --format=sarif-latest --output=results <db> \
|
||||
codeql/cpp-queries:experimental/Security
|
||||
|
||||
To run the `RedundantNullCheckParam.ql` query in the `codeql/cpp-queries` CodeQL pack use::
|
||||
|
||||
codeql database analyze --format=sarif-latest --output=results <db> \
|
||||
'codeql/cpp-queries:experimental/Likely Bugs/RedundantNullCheckParam.ql'
|
||||
|
||||
To analyze your database using the `cpp-security-and-quality.qls` query suite from a version of the `codeql/cpp-queries` CodeQL pack that is >= 0.0.3 and < 0.1.0 (the highest compatible version will be chosen) you can use::
|
||||
|
||||
codeql database analyze --format=sarif-latest --output=results <db> \
|
||||
'codeql/cpp-queries@~0.0.3:codeql-suites/cpp-security-and-quality.qls'
|
||||
|
||||
If you need to reference a query file, directory, or suite whose path contains a literal `@` or `:`, you can prefix the query specification with `path:` like so::
|
||||
|
||||
codeql database analyze --format=sarif-latest --output=results <db> \
|
||||
path:C:/Users/ci/workspace@2/security/query.ql
|
||||
|
||||
For more information about CodeQL packs, see :doc:`About CodeQL Packs <about-codeql-packs>`.
|
||||
|
||||
Running query suites
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
@@ -11,11 +11,11 @@ or download them from GitHub.com.
|
||||
CodeQL analysis relies on extracting relational data from your code, and
|
||||
using it to build a :ref:`CodeQL database <codeql-database>`. CodeQL
|
||||
databases contain all of the important information about a codebase, which can
|
||||
be analyzed by executing CodeQL queries against it. GitHub creates and
|
||||
be analyzed by executing CodeQL queries against it. GitHub creates and
|
||||
stores CodeQL databases for a large number of open-source projects. For more information,
|
||||
see ":ref:`Downloading CodeQL databases from GitHub.com <downloading-codeql-databases-from-github-com>`."
|
||||
|
||||
You can also create CodeQL databases yourself using the CodeQL CLI.
|
||||
You can also create CodeQL databases yourself using the CodeQL CLI.
|
||||
Before you generate a CodeQL database, you need to:
|
||||
|
||||
- Install and set up the CodeQL CLI. For more information, see
|
||||
@@ -214,12 +214,12 @@ commands that you can specify for compiled languages.
|
||||
|
||||
codeql database create cpp-database --language=cpp --command=make
|
||||
|
||||
- C# project built using ``dotnet build``::
|
||||
- C# project built using ``dotnet build``:
|
||||
|
||||
It is a good idea to add `/t:rebuild` to ensure that all code will be built, or do a
|
||||
prior `dotnet clean` (code that is not built will not be included in the CodeQL database):
|
||||
It is a good idea to add `/t:rebuild` to ensure that all code will be built, or do a
|
||||
prior `dotnet clean` (code that is not built will not be included in the CodeQL database)::
|
||||
|
||||
codeql database create csharp-database --language=csharp --command='dotnet build /t:rebuild'
|
||||
codeql database create csharp-database --language=csharp --command='dotnet build /t:rebuild'
|
||||
|
||||
- Go project built using the ``CODEQL_EXTRACTOR_GO_BUILD_TRACING=on`` environment variable::
|
||||
|
||||
@@ -391,9 +391,9 @@ Downloading databases from GitHub.com
|
||||
-------------------------------------
|
||||
|
||||
.. include:: ../reusables/download-github-database.rst
|
||||
|
||||
|
||||
Before running an analysis with the CodeQL CLI, you must unzip the databases.
|
||||
|
||||
|
||||
Further reading
|
||||
---------------
|
||||
|
||||
|
||||
@@ -118,8 +118,10 @@ typically a query metadata property. The value can be:
|
||||
|
||||
To match a constraint, a metadata value must match one of the strings or
|
||||
regular expressions. When there is more than one metadata key, each key must be matched.
|
||||
For more information about query metadata properties, see ":ref:`Metadata for CodeQL queries
|
||||
<metadata-for-codeql-queries>`."
|
||||
The standard metadata keys available to match on are: ``description``, ``id``, ``kind``,
|
||||
``name``, ``tags``, ``precision``, and ``problem.severity``.
|
||||
For more information about query metadata properties, see
|
||||
":ref:`Metadata for CodeQL queries <metadata-for-codeql-queries>`."
|
||||
|
||||
In addition to metadata tags, the keys in the constraint block can also be:
|
||||
|
||||
@@ -131,8 +133,37 @@ In addition to metadata tags, the keys in the constraint block can also be:
|
||||
- ``tags contain all``---each of the given match strings must match one of the
|
||||
components of the ``@tags`` metadata property.
|
||||
|
||||
Examples
|
||||
~~~~~~~~
|
||||
Examples of filtering which queries are run
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
A common use case is to create a query suite that runs all queries in a CodeQL pack,
|
||||
except for a few specific queries that the user does not want to run. In general, we
|
||||
recommend filtering on the query ``id``, which is a unique and stable identifier for
|
||||
each query. The following three query suite definitions are semantically identical and
|
||||
filter by the query ``id``:
|
||||
|
||||
This filter matches all the queries in the default suite of ``codeql/cpp-queries``, except for the two queries with the excluded identifiers::
|
||||
|
||||
- qlpack: codeql/cpp-queries
|
||||
- exclude:
|
||||
id:
|
||||
- cpp/cleartext-transmission
|
||||
- cpp/cleartext-storage-file
|
||||
|
||||
In this example, a separate ``exclude`` instruction is used for each query::
|
||||
|
||||
- qlpack: codeql/cpp-queries
|
||||
- exclude:
|
||||
id: cpp/cleartext-transmission
|
||||
- exclude:
|
||||
id: cpp/cleartext-storage-file
|
||||
|
||||
In this example, a regular expression excludes the same two queries. It would also exclude any future queries added to the suite with identifiers that begin: ``cpp/cleartext-``::
|
||||
|
||||
- qlpack: codeql/cpp-queries
|
||||
- exclude:
|
||||
id:
|
||||
- /^cpp\/cleartext-.*/
|
||||
|
||||
To define a suite that selects all queries in the default suite of the
|
||||
``codeql/cpp-queries`` CodeQL pack, and then refines them to only include
|
||||
@@ -150,6 +181,15 @@ and ``@precision high`` from the ``my-custom-queries`` directory, use::
|
||||
kind: problem
|
||||
precision: very-high
|
||||
|
||||
Note that the following query suite definition behaves differently from the definition above. This definition selects queries that are ``@kind problem`` *or*
|
||||
are ``@precision very-high``::
|
||||
|
||||
- queries: my-custom-queries
|
||||
- include:
|
||||
kind: problem
|
||||
- include:
|
||||
precision: very-high
|
||||
|
||||
To create a suite that selects all queries with ``@kind problem`` from the
|
||||
``my-custom-queries`` directory except those with ``@problem.severity
|
||||
recommendation``, use::
|
||||
@@ -172,6 +212,15 @@ use::
|
||||
- high
|
||||
- very-high
|
||||
|
||||
.. pull-quote::
|
||||
|
||||
Tip
|
||||
|
||||
You can use the ``codeql resolve queries /path/to/suite.qls`` command to see
|
||||
which queries are selected by a query suite definition. For more information,
|
||||
see the `resolve queries <../../codeql-cli/manual/resolve-queries>`__
|
||||
reference documentation.
|
||||
|
||||
Reusing existing query suite definitions
|
||||
-----------------------------------------
|
||||
|
||||
@@ -208,14 +257,8 @@ Existing query suite definitions can be reused by specifying:
|
||||
conditions, saved in a ``.yml`` file, to multiple query definitions. For more
|
||||
information, see the `example <#example>`__ below.
|
||||
|
||||
- An ``eval`` instruction---performs the same function as an ``import``
|
||||
instruction, but takes a full suite definition as the argument, rather than the
|
||||
path to a ``.qls`` file on disk.
|
||||
|
||||
To see what queries are included in a query suite, you can run the ``codeql resolve queries my-suite.qls`` command.
|
||||
|
||||
Example
|
||||
~~~~~~~
|
||||
Reusability Examples
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To use the same conditions in multiple query suite definitions, create a
|
||||
separate ``.yml`` file containing your instructions. For example, save the
|
||||
@@ -252,6 +295,30 @@ instruction::
|
||||
from: my-org/my-custom-instructions
|
||||
version: ^1.2.3 # optional
|
||||
|
||||
A common use case for an ``import`` instruction is to apply a further filter to queries from another
|
||||
query suite. For example, this suite will further filter the ``cpp-security-and-quality`` suite
|
||||
and exclude ``low`` and ``medium`` precision queries::
|
||||
|
||||
- import: codeql-suites/cpp-security-and-quality.qls
|
||||
from: codeql/cpp-queries
|
||||
- exclude:
|
||||
precision:
|
||||
- low
|
||||
- medium
|
||||
|
||||
If you want to ``include`` queries imported from another suite, the syntax is a little different::
|
||||
|
||||
- import: codeql-suites/cpp-security-and-quality.qls
|
||||
from: codeql/cpp-queries
|
||||
- exclude: {}
|
||||
- include:
|
||||
precision:
|
||||
- very-high
|
||||
- high
|
||||
|
||||
Notice the empty ``exclude`` instruction. This is required to ensure that the subsequent ``include``
|
||||
instruction is able to filter queries from the imported suite.
|
||||
|
||||
Naming a query suite
|
||||
--------------------
|
||||
|
||||
|
||||
@@ -74,6 +74,8 @@ The ``analyze`` command will run the default suite of any specified CodeQL packs
|
||||
|
||||
codeql <database> analyze <scope>/<pack> <scope>/<other-pack>
|
||||
|
||||
.. _working-with-codeql-packs-on-ghes:
|
||||
|
||||
Working with CodeQL packs on GitHub Enterprise Server
|
||||
-----------------------------------------------------
|
||||
|
||||
@@ -91,13 +93,17 @@ For example, the following ``qlconfig.yml`` file associates all packs with the C
|
||||
.. code-block:: yaml
|
||||
|
||||
registries:
|
||||
- packages: 'codeql/*'
|
||||
- packages:
|
||||
- 'codeql/*'
|
||||
- 'other-org/*'
|
||||
url: https://ghcr.io/v2/
|
||||
- packages: '*'
|
||||
url: https://containers.GHE_HOSTNAME/v2/
|
||||
|
||||
The CodeQL CLI will determine which registry to use for a given package name by finding the first item in the ``registries`` list with a ``packages`` property that matches that package name.
|
||||
This means that you'll generally want to define the most specific package name patterns first.
|
||||
This means that you'll generally want to define the most specific package name patterns first. The ``packages`` property may be a single package name, a glob pattern, or a YAML list of package names and glob patterns.
|
||||
|
||||
The ``registries`` list can also be placed inside of a ``codeql-workspace.yml`` file. Doing so will allow you to define the registries to be used within a specific workspace, so that it can be shared amongst other CodeQL users of the workspace. The ``registries`` list in the ``codeql-workspace.yml`` will be merged with and take precedence over the list in the global ``qlconfig.yml``. For more information about ``codeql-workspace.yml``, see :ref:`About CodeQL workspaces <about-codeql-workspaces>`.
|
||||
|
||||
You can now use ``codeql pack publish``, ``codeql pack download``, and ``codeql database analyze`` to manage packs on GitHub Enterprise Server.
|
||||
|
||||
|
||||
@@ -36,7 +36,7 @@ Running the query
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
import ruby
|
||||
import codeql.ruby.AST
|
||||
|
||||
from IfExpr ifexpr
|
||||
where
|
||||
@@ -80,7 +80,7 @@ After the initial ``import`` statement, this simple query comprises three parts
|
||||
+---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
|
||||
| Query part | Purpose | Details |
|
||||
+===============================================================+===================================================================================================================+========================================================================================================================+
|
||||
| ``import ruby`` | Imports the standard CodeQL libraries for Ruby. | Every query begins with one or more ``import`` statements. |
|
||||
| ``import codeql.ruby.AST`` | Imports the standard CodeQL AST libraries for Ruby. | Every query begins with one or more ``import`` statements. |
|
||||
+---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
|
||||
| ``from IfExpr ifexpr`` | Defines the variables for the query. | We use: an ``IfExpr`` variable for ``if`` expressions. |
|
||||
| | Declarations are of the form: | |
|
||||
|
||||
@@ -18,7 +18,7 @@ library by beginning your query with:
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
import ruby
|
||||
import codeql.ruby.AST
|
||||
|
||||
The CodeQL libraries model various aspects of Ruby code, depending on the type of query you want to write.
|
||||
For example the abstract syntax tree (AST) library is used for locating program elements, to match syntactic
|
||||
@@ -138,7 +138,7 @@ The following example lists all methods in the class `ApiController`:
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
import ruby
|
||||
import codeql.ruby.AST
|
||||
|
||||
from ClassDeclaration m
|
||||
where m.getName() = "ApiController"
|
||||
@@ -223,7 +223,7 @@ Example
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
import ruby
|
||||
import codeql.ruby.AST
|
||||
|
||||
from Method m
|
||||
where m.getName() = "show"
|
||||
@@ -274,7 +274,7 @@ The following example finds all literals that are returned by a `return` stateme
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
import ruby
|
||||
import codeql.ruby.AST
|
||||
|
||||
from ReturnStmt return, Literal lit
|
||||
where lit.getParent() = return
|
||||
@@ -421,7 +421,7 @@ The following example finds "chained assignments" (of the form ``A=B=C``):
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
import ruby
|
||||
import codeql.ruby.AST
|
||||
|
||||
from Assignment op
|
||||
where op.getRightOperand() instanceof Assignment
|
||||
@@ -460,7 +460,7 @@ The following example finds all method calls to a method called `delete`.
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
import ruby
|
||||
import codeql.ruby.AST
|
||||
|
||||
from MethodCall call
|
||||
where call.getMethodName() = "delete"
|
||||
@@ -517,7 +517,7 @@ The following example finds `if`-expressions that are missing a `then` branch.
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
import ruby
|
||||
import codeql.ruby.AST
|
||||
|
||||
from IfExpr expr
|
||||
where not exists(expr.getThen())
|
||||
@@ -559,7 +559,7 @@ The following example finds all class variables in the class `StaticController`:
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
import ruby
|
||||
import codeql.ruby.AST
|
||||
|
||||
from ClassDeclaration cd, ClassVariable v
|
||||
where
|
||||
@@ -612,7 +612,7 @@ The following example finds writes to class variables in the class `StaticContro
|
||||
|
||||
.. code-block:: ql
|
||||
|
||||
import ruby
|
||||
import codeql.ruby.AST
|
||||
|
||||
from ClassVariableWriteAccess write, ClassDeclaration cd, ClassVariable v
|
||||
where
|
||||
|
||||
@@ -57,44 +57,27 @@ construction of the library path.
|
||||
First, determine the *query directory* of the ``.ql`` file being
|
||||
compiled. Starting with the directory containing the ``.ql`` file, and
|
||||
walking up the directory structure, each directory is checked for a
|
||||
file called ``queries.xml`` or ``qlpack.yml``. The first directory
|
||||
file called ``qlpack.yml`` or ``codeql-pack.yml``. The first directory
|
||||
where such a file is found is the query directory. If there is no such
|
||||
directory, the directory of the ``.ql`` file itself is the query
|
||||
directory.
|
||||
|
||||
A ``queries.xml`` file that defines a query directory must always
|
||||
contain a single top-level tag named
|
||||
``queries``, which has a ``language`` attribute set to the identifier
|
||||
of the active database schema (for example, ``<queries
|
||||
language="java"/>``).
|
||||
|
||||
A ``qlpack.yml`` file defines a :ref:`CodeQL pack <about-codeql-packs>`.
|
||||
The content of a ``qlpack.yml`` file is described in the CodeQL CLI documentation.
|
||||
``codeql-pack.yml`` is an alias for ``qlpack.yml``.
|
||||
|
||||
If both a ``queries.xml`` and a ``qlpack.yml`` exist in the same
|
||||
directory, the latter takes precedence (and the former is assumed to
|
||||
exist for compatibility with older tooling).
|
||||
|
||||
The CodeQL CLI and newer tools based on it (such as,
|
||||
The CodeQL CLI and tools based on it (such as,
|
||||
GitHub code scanning and the CodeQL extension for Visual Studio Code)
|
||||
construct a library path using CodeQL packs. For each CodeQL pack
|
||||
added to the library path, the CodeQL packs named in its
|
||||
``libraryPathDependencies`` will be subsequently added to the library
|
||||
``dependencies`` will be subsequently added to the library
|
||||
path, and the process continues until all packs have been
|
||||
resolved. The actual library path consists of the root directories of
|
||||
the selected CodeQL packs. This process depends on a mechanism for finding
|
||||
CodeQL packs by pack name, as described in the :ref:`CodeQL CLI documentation <codeql-cli>`.
|
||||
CodeQL packs by pack name and version, as described in the :ref:`CodeQL CLI documentation <codeql-cli>`.
|
||||
|
||||
When the query directory contains a ``queries.xml`` file but no
|
||||
``qlpack.yml``, the CodeQL pack resolution behaves as if it defines a QL
|
||||
pack with no name and a single library path dependency named
|
||||
``legacy-libraries-LANGUAGE`` where ``LANGUAGE`` is taken from
|
||||
``queries.xml``. The ``github/codeql`` repository provides packs with
|
||||
names following this pattern, which themselves depend on the actual
|
||||
CodeQL libraries for each language.
|
||||
|
||||
When the query directory contains neither a ``queries.xml`` nor
|
||||
``qlpack.yml`` file, it is considered to be a CodeQL pack with no name and
|
||||
When the query directory contains neither a ``qlpack.yml`` nor
|
||||
``codeql-pack.yml`` file, it is considered to be a CodeQL pack with no name and
|
||||
no library dependencies. This causes the library path to consist of
|
||||
*only* the query directory itself. This is not generally useful,
|
||||
but it suffices for running toy examples of QL code that don't
|
||||
@@ -160,7 +143,7 @@ Module definitions
|
||||
|
||||
A QL module definition has the following syntax:
|
||||
|
||||
::
|
||||
::
|
||||
|
||||
module ::= annotation* "module" modulename "{" moduleBody "}"
|
||||
|
||||
@@ -196,7 +179,7 @@ An import directive refers to a module identifier:
|
||||
|
||||
import ::= annotations "import" importModuleId ("as" modulename)?
|
||||
|
||||
qualId ::= simpleId | qualId "." simpleId
|
||||
qualId ::= simpleId | qualId "." simpleId
|
||||
|
||||
importModuleId ::= qualId
|
||||
| importModuleId "::" simpleId
|
||||
@@ -268,7 +251,7 @@ With the exception of class domain types and character types (which cannot be re
|
||||
|
||||
type ::= (moduleId "::")? classname | dbasetype | "boolean" | "date" | "float" | "int" | "string"
|
||||
|
||||
moduleId ::= simpleId | moduleId "::" simpleId
|
||||
moduleId ::= simpleId | moduleId "::" simpleId
|
||||
|
||||
A type reference is resolved to a type as follows:
|
||||
|
||||
@@ -598,7 +581,7 @@ An integer literal is a possibly negated sequence of decimal digits (``0`` throu
|
||||
0
|
||||
42
|
||||
123
|
||||
-2147483648
|
||||
-2147483648
|
||||
|
||||
Float literals (float)
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
@@ -760,7 +743,7 @@ it is parsed as part of the first declaration.
|
||||
Inheriting QLDoc
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
If no QLDoc is provided then it may be inherited.
|
||||
If no QLDoc is provided then it may be inherited.
|
||||
|
||||
In the case of an alias then it may be inherited from the right-hand side of the alias.
|
||||
|
||||
@@ -818,7 +801,7 @@ The body of a predicate is of one of three forms:
|
||||
::
|
||||
|
||||
optbody ::= ";"
|
||||
| "{" formula "}"
|
||||
| "{" formula "}"
|
||||
| "=" literalId "(" (predicateRef "/" int ("," predicateRef "/" int)*)? ")" "(" (exprs)? ")"
|
||||
|
||||
In the first form, with just a semicolon, the predicate is said to not have a body. In the second form, the body of the predicate is the given formula (see "`Formulas <#formulas>`__"). In the third form, the body is a higher-order relation.
|
||||
@@ -873,7 +856,7 @@ Each member of a class is either a *character*, a predicate, or a field:
|
||||
::
|
||||
|
||||
member ::= character | predicate | field
|
||||
character ::= qldoc? annotations classname "(" ")" "{" formula "}"
|
||||
character ::= qldoc? annotations classname "(" ")" "{" formula "}"
|
||||
field ::= qldoc? annotations var_decl ";"
|
||||
|
||||
Characters
|
||||
@@ -924,7 +907,7 @@ A valid class may not inherit from two different classes that include a field wi
|
||||
|
||||
A valid field must override another field if it is annotated ``override``.
|
||||
|
||||
When field ``f`` overrides field ``g`` the type of ``f`` must be a subtype of the type of ``g``. ``f`` may not be a final field.
|
||||
When field ``f`` overrides field ``g`` the type of ``f`` must be a subtype of the type of ``g``. ``f`` may not be a final field.
|
||||
|
||||
Select clauses
|
||||
~~~~~~~~~~~~~~
|
||||
@@ -993,8 +976,8 @@ There are several kinds of expressions:
|
||||
| binop
|
||||
| cast
|
||||
| primary
|
||||
|
||||
primary ::= eparen
|
||||
|
||||
primary ::= eparen
|
||||
| literal
|
||||
| variable
|
||||
| super_expr
|
||||
@@ -1103,7 +1086,7 @@ A super expression has the following syntax:
|
||||
|
||||
::
|
||||
|
||||
super_expr ::= "super" | type "." "super"
|
||||
super_expr ::= "super" | type "." "super"
|
||||
|
||||
For a super expression to be valid, the ``this`` keyword must have a type and value in the typing environment. The type of the expression is the same as the type of ``this`` in the typing environment.
|
||||
|
||||
@@ -1163,11 +1146,11 @@ A valid call with results *resolves* to a set of predicates. The ways a call can
|
||||
- If the call has no receiver and the predicate name is a selection identifier, then the qualifier is resolved as a module (see "`Module resolution <#module-resolution>`__"). The identifier is then resolved in the exported predicate environment of the qualifier module.
|
||||
|
||||
- If the call has a super expression as the receiver, then it resolves to a member predicate in a class that the enclosing class inherits from:
|
||||
- If the super expression is unqualified and there is a single class that the current class inherits from, then the super-class is that class.
|
||||
- If the super expression is unqualified and there is a single class that the current class inherits from, then the super-class is that class.
|
||||
- If the super expression is unqualified and there are multiple classes that the current class inherits from, then the super-class is the domain type.
|
||||
- Otherwise, the super-class is the class named by the qualifier of the super expression.
|
||||
- Otherwise, the super-class is the class named by the qualifier of the super expression.
|
||||
|
||||
The predicate is resolved by looking up its name and arity in the exported predicate environment of the super-class.
|
||||
The predicate is resolved by looking up its name and arity in the exported predicate environment of the super-class.
|
||||
|
||||
- If the type of the receiver is the same as the enclosing class, the predicate is resolved by looking up its name and arity in the visible predicate environment of the class.
|
||||
|
||||
@@ -1226,15 +1209,15 @@ The rank expression must be present if the aggregate id is ``rank``; otherwise i
|
||||
Apart from the presence or absence of the rank variable, all other reduced forms of an aggregation are equivalent to a full form using the following steps:
|
||||
|
||||
- If the formula is omitted, then it is taken to be ``any()``.
|
||||
- If there are no aggregation expressions, then either:
|
||||
- If there are no aggregation expressions, then either:
|
||||
|
||||
- The aggregation id is ``count`` or ``strictcount`` and the expression is taken to be ``1``.
|
||||
- The aggregation id is ``count`` or ``strictcount`` and the expression is taken to be ``1``.
|
||||
- There must be precisely one variable declaration, and the aggregation expression is taken to be a reference to that variable.
|
||||
|
||||
- If the aggregation id is ``concat`` or ``strictconcat`` and it has a single expression then the second expression is taken to be ``""``.
|
||||
- If the ``monotonicAggregates`` language pragma is not enabled, or the original formula and variable declarations are both omitted, then the aggregate is transformed as follows:
|
||||
- If the ``monotonicAggregates`` language pragma is not enabled, or the original formula and variable declarations are both omitted, then the aggregate is transformed as follows:
|
||||
|
||||
- For each aggregation expression ``expr_i``, a fresh variable ``v_i`` is declared with the same type as the expression in addition to the original variable declarations.
|
||||
- For each aggregation expression ``expr_i``, a fresh variable ``v_i`` is declared with the same type as the expression in addition to the original variable declarations.
|
||||
- The new range is the conjunction of the original range and a term ``v_i = expr_i`` for each aggregation expression ``expr_i``.
|
||||
- Each original aggregation expression ``expr_i`` is replaced by a new aggregation expression ``v_i``.
|
||||
|
||||
@@ -1320,11 +1303,11 @@ Expression pragmas can be used to guide optimization.
|
||||
The values of an expression pragma are the values of the contained expression.
|
||||
|
||||
The type `only_bind_out` hints that uses of the result of the expression pragma should not be used to guide the evaluation of the result of the contained expression.
|
||||
When checking to see that all values are bound the compiler does not assume that if the result of the expression pragma is bound then the result of the contained
|
||||
When checking to see that all values are bound the compiler does not assume that if the result of the expression pragma is bound then the result of the contained
|
||||
expression is bound.
|
||||
|
||||
The type `only_bind_into` hints that uses of the contained expression should not be used to guide the evaluation of the result of the expression pragma.
|
||||
When checking to see that all values are bound the compiler does not assume that if the result of the contained expression is bound then the result of the
|
||||
When checking to see that all values are bound the compiler does not assume that if the result of the contained expression is bound then the result of the
|
||||
expression pragma is bound.
|
||||
|
||||
Ranges
|
||||
@@ -1498,7 +1481,7 @@ A comparison formula is two expressions separated by a comparison operator:
|
||||
::
|
||||
|
||||
comparison ::= expr compop expr
|
||||
compop ::= "=" | "!=" | "<" | ">" | "<=" | ">="
|
||||
compop ::= "=" | "!=" | "<" | ">" | "<=" | ">="
|
||||
|
||||
A comparison formula matches if there is one value of the left expression that is in the given ordering with one of the values of the right expression. The ordering used is specified in "`Ordering <#ordering>`__." If one of the values is an integer and the other is a float value, then the integer is converted to a float value before the comparison.
|
||||
|
||||
@@ -1582,7 +1565,7 @@ Aliases define new names for existing QL entities.
|
||||
alias ::= qldoc? annotations "predicate" literalId "=" predicateRef "/" int ";"
|
||||
| qldoc? annotations "class" classname "=" type ";"
|
||||
| qldoc? annotations "module" modulename "=" moduleId ";"
|
||||
|
||||
|
||||
|
||||
An alias introduces a binding from the new name to the entity referred to by the right-hand side in the current module's declared predicate, type, or module environment respectively.
|
||||
|
||||
@@ -1973,13 +1956,13 @@ Each layer of the stratification is *populated* in order. To populate a layer, e
|
||||
- To populate a predicate that has a formula as a body, find each named tuple ``t`` that has the following properties:
|
||||
|
||||
- The tuple matches the body formula.
|
||||
- The variables should be the predicate's arguments.
|
||||
- The variables should be the predicate's arguments.
|
||||
- If the predicate has a result, then the tuples should additionally have a value for ``result``.
|
||||
- If the predicate is a member predicate or characteristic predicate of a class ``C`` then the tuples should additionally have a value for ``this`` and each visible field on the class.
|
||||
- The values corresponding to the arguments should all be a member of the declared types of the arguments.
|
||||
- The values corresponding to ``result`` should all be a member of the result type.
|
||||
- The values corresponding to the fields should all be a member of the declared types of the fields.
|
||||
- If the predicate is a member predicate of a class ``C`` and not a characteristic predicate, then the tuples should additionally extend some tuple in ``C.class``.
|
||||
- If the predicate is a member predicate of a class ``C`` and not a characteristic predicate, then the tuples should additionally extend some tuple in ``C.class``.
|
||||
- If the predicate is a characteristic predicate of a class ``C``, then there should be a tuple ``t'`` in ``C.extends`` such that for each visible field in ``C``, any field that is equal to or overrides a field in ``t'`` should have the same value in ``t``. ``this`` should also map to the same value in ``t`` and ``t'``.
|
||||
|
||||
For each such tuple remove any components that correspond to fields and add it to the predicate in the store.
|
||||
@@ -1998,7 +1981,7 @@ Each layer of the stratification is *populated* in order. To populate a layer, e
|
||||
|
||||
- To populate the type ``C.C`` for a class ``C``, if ``C`` has a characteristic predicate, then add all tuples from that predicate to the store. Otherwise add all tuples ``t`` such that:
|
||||
|
||||
- The variables of ``t`` should be ``this`` and the visible fields of ``C``.
|
||||
- The variables of ``t`` should be ``this`` and the visible fields of ``C``.
|
||||
- The values corresponding to the fields should all be a member of the declared types of the fields.
|
||||
- If the predicate is a characteristic predicate of a class ``C``, then there should be a tuple ``t'`` in ``C.extends`` such that for each visible field in ``C``, any field that is equal to or overrides a field in ``t'`` should have the same value in ``t``. ``this`` should also map to the same value in ``t`` and ``t'``.
|
||||
|
||||
@@ -2033,7 +2016,7 @@ The complete grammar for QL is as follows:
|
||||
|
||||
import ::= annotations "import" importModuleId ("as" modulename)?
|
||||
|
||||
qualId ::= simpleId | qualId "." simpleId
|
||||
qualId ::= simpleId | qualId "." simpleId
|
||||
|
||||
importModuleId ::= qualId
|
||||
| importModuleId "::" simpleId
|
||||
@@ -2072,18 +2055,18 @@ The complete grammar for QL is as follows:
|
||||
head ::= ("predicate" | type) predicateName "(" var_decls ")"
|
||||
|
||||
optbody ::= ";"
|
||||
| "{" formula "}"
|
||||
| "{" formula "}"
|
||||
| "=" literalId "(" (predicateRef "/" int ("," predicateRef "/" int)*)? ")" "(" (exprs)? ")"
|
||||
|
||||
class ::= qldoc? annotations "class" classname "extends" type ("," type)* "{" member* "}"
|
||||
|
||||
member ::= character | predicate | field
|
||||
|
||||
character ::= qldoc? annotations classname "(" ")" "{" formula "}"
|
||||
character ::= qldoc? annotations classname "(" ")" "{" formula "}"
|
||||
|
||||
field ::= qldoc? annotations var_decl ";"
|
||||
|
||||
moduleId ::= simpleId | moduleId "::" simpleId
|
||||
moduleId ::= simpleId | moduleId "::" simpleId
|
||||
|
||||
type ::= (moduleId "::")? classname | dbasetype | "boolean" | "date" | "float" | "int" | "string"
|
||||
|
||||
@@ -2092,7 +2075,7 @@ The complete grammar for QL is as follows:
|
||||
alias ::= qldoc? annotations "predicate" literalId "=" predicateRef "/" int ";"
|
||||
| qldoc? annotations "class" classname "=" type ";"
|
||||
| qldoc? annotations "module" modulename "=" moduleId ";"
|
||||
|
||||
|
||||
var_decls ::= (var_decl ("," var_decl)*)?
|
||||
|
||||
var_decl ::= type lowerId
|
||||
@@ -2108,7 +2091,7 @@ The complete grammar for QL is as follows:
|
||||
| instanceof
|
||||
| inrange
|
||||
| call
|
||||
|
||||
|
||||
fparen ::= "(" formula ")"
|
||||
|
||||
disjunction ::= formula "or" formula
|
||||
@@ -2128,7 +2111,7 @@ The complete grammar for QL is as follows:
|
||||
|
||||
comparison ::= expr compop expr
|
||||
|
||||
compop ::= "=" | "!=" | "<" | ">" | "<=" | ">="
|
||||
compop ::= "=" | "!=" | "<" | ">" | "<=" | ">="
|
||||
|
||||
instanceof ::= expr "instanceof" type
|
||||
|
||||
@@ -2146,7 +2129,7 @@ The complete grammar for QL is as follows:
|
||||
| primary
|
||||
|
||||
|
||||
primary ::= eparen
|
||||
primary ::= eparen
|
||||
| literal
|
||||
| variable
|
||||
| super_expr
|
||||
@@ -2175,7 +2158,7 @@ The complete grammar for QL is as follows:
|
||||
|
||||
variable ::= varname | "this" | "result"
|
||||
|
||||
super_expr ::= "super" | type "." "super"
|
||||
super_expr ::= "super" | type "." "super"
|
||||
|
||||
cast ::= "(" type ")" expr
|
||||
|
||||
@@ -2184,7 +2167,7 @@ The complete grammar for QL is as follows:
|
||||
aggregation ::= aggid ("[" expr "]")? "(" var_decls ("|" (formula)? ("|" as_exprs ("order" "by" aggorderbys)?)?)? ")"
|
||||
| aggid ("[" expr "]")? "(" as_exprs ("order" "by" aggorderbys)? ")"
|
||||
| "unique" "(" var_decls "|" (formula)? ("|" as_exprs)? ")"
|
||||
|
||||
|
||||
expression_pragma ::= "pragma" "[" expression_pragma_type "]" "(" expr ")"
|
||||
|
||||
expression_pragma_type ::= "only_bind_out" | "only_bind_into"
|
||||
@@ -2199,9 +2182,9 @@ The complete grammar for QL is as follows:
|
||||
|
||||
callwithresults ::= predicateRef (closure)? "(" (exprs)? ")"
|
||||
| primary "." predicateName (closure)? "(" (exprs)? ")"
|
||||
|
||||
|
||||
range ::= "[" expr ".." expr "]"
|
||||
|
||||
|
||||
setliteral ::= "[" expr ("," expr)* ","? "]"
|
||||
|
||||
simpleId ::= lowerId | upperId
|
||||
|
||||
@@ -7,7 +7,7 @@ For example, to check for CodeQL databases using the `GitHub CLI <https://cli.gi
|
||||
|
||||
This command returns information about any CodeQL databases that are available for a repository, including the language the database represents, and when the database was last updated. If no CodeQL databases are available, the response is empty.
|
||||
|
||||
When you have confirmed that a CodeQL database exists for the language you are interested in, you can download it using the following command::
|
||||
When you have confirmed that a CodeQL database exists for the language you are interested in, you can download it using the following command::
|
||||
|
||||
gh api /repos/<owner>/<repo>/code-scanning/codeql/databases/<language> -H 'Accept: application/zip' > path/to/local/database.zip
|
||||
|
||||
|
||||
@@ -179,7 +179,15 @@ The select clause of each alert query defines the alert message that is displaye
|
||||
* The message should factually describe the problem that is being highlighted–it should not contain recommendations about how to fix the problem or value judgements.
|
||||
* Program element references should be in 'single quotes' to distinguish them from ordinary words. Quotes are not needed around substitutions (`$@`).
|
||||
* Avoid constant alert message strings and include some context, if possible. For example, `The class 'Foo' is duplicated as 'Bar'.` is preferable to `This class is duplicated here.`
|
||||
* If a reference to the current location can't be avoided use "this location" instead of "here". For example, `Bad thing at this location.` is preferable to `Bad thing here.`. This avoids the "click here" anti-pattern.
|
||||
* For path queries, if possible, try to follow the template: `This path depends on a [user-provided value].`, or alternatively (if the first option doesn't work) `[User-provided value] flows to this location and is used in a path.`.
|
||||
* Taint tracking queries generally have a sink that "depends on" the source, and dataflow queries generally have a source that "flows to" the sink.
|
||||
|
||||
### Links in alert messages
|
||||
|
||||
* Where you reference another program element, link to it if possible using a substitution (`$@`). Links should be used inline in the sentence, rather than as parenthesised lists or appositions.
|
||||
* Avoid using link texts that don't describe what they link to. For example, rewrite `This sensitive data is written to a logfile unescaped [here]` to `This sensitive data is [written to a logfile unescaped]`.
|
||||
* Make link text as concise and precise as possible. For example, avoid starting a link text with an indefinite article (a, an). `Path construction depends on a [user-provided value]` is preferable to `Path construction depends on [a user-provided value]`. (Where the square brackets indicate a link.) See [the W3C guide on link texts](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html) for further information.
|
||||
* When a message contains multiple links, construct a sentence that has the most variable link (that is, the link with most targets) last. For further information, see [Defining the results of a query](https://codeql.github.com/docs/writing-codeql-queries/defining-the-results-of-a-query/).
|
||||
|
||||
For examples of select clauses and alert messages, see the query source files at the following pages:
|
||||
|
||||
Reference in New Issue
Block a user