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

Merge pull request #4620 from github/codeql-docs-reorg-1

Browse Source 
[docs] Rename source files to match article titles
This commit is contained in:
Aditya Sharad
2020-11-06 12:18:14 -08:00
committed by GitHub
parent 4259c81061 f85f99c6c2
commit e75082a249
92 changed files with 396 additions and 396 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/language/README.rst
View File

@@ -18,7 +18,7 @@ Project structure
The documentation currently consists of the following Sphinx projects:
- ``learn-ql``–help topics to help you learn CodeQL and write queries
- ``ql-handbook``–an overview of important concepts in QL, the language that underlies CodeQL analysis
- ``ql-language-reference``–an overview of important concepts in QL, the language that underlies CodeQL analysis
- ``support``–the languages and frameworks currently supported in CodeQL analysis
- ``ql-training``–source files for the CodeQL training and variant analysis examples slide decks

18
docs/language/learn-ql/intro-to-data-flow.rst → docs/language/learn-ql/about-data-flow-analysis.rst
View File

@@ -14,17 +14,17 @@ The following sections provide a brief introduction to data flow analysis with C
See the following tutorials for more information about analyzing data flow in specific languages:
- ":doc:`Analyzing data flow in C/C++ <cpp/dataflow>`"
- ":doc:`Analyzing data flow in C# <csharp/dataflow>`"
- ":doc:`Analyzing data flow in Java <java/dataflow>`"
- ":doc:`Analyzing data flow in JavaScript/TypeScript <javascript/dataflow>`"
- ":doc:`Analyzing data flow and tracking tainted data in Python <python/taint-tracking>`"
- ":doc:`Analyzing data flow in C/C++ <cpp/analyzing-data-flow-in-cpp>`"
- ":doc:`Analyzing data flow in C# <csharp/analyzing-data-flow-in-csharp>`"
- ":doc:`Analyzing data flow in Java <java/analyzing-data-flow-in-java>`"
- ":doc:`Analyzing data flow in JavaScript/TypeScript <javascript/analyzing-data-flow-in-javascript>`"
- ":doc:`Analyzing data flow and tracking tainted data in Python <python/analyzing-data-flow-and-tracking-tainted-data-in-python>`"
.. pull-quote::
Note
Data flow analysis is used extensively in path queries. To learn more about path queries, see ":doc:`Creating path queries <writing-queries/path-queries>`."
Data flow analysis is used extensively in path queries. To learn more about path queries, see ":doc:`Creating path queries <writing-queries/creating-path-queries>`."
.. _data-flow-graph:
@@ -49,8 +49,8 @@ flow between functions and through object properties. Global data flow, however,
graph that do not precisely correspond to the flow of values, but model whether some value at runtime may be derived from another, for instance through a string manipulating
operation.
The data flow graph is computed using `classes <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__ to model the program elements that represent the graph's nodes.
The flow of data between the nodes is modeled using `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ to compute the graph's edges.
The data flow graph is computed using `classes <https://help.semmle.com/QL/ql-language-reference/types.html#classes>`__ to model the program elements that represent the graph's nodes.
The flow of data between the nodes is modeled using `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ to compute the graph's edges.
Computing an accurate and complete data flow graph presents several challenges:
@@ -82,5 +82,5 @@ These flow steps are modeled in the taint-tracking library using predicates that
Further reading
***************
- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-paths.html>`__"
- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-data-flow-with-path-queries.html>`__"

4
docs/language/learn-ql/beginner/catch-the-fire-starter.rst
View File

@@ -14,7 +14,7 @@ Read the examples below to learn how to define predicates and classes in QL. The
Select the southerners
----------------------
This time you only need to consider a specific group of villagers, namely those living in the south of the village. Instead of writing ``getLocation() = "south"`` in all your queries, you could define a new `predicate <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ ``isSouthern``:
This time you only need to consider a specific group of villagers, namely those living in the south of the village. Instead of writing ``getLocation() = "south"`` in all your queries, you could define a new `predicate <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ ``isSouthern``:
.. code-block:: ql
@@ -41,7 +41,7 @@ You can now list all southerners using:
where isSouthern(p)
select p
This is already a nice way to simplify the logic, but we could be more efficient. Currently, the query looks at every ``Person p``, and then restricts to those who satisfy ``isSouthern(p)``. Instead, we could define a new `class <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__ ``Southerner`` containing precisely the people we want to consider.
This is already a nice way to simplify the logic, but we could be more efficient. Currently, the query looks at every ``Person p``, and then restricts to those who satisfy ``isSouthern(p)``. Instead, we could define a new `class <https://help.semmle.com/QL/ql-language-reference/types.html#classes>`__ ``Southerner`` containing precisely the people we want to consider.
.. code-block:: ql

20
docs/language/learn-ql/beginner/cross-the-river.rst
View File

@@ -20,8 +20,8 @@ A solution should be a set of instructions for how to ferry the items, such as "
across the river, and come back with nothing. Then ferry the cabbage across, and come back with ..."
There are lots of ways to approach this problem and implement it in QL. Before you start, make
sure that you are familiar with how to define `classes <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__
and `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ in QL.
sure that you are familiar with how to define `classes <https://help.semmle.com/QL/ql-language-reference/types.html#classes>`__
and `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ in QL.
The following walkthrough is just one of many possible implementations, so have a go at writing your
own query too! To find more example queries, see the list :ref:`below <alternatives>`.
@@ -69,7 +69,7 @@ For example, if the man is on the left shore, the goat on the right shore, and t
shore, the state should be ``Left, Right, Left, Left``.
You may find it helpful to introduce some variables that refer to the shore on which the man and the cargo items are. These
temporary variables in the body of a class are called `fields <https://help.semmle.com/QL/ql-handbook/types.html#fields>`__.
temporary variables in the body of a class are called `fields <https://help.semmle.com/QL/ql-language-reference/types.html#fields>`__.
.. container:: toggle
@@ -159,12 +159,12 @@ could ferry the goat back and forth any number of times without ever reaching an
Such a path would have an infinite number of river crossings without ever solving the puzzle.
One way to restrict our paths to a finite number of river crossings is to define a
`member predicate <https://help.semmle.com/QL/ql-handbook/types.html#member-predicates>`__
`member predicate <https://help.semmle.com/QL/ql-language-reference/types.html#member-predicates>`__
``State reachesVia(string path, int steps)``.
The result of this predicate is any state that is reachable from the current state (``this``) via
the given path in a specified finite number of steps.
You can write this as a `recursive predicate <https://help.semmle.com/QL/ql-handbook/recursion.html>`__,
You can write this as a `recursive predicate <https://help.semmle.com/QL/ql-language-reference/recursion.html>`__,
with the following base case and recursion step:
- If ``this`` *is* the result state, then it (trivially) reaches the result state via an
@@ -203,7 +203,7 @@ the given path without revisiting any previously visited states.
revisiting any previous states, and there is a ``safeFerry`` action from the intermediate state to
the result state.
(Hint: To check whether a state has previously been visited, you could check if
there is an `index of <https://help.semmle.com/QL/ql-spec/language.html#built-ins-for-string>`__
there is an `index of <ql-language-specification#built-ins-for-string>`__
``visitedStates`` at which the state occurs.)
.. container:: toggle
@@ -218,7 +218,7 @@ the given path without revisiting any previously visited states.
Display the results
~~~~~~~~~~~~~~~~~~~
Once you've defined all the necessary classes and predicates, write a `select clause <https://help.semmle.com/QL/ql-handbook/queries.html#select-clauses>`__
Once you've defined all the necessary classes and predicates, write a `select clause <https://help.semmle.com/QL/ql-language-reference/queries.html#select-clauses>`__
that returns the resulting path.
.. container:: toggle
@@ -230,7 +230,7 @@ that returns the resulting path.
.. literalinclude:: river-crossing.ql
:lines: 115-117
The `don't-care expression <https://help.semmle.com/QL/ql-handbook/expressions.html#don-t-care-expressions>`__ (``_``),
The `don't-care expression <https://help.semmle.com/QL/ql-language-reference/expressions.html#don-t-care-expressions>`__ (``_``),
as the second argument to the ``reachesVia`` predicate, represents any value of ``visitedStates``.
For now, the path defined in ``reachesVia`` just lists the order of cargo items to ferry.
@@ -254,12 +254,12 @@ Here are some more example queries that solve the river crossing puzzle:
➤ `See solution in the query console on LGTM.com <https://lgtm.com/query/659603593702729237/>`__
#. This query models the man and the cargo items in a different way, using an
`abstract <https://help.semmle.com/QL/ql-handbook/annotations.html#abstract>`__
`abstract <https://help.semmle.com/QL/ql-language-reference/annotations.html#abstract>`__
class and predicate. It also displays the resulting path in a more visual way.
➤ `See solution in the query console on LGTM.com <https://lgtm.com/query/1025323464423811143/>`__
#. This query introduces `algebraic datatypes <https://help.semmle.com/QL/ql-handbook/types.html#algebraic-datatypes>`__
#. This query introduces `algebraic datatypes <https://help.semmle.com/QL/ql-language-reference/types.html#algebraic-datatypes>`__
to model the situation, instead of defining everything as a subclass of ``string``.
➤ `See solution in the query console on LGTM.com <https://lgtm.com/query/7260748307619718263/>`__

2
docs/language/learn-ql/beginner/crown-the-rightful-heir.rst
View File

@@ -106,7 +106,7 @@ You can translate this into QL as follows:
result = parentOf(ancestorOf(p))
}
As you can see, you have used the predicate ``ancestorOf()`` inside its own definition. This is an example of `recursion <https://help.semmle.com/QL/ql-handbook/recursion.html>`__.
As you can see, you have used the predicate ``ancestorOf()`` inside its own definition. This is an example of `recursion <https://help.semmle.com/QL/ql-language-reference/recursion.html>`__.
This kind of recursion, where the same operation (in this case ``parentOf()``) is applied multiple times, is very common in QL, and is known as the *transitive closure* of the operation. There are two special symbols ``+`` and ``*`` that are extremely useful when working with transitive closures:

12
docs/language/learn-ql/beginner/find-the-thief.rst
View File

@@ -48,12 +48,12 @@ There is too much information to search through by hand, so you decide to use yo
#. Open the `query console on LGTM.com <https://lgtm.com/query>`__ to get started.
#. Select a language and a demo project. For this tutorial, any language and project will do.
#. Delete the default code ``import <language> select "hello world"``.
#. Delete the default code ``import <ql-language-specification> select "hello world"``.
QL libraries
------------
We've defined a number of QL `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ to help you extract data from your table. A QL predicate is a mini-query that expresses a relation between various pieces of data and describes some of their properties. In this case, the predicates give you information about a person, for example their height or age.
We've defined a number of QL `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ to help you extract data from your table. A QL predicate is a mini-query that expresses a relation between various pieces of data and describes some of their properties. In this case, the predicates give you information about a person, for example their height or age.
+--------------------+----------------------------------------------------------------------------------------+
| Predicate | Description |
@@ -84,14 +84,14 @@ The villagers answered "yes" to the question "Is the thief taller than 150cm?" T
where t.getHeight() > 150
select t
The first line, ``from Person t``, declares that ``t`` must be a ``Person``. We say that the `type <https://help.semmle.com/QL/ql-handbook/types.html>`__ of ``t`` is ``Person``.
The first line, ``from Person t``, declares that ``t`` must be a ``Person``. We say that the `type <https://help.semmle.com/QL/ql-language-reference/types.html>`__ of ``t`` is ``Person``.
Before you use the rest of your answers in your QL search, here are some more tools and examples to help you write your own QL queries:
Logical connectives
-------------------
Using `logical connectives <https://help.semmle.com/QL/ql-handbook/formulas.html#logical-connectives>`__, you can write more complex queries that combine different pieces of information.
Using `logical connectives <https://help.semmle.com/QL/ql-language-reference/formulas.html#logical-connectives>`__, you can write more complex queries that combine different pieces of information.
For example, if you know that the thief is older than 30 *and* has brown hair, you can use the following ``where`` clause to link two predicates:
@@ -157,7 +157,7 @@ Notice that we have only temporarily introduced the variable ``c`` and we didn't
Note
If you are familiar with logic, you may notice that ``exists`` in QL corresponds to the existential `quantifier <https://help.semmle.com/QL/ql-handbook/formulas.html#quantified-formulas>`__ in logic. QL also has a universal quantifier ``forall(vars | formula 1 | formula 2)`` which is logically equivalent to ``not exists(vars | formula 1 | not formula 2)``.
If you are familiar with logic, you may notice that ``exists`` in QL corresponds to the existential `quantifier <https://help.semmle.com/QL/ql-language-reference/formulas.html#quantified-formulas>`__ in logic. QL also has a universal quantifier ``forall(vars | formula 1 | formula 2)`` which is logically equivalent to ``not exists(vars | formula 1 | not formula 2)``.
The real investigation
----------------------
@@ -218,7 +218,7 @@ You are getting closer to solving the mystery! Unfortunately, you still have qui
More advanced queries
---------------------
What if you want to find the oldest, youngest, tallest, or shortest person in the village? As mentioned in the previous topic, you can do this using ``exists``. However, there is also a more efficient way to do this in QL using functions like ``max`` and ``min``. These are examples of `aggregates <https://help.semmle.com/QL/ql-handbook/expressions.html#aggregations>`__.
What if you want to find the oldest, youngest, tallest, or shortest person in the village? As mentioned in the previous topic, you can do this using ``exists``. However, there is also a more efficient way to do this in QL using functions like ``max`` and ``min``. These are examples of `aggregates <https://help.semmle.com/QL/ql-language-reference/expressions.html#aggregations>`__.
In general, an aggregate is a function that performs an operation on multiple pieces of data and returns a single value as its output. Common aggregates are ``count``, ``max``, ``min``, ``avg`` (average) and ``sum``. The general way to use an aggregate is:

4
docs/language/learn-ql/cpp/dataflow.rst → docs/language/learn-ql/cpp/analyzing-data-flow-in-cpp.rst
View File

@@ -6,7 +6,7 @@ You can use data flow analysis to track the flow of potentially malicious or ins
About data flow
---------------
Data flow analysis computes the possible values that a variable can hold at various points in a program, determining how those values propagate through the program, and where they are used. In CodeQL, you can model both local data flow and global data flow. For a more general introduction to modeling data flow, see ":doc:`About data flow analysis <../intro-to-data-flow>`."
Data flow analysis computes the possible values that a variable can hold at various points in a program, determining how those values propagate through the program, and where they are used. In CodeQL, you can model both local data flow and global data flow. For a more general introduction to modeling data flow, see ":doc:`About data flow analysis <../about-data-flow-analysis>`."
Local data flow
---------------
@@ -390,7 +390,7 @@ Exercise 4
Further reading
---------------
- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-paths.html>`__"
- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-data-flow-with-path-queries.html>`__"
.. include:: ../../reusables/cpp-further-reading.rst

0
docs/language/learn-ql/cpp/basic-query-cpp.rst → docs/language/learn-ql/cpp/basic-query-for-cpp-code.rst
View File

42
docs/language/learn-ql/cpp/codeql-for-cpp.rst Normal file
View File

@@ -0,0 +1,42 @@
CodeQL for C and C++
====================
Experiment and learn how to write effective and efficient queries for CodeQL databases generated from C and C++ codebases.
.. toctree::
:hidden:
basic-query-for-cpp-code
codeql-library-for-cpp
functions-in-cpp
expressions-types-and-statements-in-cpp
conversions-and-classes-in-cpp
analyzing-data-flow-in-cpp
refining-a-query-to-account-for-edge-cases
detecting-a-potential-buffer-overflow
using-the-guards-library-in-cpp
using-range-analsis-in-cpp
hash-consing-and-value-numbering
- :doc:`Basic query for C and C++ code <basic-query-for-cpp-code>`: Learn to write and run a simple CodeQL query using LGTM.
- :doc:`CodeQL library for C and C++ <codeql-library-for-cpp>`: When analyzing C or C++ code, you can use the large collection of classes in the CodeQL library for C and C++.
- :doc:`Functions in C and C++ <functions-in-cpp>`: You can use CodeQL to explore functions in C and C++ code.
- :doc:`Expressions, types, and statements in C and C++ <expressions-types-and-statements-in-cpp>`: You can use CodeQL to explore expressions, types, and statements in C and C++ code to find, for example, incorrect assignments.
- :doc:`Conversions and classes in C and C++ <conversions-and-classes-in-cpp>`: You can use the standard CodeQL libraries for C and C++ to detect when the type of an expression is changed.
- :doc:`Analyzing data flow in C and C++ <analyzing-data-flow-in-cpp>`: You can use data flow analysis to track the flow of potentially malicious or insecure data that can cause vulnerabilities in your codebase.
- :doc:`Refining a query to account for edge cases <refining-a-query-to-account-for-edge-cases>`: You can improve the results generated by a CodeQL query by adding conditions to remove false positive results caused by common edge cases.
- :doc:`Detecting a potential buffer overflow <detecting-a-potential-buffer-overflow>`: You can use CodeQL to detect potential buffer overflows by checking for allocations equal to ``strlen`` in C and C++.
- :doc:`Using the guards library in C and C++ <using-the-guards-library-in-cpp>`: You can use the CodeQL guards library to identify conditional expressions that control the execution of other parts of a program in C and C++ codebases.
- :doc:`Using range analysis for C and C++ <using-range-analsis-in-cpp>`: You can use range analysis to determine the upper or lower bounds on an expression, or whether an expression could potentially over or underflow.
- :doc:`Hash consing and value numbering <hash-consing-and-value-numbering>`: You can use specialized CodeQL libraries to recognize expressions that are syntactically identical or compute the same value at runtime in C and C++ codebases.

0
docs/language/learn-ql/cpp/introduce-libraries-cpp.rst → docs/language/learn-ql/cpp/codeql-library-for-cpp.rst
View File

0
docs/language/learn-ql/cpp/conversions-classes.rst → docs/language/learn-ql/cpp/conversions-and-classes-in-cpp.rst
View File

0
docs/language/learn-ql/cpp/zero-space-terminator.rst → docs/language/learn-ql/cpp/detecting-a-potential-buffer-overflow.rst
View File

0
docs/language/learn-ql/cpp/expressions-types.rst → docs/language/learn-ql/cpp/expressions-types-and-statements-in-cpp.rst
View File

4
docs/language/learn-ql/cpp/function-classes.rst → docs/language/learn-ql/cpp/functions-in-cpp.rst
View File

@@ -6,7 +6,7 @@ You can use CodeQL to explore functions in C and C++ code.
Overview
--------
The standard CodeQL library for C and C++ represents functions using the ``Function`` class (see :doc:`CodeQL libraries for C and C++ <introduce-libraries-cpp>`).
The standard CodeQL library for C and C++ represents functions using the ``Function`` class (see :doc:`CodeQL libraries for C and C++ <codeql-library-for-cpp>`).
The example queries in this topic explore some of the most useful library predicates for querying functions.
@@ -28,7 +28,7 @@ This query is very general, so there are probably too many results to be interes
Finding functions that are not called
-------------------------------------
It might be more interesting to find functions that are not called, using the standard CodeQL ``FunctionCall`` class from the **abstract syntax tree** category (see :doc:`CodeQL libraries for C and C++ <introduce-libraries-cpp>`). The ``FunctionCall`` class can be used to identify places where a function is actually used, and it is related to ``Function`` through the ``FunctionCall.getTarget()`` predicate.
It might be more interesting to find functions that are not called, using the standard CodeQL ``FunctionCall`` class from the **abstract syntax tree** category (see :doc:`CodeQL libraries for C and C++ <codeql-library-for-cpp>`). The ``FunctionCall`` class can be used to identify places where a function is actually used, and it is related to ``Function`` through the ``FunctionCall.getTarget()`` predicate.
.. code-block:: ql

0
docs/language/learn-ql/cpp/value-numbering-hash-cons.rst → docs/language/learn-ql/cpp/hash-consing-and-value-numbering.rst
View File

42
docs/language/learn-ql/cpp/ql-for-cpp.rst
View File

@@ -1,42 +0,0 @@
CodeQL for C and C++
====================
Experiment and learn how to write effective and efficient queries for CodeQL databases generated from C and C++ codebases.
.. toctree::
:hidden:
basic-query-cpp
introduce-libraries-cpp
function-classes
expressions-types
conversions-classes
dataflow
private-field-initialization
zero-space-terminator
guards
range-analysis
value-numbering-hash-cons
- :doc:`Basic query for C and C++ code <basic-query-cpp>`: Learn to write and run a simple CodeQL query using LGTM.
- :doc:`CodeQL library for C and C++ <introduce-libraries-cpp>`: When analyzing C or C++ code, you can use the large collection of classes in the CodeQL library for C and C++.
- :doc:`Functions in C and C++ <function-classes>`: You can use CodeQL to explore functions in C and C++ code.
- :doc:`Expressions, types, and statements in C and C++ <expressions-types>`: You can use CodeQL to explore expressions, types, and statements in C and C++ code to find, for example, incorrect assignments.
- :doc:`Conversions and classes in C and C++ <conversions-classes>`: You can use the standard CodeQL libraries for C and C++ to detect when the type of an expression is changed.
- :doc:`Analyzing data flow in C and C++ <dataflow>`: You can use data flow analysis to track the flow of potentially malicious or insecure data that can cause vulnerabilities in your codebase.
- :doc:`Refining a query to account for edge cases <private-field-initialization>`: You can improve the results generated by a CodeQL query by adding conditions to remove false positive results caused by common edge cases.
- :doc:`Detecting a potential buffer overflow <zero-space-terminator>`: You can use CodeQL to detect potential buffer overflows by checking for allocations equal to ``strlen`` in C and C++.
- :doc:`Using the guards library in C and C++ <guards>`: You can use the CodeQL guards library to identify conditional expressions that control the execution of other parts of a program in C and C++ codebases.
- :doc:`Using range analysis for C and C++ <range-analysis>`: You can use range analysis to determine the upper or lower bounds on an expression, or whether an expression could potentially over or underflow.
- :doc:`Hash consing and value numbering <value-numbering-hash-cons>`: You can use specialized CodeQL libraries to recognize expressions that are syntactically identical or compute the same value at runtime in C and C++ codebases.

6
docs/language/learn-ql/cpp/private-field-initialization.rst → docs/language/learn-ql/cpp/refining-a-query-to-account-for-edge-cases.rst
View File

@@ -6,7 +6,7 @@ You can improve the results generated by a CodeQL query by adding conditions to
Overview
--------
This topic describes how a C++ query was developed. The example introduces recursive predicates and demonstrates the typical workflow used to refine a query. For a full overview of the topics available for learning to write queries for C/C++ code, see ":doc:`CodeQL for C and C++ <ql-for-cpp>`."
This topic describes how a C++ query was developed. The example introduces recursive predicates and demonstrates the typical workflow used to refine a query. For a full overview of the topics available for learning to write queries for C/C++ code, see ":doc:`CodeQL for C and C++ <codeql-for-cpp>`."
Finding every private field and checking for initialization
-----------------------------------------------------------
@@ -102,7 +102,7 @@ You may also wish to consider methods called by constructors that assign to the
int m_value;
};
This case can be excluded by creating a recursive predicate. The recursive predicate is given a function and a field, then checks whether the function assigns to the field. The predicate runs itself on all the functions called by the function that it has been given. By passing the constructor to this predicate, we can check for assignments of a field in all functions called by the constructor, and then do the same for all functions called by those functions all the way down the tree of function calls. For more information, see "`Recursion <https://help.semmle.com/QL/ql-handbook/recursion.html>`__" in the QL language reference.
This case can be excluded by creating a recursive predicate. The recursive predicate is given a function and a field, then checks whether the function assigns to the field. The predicate runs itself on all the functions called by the function that it has been given. By passing the constructor to this predicate, we can check for assignments of a field in all functions called by the constructor, and then do the same for all functions called by those functions all the way down the tree of function calls. For more information, see "`Recursion <https://help.semmle.com/QL/ql-language-reference/recursion.html>`__" in the QL language reference.
.. code-block:: ql
@@ -126,7 +126,7 @@ This case can be excluded by creating a recursive predicate. The recursive predi
Refinement 4—simplifying the query
----------------------------------
Finally we can simplify the query by using the transitive closure operator. In this final version of the query, ``c.calls*(fun)`` resolves to the set of all functions that are ``c`` itself, are called by ``c``, are called by a function that is called by ``c``, and so on. This eliminates the need to make a new predicate all together. For more information, see "`Transitive closures <https://help.semmle.com/QL/ql-handbook/recursion.html#transitive-closures>`__" in the QL language reference.
Finally we can simplify the query by using the transitive closure operator. In this final version of the query, ``c.calls*(fun)`` resolves to the set of all functions that are ``c`` itself, are called by ``c``, are called by a function that is called by ``c``, and so on. This eliminates the need to make a new predicate all together. For more information, see "`Transitive closures <https://help.semmle.com/QL/ql-language-reference/recursion.html#transitive-closures>`__" in the QL language reference.
.. code-block:: ql

0
docs/language/learn-ql/cpp/range-analysis.rst → docs/language/learn-ql/cpp/using-range-analsis-in-cpp.rst
View File

0
docs/language/learn-ql/cpp/guards.rst → docs/language/learn-ql/cpp/using-the-guards-library-in-cpp.rst
View File

4
docs/language/learn-ql/csharp/dataflow.rst → docs/language/learn-ql/csharp/analyzing-data-flow-in-csharp.rst
View File

@@ -8,7 +8,7 @@ About this article
This article describes how data flow analysis is implemented in the CodeQL libraries for C# and includes examples to help you write your own data flow queries.
The following sections describe how to use the libraries for local data flow, global data flow, and taint tracking.
For a more general introduction to modeling data flow, see ":doc:`About data flow analysis <../intro-to-data-flow>`."
For a more general introduction to modeling data flow, see ":doc:`About data flow analysis <../about-data-flow-analysis>`."
Local data flow
---------------
@@ -553,7 +553,7 @@ This can be adapted from the ``SystemUriFlow`` class:
Further reading
---------------
- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-paths.html>`__"
- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-data-flow-with-path-queries.html>`__"
.. include:: ../../reusables/csharp-further-reading.rst

0
docs/language/learn-ql/csharp/basic-query-csharp.rst → docs/language/learn-ql/csharp/basic-query-for-csharp-code.rst
View File

19
docs/language/learn-ql/csharp/codeql-for-csharp.rst Normal file
View File

@@ -0,0 +1,19 @@
CodeQL for C#
=============
Experiment and learn how to write effective and efficient queries for CodeQL databases generated from C# codebases.
.. toctree::
:hidden:
basic-query-for-csharp-code
codeql-library-for-csharp
analyzing-data-flow-in-csharp
- :doc:`Basic query for C# code <basic-query-for-csharp-code>`: Learn to write and run a simple CodeQL query using LGTM.
- :doc:`CodeQL library for C# <codeql-library-for-csharp>`: When you're analyzing a C# program, you can make use of the large collection of classes in the CodeQL library for C#.
- :doc:`Analyzing data flow in C# <analyzing-data-flow-in-csharp>`: You can use CodeQL to track the flow of data through a C# program to its use.

2
docs/language/learn-ql/csharp/introduce-libraries-csharp.rst → docs/language/learn-ql/csharp/codeql-library-for-csharp.rst
View File

@@ -14,7 +14,7 @@ There is an extensive core library for analyzing CodeQL databases extracted from
Since this is required for all C# queries, it's omitted from code snippets below.
The core library contains all the program elements, including `files <#files>`__, `types <#types>`__, methods, `variables <#variables>`__, `statements <#statements>`__, and `expressions <#expressions>`__. This is sufficient for most queries, however additional libraries can be imported for bespoke functionality such as control flow and data flow. For information about these additional libraries, see ":doc:`CodeQL for C# <ql-for-csharp>`."
The core library contains all the program elements, including `files <#files>`__, `types <#types>`__, methods, `variables <#variables>`__, `statements <#statements>`__, and `expressions <#expressions>`__. This is sufficient for most queries, however additional libraries can be imported for bespoke functionality such as control flow and data flow. For information about these additional libraries, see ":doc:`CodeQL for C# <codeql-for-csharp>`."
Class hierarchies
~~~~~~~~~~~~~~~~~

19
docs/language/learn-ql/csharp/ql-for-csharp.rst
View File

@@ -1,19 +0,0 @@
CodeQL for C#
=============
Experiment and learn how to write effective and efficient queries for CodeQL databases generated from C# codebases.
.. toctree::
:hidden:
basic-query-csharp
introduce-libraries-csharp
dataflow
- :doc:`Basic query for C# code <basic-query-csharp>`: Learn to write and run a simple CodeQL query using LGTM.
- :doc:`CodeQL library for C# <introduce-libraries-csharp>`: When you're analyzing a C# program, you can make use of the large collection of classes in the CodeQL library for C#.
- :doc:`Analyzing data flow in C# <dataflow>`: You can use CodeQL to track the flow of data through a C# program to its use.

0
docs/language/learn-ql/go/ast-class-reference.rst → docs/language/learn-ql/go/abstract-syntax-tree-classes-for-working-with-go-programs.rst
View File

4
docs/language/learn-ql/go/basic-query-go.rst → docs/language/learn-ql/go/basic-query-for-go-code.rst
View File

@@ -99,8 +99,8 @@ After the initial ``import`` statement, this simple query comprises three parts
| ``where recv = m.getReceiver() and | Defines a condition on the variables. | ``recv = m.getReceiver()`` states that ``recv`` must be the receiver variable of ``m``. |
| w.writesField(recv.getARead(), f, _) and | | |
| not recv.getType() instanceof PointerType`` | | ``w.writesField(recv.getARead(), f, _)`` states that ``w`` must be a location in the code where field ``f`` of ``recv`` is modified. |
| | | We use a `'don't-care' expression <https://help.semmle.com/QL/ql-handbook/expressions.html#don-t-care-expressions>`__ _ for the |
| | | value that is written to ``f``—the actual value doesn't matter in this query. |
| | | We use a `'don't-care' expression <https://help.semmle.com/QL/ql-language-reference/expressions.html#don-t-care-expressions>`__ ``_``|
| | | for the value that is written to ``f``—the actual value doesn't matter in this query. |
| | | |
| | | ``not recv.getType() instanceof PointerType`` states that ``m`` is not a pointer method. |
+---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+

21
docs/language/learn-ql/go/codeql-for-go.rst Normal file
View File

@@ -0,0 +1,21 @@
CodeQL for Go
=============
Experiment and learn how to write effective and efficient queries for CodeQL databases generated from Go codebases.
.. toctree::
:hidden:
basic-query-for-go-code
codeql-library-for-go
abstract-syntax-tree-classes-for-working-with-go-programs
modeling-data-flow-in-go-libraries
- :doc:`Basic query for Go code <basic-query-for-go-code>`: Learn to write and run a simple CodeQL query using LGTM.
- :doc:`CodeQL library for Go <codeql-library-for-go>`: When you're analyzing a Go program, you can make use of the large collection of classes in the CodeQL library for Go.
- :doc:`Abstract syntax tree classes for working with Go programs <abstract-syntax-tree-classes-for-working-with-go-programs>`: CodeQL has a large selection of classes for representing the abstract syntax tree of Go programs.
- :doc:`Modeling data flow in Go libraries <modeling-data-flow-in-go-libraries>`: When analyzing a Go program, CodeQL does not examine the source code for external packages.
To track the flow of untrusted data through a library, you can create a model of the library.

4
docs/language/learn-ql/go/introduce-libraries-go.rst → docs/language/learn-ql/go/codeql-library-for-go.rst
View File

@@ -100,7 +100,7 @@ statements and expressions, respectively. This section briefly discusses some of
important subclasses and predicates. For a full reference of all the subclasses of `Stmt
<https://help.semmle.com/qldoc/go/semmle/go/Stmt.qll/type.Stmt$Stmt.html>`__ and `Expr
<https://help.semmle.com/qldoc/go/semmle/go/Expr.qll/type.Expr$Expr.html>`__, see
:doc:`Abstract syntax tree classes for Go <ast-class-reference>`.
:doc:`Abstract syntax tree classes for Go <abstract-syntax-tree-classes-for-working-with-go-programs>`.
Statements
~~~~~~~~~~
@@ -502,7 +502,7 @@ taint, you can define a subclass of ``TaintTracking::Configuration``, which work
data-flow configurations.
A detailed exposition of global data flow and taint tracking is out of scope for this brief
introduction. For a general overview of data flow and taint tracking, see "`About data flow analysis <https://help.semmle.com/QL/learn-ql/intro-to-data-flow.html>`__."
introduction. For a general overview of data flow and taint tracking, see "`About data flow analysis <https://help.semmle.com/QL/learn-ql/about-data-flow-analysis.html>`__."
Advanced libraries
------------------

0
docs/language/learn-ql/go/library-modeling-go.rst → docs/language/learn-ql/go/modeling-data-flow-in-go-libraries.rst
View File

21
docs/language/learn-ql/go/ql-for-go.rst
View File

@@ -1,21 +0,0 @@
CodeQL for Go
=============
Experiment and learn how to write effective and efficient queries for CodeQL databases generated from Go codebases.
.. toctree::
:hidden:
basic-query-go
introduce-libraries-go
ast-class-reference
library-modeling-go
- :doc:`Basic query for Go code <basic-query-go>`: Learn to write and run a simple CodeQL query using LGTM.
- :doc:`CodeQL library for Go <introduce-libraries-go>`: When you're analyzing a Go program, you can make use of the large collection of classes in the CodeQL library for Go.
- :doc:`Abstract syntax tree classes for working with Go programs <ast-class-reference>`: CodeQL has a large selection of classes for representing the abstract syntax tree of Go programs.
- :doc:`Modeling data flow in Go libraries <library-modeling-go>`: When analyzing a Go program, CodeQL does not examine the source code for external packages.
To track the flow of untrusted data through a library, you can create a model of the library.

16
docs/language/learn-ql/index.rst
View File

@@ -19,13 +19,13 @@ CodeQL is based on a powerful query language called QL. The following topics hel
:maxdepth: 1
beginner/ql-tutorials
writing-queries/writing-queries
cpp/ql-for-cpp
csharp/ql-for-csharp
go/ql-for-go
java/ql-for-java
javascript/ql-for-javascript
python/ql-for-python
writing-queries/codeql-queries
cpp/codeql-for-cpp
csharp/codeql-for-csharp
go/codeql-for-go
java/codeql-for-java
javascript/codeql-for-javascript
python/codeql-for-python
ql-training
.. toctree::
@@ -36,4 +36,4 @@ CodeQL is based on a powerful query language called QL. The following topics hel
Further reading
***************
- `QL language reference <https://help.semmle.com/QL/ql-handbook/index.html>`__: A description of important concepts in QL and a formal specification of the QL language.
- `QL language reference <https://help.semmle.com/QL/ql-language-reference/index.html>`__: A description of important concepts in QL and a formal specification of the QL language.

10
docs/language/learn-ql/introduction-to-ql.rst
View File

@@ -15,13 +15,13 @@ QL also supports recursion and aggregates. This allows you to write complex recu
Running a query
---------------
You can try out the following examples and exercises using `CodeQL for VS Code <https://help.semmle.com/codeql/codeql-for-vscode.html>`__, or you can run them in the `query console on LGTM.com <https://lgtm.com/query>`__. Before you can run a query on LGTM.com, you need to select a language and project to query (for these logic examples, any language and project will do).
You can try out the following examples and exercises using `CodeQL for VS Code <https://help.semmle.com/codeql/codeql-for-visual-studio-code.html>`__, or you can run them in the `query console on LGTM.com <https://lgtm.com/query>`__. Before you can run a query on LGTM.com, you need to select a language and project to query (for these logic examples, any language and project will do).
Once you have selected a language, the query console is populated with the query:
.. code-block:: ql
import <language>
import <ql-language-specification>
select "hello world"
@@ -53,7 +53,7 @@ You can write simple queries using the some of the basic functions that are avai
Exercise 1
~~~~~~~~~~
Write a query which returns the length of the string ``"lgtm"``. (Hint: `here <https://help.semmle.com/QL/ql-spec/language.html#built-ins-for-string>`__ is the list of the functions that can be applied to strings.)
Write a query which returns the length of the string ``"lgtm"``. (Hint: `here <ql-language-specification#built-ins-for-string>`__ is the list of the functions that can be applied to strings.)
➤ `See answer in the query console on LGTM.com <https://lgtm.com/query/2103060623/>`__
@@ -122,7 +122,7 @@ The following example queries *do* use these databases and give you an idea of h
Queries using the CodeQL libraries can find errors and uncover variants of important security vulnerabilities in codebases.
Visit `GitHub Security Lab <https://securitylab.github.com/>`__ to read about examples of vulnerabilities that we have recently found in open source projects.
To import the CodeQL library for a specific programming language, type ``import <language>`` at the start of the query.
To import the CodeQL library for a specific programming language, type ``import <ql-language-specification>`` at the start of the query.
.. code-block:: ql
@@ -159,4 +159,4 @@ Further reading
- To find out more about how to write your own queries, try working through the ":doc:`QL tutorials <beginner/ql-tutorials>`."
- For an overview of the other available resources, see ":doc:`Learning CodeQL <../index>`."
- For a more technical description of the underlying language, see the "`QL language reference <https://help.semmle.com/QL/ql-handbook>`__."
- For a more technical description of the underlying language, see the "`QL language reference <https://help.semmle.com/QL/ql-language-reference>`__."

0
docs/language/learn-ql/java/ast-class-reference.rst → docs/language/learn-ql/java/abstract-syntax-tree-classes-for-working-with-go-programs.rst
View File

4
docs/language/learn-ql/java/dataflow.rst → docs/language/learn-ql/java/analyzing-data-flow-in-java.rst
View File

@@ -9,7 +9,7 @@ About this article
This article describes how data flow analysis is implemented in the CodeQL libraries for Java and includes examples to help you write your own data flow queries.
The following sections describe how to use the libraries for local data flow, global data flow, and taint tracking.
For a more general introduction to modeling data flow, see ":doc:`About data flow analysis <../intro-to-data-flow>`."
For a more general introduction to modeling data flow, see ":doc:`About data flow analysis <../about-data-flow-analysis>`."
Local data flow
---------------
@@ -358,7 +358,7 @@ Exercise 4
Further reading
---------------
- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-paths.html>`__"
- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-data-flow-with-path-queries.html>`__"
.. include:: ../../reusables/java-further-reading.rst

2
docs/language/learn-ql/java/annotations.rst → docs/language/learn-ql/java/annotations-in-java.rst
View File

@@ -180,7 +180,7 @@ Finally, we use these classes to find calls to deprecated methods, excluding cal
In our example, this query flags the call to ``A.m`` in ``A.r``, but not the one in ``A.n``.
For more information about the class ``Call``, see ":doc:`Navigating the call graph <call-graph>`."
For more information about the class ``Call``, see ":doc:`Navigating the call graph <navigating-the-call-graph>`."
Improvements
~~~~~~~~~~~~

0
docs/language/learn-ql/java/basic-query-java.rst → docs/language/learn-ql/java/basic-query-for-java-code.rst
View File

39
docs/language/learn-ql/java/codeql-for-java.rst Normal file
View File

@@ -0,0 +1,39 @@
CodeQL for Java
===============
Experiment and learn how to write effective and efficient queries for CodeQL databases generated from Java codebases.
.. toctree::
:hidden:
basic-query-for-java-code
codeql-library-for-java
analyzing-data-flow-in-java
types-in-java
overflow-prone-comparisons-in-java
navigating-the-call-graph
annotations-in-java
javadoc
working-with-source-locations
abstract-syntax-tree-classes-for-working-with-go-programs
- :doc:`Basic query for Java code <basic-query-for-java-code>`: Learn to write and run a simple CodeQL query using LGTM.
- :doc:`CodeQL library for Java <codeql-library-for-java>`: When analyzing Java code, you can use the large collection of classes in the CodeQL library for Java.
- :doc:`Analyzing data flow in Java <analyzing-data-flow-in-java>`: You can use CodeQL to track the flow of data through a Java program to its use.
- :doc:`Java types <types-in-java>`: You can use CodeQL to find out information about data types used in Java code. This allows you to write queries to identify specific type-related issues.
- :doc:`Overflow-prone comparisons in Java <overflow-prone-comparisons-in-java>`: You can use CodeQL to check for comparisons in Java code where one side of the comparison is prone to overflow.
- :doc:`Navigating the call graph <navigating-the-call-graph>`: CodeQL has classes for identifying code that calls other code, and code that can be called from elsewhere. This allows you to find, for example, methods that are never used.
- :doc:`Annotations in Java <annotations-in-java>`: CodeQL databases of Java projects contain information about all annotations attached to program elements.
- :doc:`Javadoc <javadoc>`: You can use CodeQL to find errors in Javadoc comments in Java code.
- :doc:`Working with source locations <working-with-source-locations>`: You can use the location of entities within Java code to look for potential errors. Locations allow you to deduce the presence, or absence, of white space which, in some cases, may indicate a problem.
- :doc:`Abstract syntax tree classes for working with Java programs <abstract-syntax-tree-classes-for-working-with-go-programs>`: CodeQL has a large selection of classes for representing the abstract syntax tree of Java programs.

12
docs/language/learn-ql/java/introduce-libraries-java.rst → docs/language/learn-ql/java/codeql-library-for-java.rst
View File

@@ -196,7 +196,7 @@ The wildcards ``? extends Number`` and ``? super Float`` are represented by clas
For dealing with generic methods, there are classes ``GenericMethod``, ``ParameterizedMethod`` and ``RawMethod``, which are entirely analogous to the like-named classes for representing generic types.
For more information on working with types, see the :doc:`article on Java types <types-class-hierarchy>`.
For more information on working with types, see the :doc:`article on Java types <types-in-java>`.
Variables
~~~~~~~~~
@@ -210,7 +210,7 @@ Class ``Variable`` represents a variable `in the Java sense <https://docs.oracle
Abstract syntax tree
--------------------
Classes in this category represent abstract syntax tree (AST) nodes, that is, statements (class ``Stmt``) and expressions (class ``Expr``). For a full list of expression and statement types available in the standard QL library, see ":doc:`Abstract syntax tree classes for working with Java programs <ast-class-reference>`."
Classes in this category represent abstract syntax tree (AST) nodes, that is, statements (class ``Stmt``) and expressions (class ``Expr``). For a full list of expression and statement types available in the standard QL library, see ":doc:`Abstract syntax tree classes for working with Java programs <abstract-syntax-tree-classes-for-working-with-go-programs>`."
Both ``Expr`` and ``Stmt`` provide member predicates for exploring the abstract syntax tree of a program:
@@ -260,7 +260,7 @@ Finally, here is a query that finds method bodies:
As these examples show, the parent node of an expression is not always an expression: it may also be a statement, for example, an ``IfStmt``. Similarly, the parent node of a statement is not always a statement: it may also be a method or a constructor. To capture this, the QL Java library provides two abstract class ``ExprParent`` and ``StmtParent``, the former representing any node that may be the parent node of an expression, and the latter any node that may be the parent node of a statement.
For more information on working with AST classes, see the :doc:`article on overflow-prone comparisons in Java <expressions-statements>`.
For more information on working with AST classes, see the :doc:`article on overflow-prone comparisons in Java <overflow-prone-comparisons-in-java>`.
Metadata
--------
@@ -292,7 +292,7 @@ These annotations are represented by class ``Annotation``. An annotation is simp
➤ `See this in the query console on LGTM.com <https://lgtm.com/query/5393027107459215059/>`__. Only constructors with the ``@Deprecated`` annotation are reported this time.
For more information on working with annotations, see the :doc:`article on annotations <annotations>`.
For more information on working with annotations, see the :doc:`article on annotations <annotations-in-java>`.
For Javadoc, class ``Element`` has a member predicate ``getDoc`` that returns a delegate ``Documentable`` object, which can then be queried for its attached Javadoc comments. For example, the following query finds Javadoc comments on private fields:
@@ -379,9 +379,9 @@ Conversely, ``Callable.getAReference`` returns a ``Call`` that refers to it. So
where not exists(c.getAReference())
select c
➤ `See this in the query console on LGTM.com <https://lgtm.com/query/7261739919657747703/>`__. The LGTM.com demo projects all appear to have many methods that are not called directly, but this is unlikely to be the whole story. To explore this area further, see ":doc:`Navigating the call graph <call-graph>`."
➤ `See this in the query console on LGTM.com <https://lgtm.com/query/7261739919657747703/>`__. The LGTM.com demo projects all appear to have many methods that are not called directly, but this is unlikely to be the whole story. To explore this area further, see ":doc:`Navigating the call graph <navigating-the-call-graph>`."
For more information about callables and calls, see the :doc:`article on the call graph <call-graph>`.
For more information about callables and calls, see the :doc:`article on the call graph <navigating-the-call-graph>`.
Further reading
---------------

0
docs/language/learn-ql/java/call-graph.rst → docs/language/learn-ql/java/navigating-the-call-graph.rst
View File

4
docs/language/learn-ql/java/expressions-statements.rst → docs/language/learn-ql/java/overflow-prone-comparisons-in-java.rst
View File

@@ -26,7 +26,7 @@ If ``l`` is bigger than 2\ :sup:`31`\ - 1 (the largest positive value of type ``
All primitive numeric types have a maximum value, beyond which they will wrap around to their lowest possible value (called an "overflow"). For ``int``, this maximum value is 2\ :sup:`31`\ - 1. Type ``long`` can accommodate larger values up to a maximum of 2\ :sup:`63`\ - 1. In this example, this means that ``l`` can take on a value that is higher than the maximum for type ``int``; ``i`` will never be able to reach this value, instead overflowing and returning to a low value.
We're going to develop a query that finds code that looks like it might exhibit this kind of behavior. We'll be using several of the standard library classes for representing statements and functions. For a full list, see ":doc:`Abstract syntax tree classes for working with Java programs <ast-class-reference>`."
We're going to develop a query that finds code that looks like it might exhibit this kind of behavior. We'll be using several of the standard library classes for representing statements and functions. For a full list, see ":doc:`Abstract syntax tree classes for working with Java programs <abstract-syntax-tree-classes-for-working-with-go-programs>`."
Initial query
-------------
@@ -61,7 +61,7 @@ Notice that we use the predicate ``getType`` (available on all subclasses of ``E
The class ``LoopStmt`` is a common superclass of all loops, including, in particular, ``for`` loops as in our example above. While different kinds of loops have different syntax, they all have a loop condition, which can be accessed through predicate ``getCondition``. We use the reflexive transitive closure operator ``*`` applied to the ``getAChildExpr`` predicate to express the requirement that ``expr`` should be nested inside the loop condition. In particular, it can be the loop condition itself.
The final conjunct in the ``where`` clause takes advantage of the fact that `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ can return more than one value (they are really relations). In particular, ``getAnOperand`` may return *either* operand of ``expr``, so ``expr.getAnOperand().isCompileTimeConstant()`` holds if at least one of the operands is constant. Negating this condition means that the query will only find expressions where *neither* of the operands is constant.
The final conjunct in the ``where`` clause takes advantage of the fact that `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ can return more than one value (they are really relations). In particular, ``getAnOperand`` may return *either* operand of ``expr``, so ``expr.getAnOperand().isCompileTimeConstant()`` holds if at least one of the operands is constant. Negating this condition means that the query will only find expressions where *neither* of the operands is constant.
Generalizing the query
----------------------

39
docs/language/learn-ql/java/ql-for-java.rst
View File

@@ -1,39 +0,0 @@
CodeQL for Java
===============
Experiment and learn how to write effective and efficient queries for CodeQL databases generated from Java codebases.
.. toctree::
:hidden:
basic-query-java
introduce-libraries-java
dataflow
types-class-hierarchy
expressions-statements
call-graph
annotations
javadoc
source-locations
ast-class-reference
- :doc:`Basic query for Java code <basic-query-java>`: Learn to write and run a simple CodeQL query using LGTM.
- :doc:`CodeQL library for Java <introduce-libraries-java>`: When analyzing Java code, you can use the large collection of classes in the CodeQL library for Java.
- :doc:`Analyzing data flow in Java <dataflow>`: You can use CodeQL to track the flow of data through a Java program to its use.
- :doc:`Java types <types-class-hierarchy>`: You can use CodeQL to find out information about data types used in Java code. This allows you to write queries to identify specific type-related issues.
- :doc:`Overflow-prone comparisons in Java <expressions-statements>`: You can use CodeQL to check for comparisons in Java code where one side of the comparison is prone to overflow.
- :doc:`Navigating the call graph <call-graph>`: CodeQL has classes for identifying code that calls other code, and code that can be called from elsewhere. This allows you to find, for example, methods that are never used.
- :doc:`Annotations in Java <annotations>`: CodeQL databases of Java projects contain information about all annotations attached to program elements.
- :doc:`Javadoc <javadoc>`: You can use CodeQL to find errors in Javadoc comments in Java code.
- :doc:`Working with source locations <source-locations>`: You can use the location of entities within Java code to look for potential errors. Locations allow you to deduce the presence, or absence, of white space which, in some cases, may indicate a problem.
- :doc:`Abstract syntax tree classes for working with Java programs <ast-class-reference>`: CodeQL has a large selection of classes for representing the abstract syntax tree of Java programs.

0
docs/language/learn-ql/java/types-class-hierarchy.rst → docs/language/learn-ql/java/types-in-java.rst
View File

0
docs/language/learn-ql/java/source-locations.rst → docs/language/learn-ql/java/working-with-source-locations.rst
View File

0
docs/language/learn-ql/javascript/ast-class-reference.rst → docs/language/learn-ql/javascript/abstract-syntax-tree-classes-for-working-with-javascript-and-typescript-programs.rst
View File

4
docs/language/learn-ql/javascript/dataflow.rst → docs/language/learn-ql/javascript/analyzing-data-flow-in-javascript.rst
View File

@@ -9,7 +9,7 @@ The various sections in this article describe how to utilize the libraries for l
As our running example, we will develop a query that identifies command-line arguments that are passed as a file path to the standard Node.js ``readFile`` function.
While this is not a problematic pattern as such, it is typical of the kind of reasoning that is frequently used in security queries.
For a more general introduction to modeling data flow, see ":doc:`About data flow analysis <../intro-to-data-flow>`."
For a more general introduction to modeling data flow, see ":doc:`About data flow analysis <../about-data-flow-analysis>`."
Data flow nodes
---------------
@@ -554,7 +554,7 @@ Exercise 4
Further reading
---------------
- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-paths.html>`__"
- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-data-flow-with-path-queries.html>`__"
.. include:: ../../reusables/java-further-reading.rst

0
docs/language/learn-ql/javascript/basic-query-javascript.rst → docs/language/learn-ql/javascript/basic-query-for-javascript-code.rst
View File

32
docs/language/learn-ql/javascript/codeql-for-javascript.rst Normal file
View File

@@ -0,0 +1,32 @@
CodeQL for JavaScript
=====================
Experiment and learn how to write effective and efficient queries for CodeQL databases generated from JavaScript codebases.
.. toctree::
:hidden:
basic-query-for-javascript-code
codeql-library-for-javascript
codeql-library-for-typescript
analyzing-data-flow-in-javascript
using-flow-labels-for-precise-data-flow-analysis
using-type-tracking-for-api-modeling
abstract-syntax-tree-classes-for-working-with-javascript-and-typescript-programs
data-flow-cheat-sheet-for-javascript
- :doc:`Basic query for JavaScript code <basic-query-for-javascript-code>`: Learn to write and run a simple CodeQL query using LGTM.
- :doc:`CodeQL library for JavaScript <codeql-library-for-javascript>`: When you're analyzing a JavaScript program, you can make use of the large collection of classes in the CodeQL library for JavaScript.
- :doc:`CodeQL library for TypeScript <codeql-library-for-typescript>`: When you're analyzing a TypeScript program, you can make use of the large collection of classes in the CodeQL library for TypeScript.
- :doc:`Analyzing data flow in JavaScript and TypeScript <analyzing-data-flow-in-javascript>`: This topic describes how data flow analysis is implemented in the CodeQL libraries for JavaScript/TypeScript and includes examples to help you write your own data flow queries.
- :doc:`Using flow labels for precise data flow analysis <using-flow-labels-for-precise-data-flow-analysis>`: You can associate flow labels with each value tracked by the flow analysis to determine whether the flow contains potential vulnerabilities.
- :doc:`Using type tracking for API modeling <using-type-tracking-for-api-modeling>`: You can track data through an API by creating a model using the CodeQL type-tracking library for JavaScript.
- :doc:`Abstract syntax tree classes for working with JavaScript and TypeScript programs <abstract-syntax-tree-classes-for-working-with-javascript-and-typescript-programs>`: CodeQL has a large selection of classes for representing the abstract syntax tree of JavaScript and TypeScript programs.
- :doc:`Data flow cheat sheet for JavaScript <data-flow-cheat-sheet-for-javascript>`: This article describes parts of the JavaScript libraries commonly used for variant analysis and in data flow queries.

0
docs/language/learn-ql/javascript/introduce-libraries-js.rst → docs/language/learn-ql/javascript/codeql-library-for-javascript.rst
View File

2
docs/language/learn-ql/javascript/introduce-libraries-ts.rst → docs/language/learn-ql/javascript/codeql-library-for-typescript.rst
View File

@@ -12,7 +12,7 @@ Support for analyzing TypeScript code is bundled with the CodeQL libraries for J
import javascript
:doc:`CodeQL libraries for JavaScript <introduce-libraries-js>` covers most of this library, and is also relevant for TypeScript analysis. This document supplements the JavaScript documentation with the TypeScript-specific classes and predicates.
:doc:`CodeQL libraries for JavaScript <codeql-library-for-javascript>` covers most of this library, and is also relevant for TypeScript analysis. This document supplements the JavaScript documentation with the TypeScript-specific classes and predicates.
Syntax
------

10
docs/language/learn-ql/javascript/dataflow-cheat-sheet.rst → docs/language/learn-ql/javascript/data-flow-cheat-sheet-for-javascript.rst
View File

@@ -34,12 +34,12 @@ This query reports flow paths which:
- Step through variables, function calls, properties, strings, arrays, promises, exceptions, and steps added by `isAdditionalTaintStep <https://help.semmle.com/qldoc/javascript/semmle/javascript/dataflow/TaintTracking.qll/predicate.TaintTracking$TaintTracking$Configuration$isAdditionalTaintStep.2.html>`__.
- End at a node matched by `isSink <https://help.semmle.com/qldoc/javascript/semmle/javascript/dataflow/Configuration.qll/predicate.Configuration$Configuration$isSink.1.html>`__.
See also: "`Global data flow <https://help.semmle.com/QL/learn-ql/javascript/dataflow.html#global-data-flow>`__" and ":doc:`Creating path queries <../writing-queries/path-queries>`."
See also: "`Global data flow <https://help.semmle.com/QL/learn-ql/javascript/dataflow.html#global-data-flow>`__" and ":doc:`Creating path queries <../writing-queries/creating-path-queries>`."
DataFlow module
---------------
Use data flow nodes to match program elements independently of syntax. See also: ":doc:`Analyzing data flow in JavaScript and TypeScript <dataflow>`."
Use data flow nodes to match program elements independently of syntax. See also: ":doc:`Analyzing data flow in JavaScript and TypeScript <analyzing-data-flow-in-javascript>`."
Predicates in the ``DataFlow::`` module:
@@ -142,7 +142,7 @@ Files
AST nodes
---------
See also: ":doc:`Abstract syntax tree classes for working with JavaScript and TypeScript programs <ast-class-reference>`."
See also: ":doc:`Abstract syntax tree classes for working with JavaScript and TypeScript programs <abstract-syntax-tree-classes-for-working-with-javascript-and-typescript-programs>`."
Conversion between DataFlow and AST nodes:
@@ -163,7 +163,7 @@ String matching
Type tracking
-------------
See also: ":doc:`Using type tracking for API modeling <type-tracking>`."
See also: ":doc:`Using type tracking for API modeling <using-type-tracking-for-api-modeling>`."
Use the following template to define forward type tracking predicates:
@@ -220,7 +220,7 @@ Troubleshooting
Further reading
---------------
- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-paths.html>`__"
- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-data-flow-with-path-queries.html>`__"
.. include:: ../../reusables/javascript-further-reading.rst

32
docs/language/learn-ql/javascript/ql-for-javascript.rst
View File

@@ -1,32 +0,0 @@
CodeQL for JavaScript
=====================
Experiment and learn how to write effective and efficient queries for CodeQL databases generated from JavaScript codebases.
.. toctree::
:hidden:
basic-query-javascript
introduce-libraries-js
introduce-libraries-ts
dataflow
flow-labels
type-tracking
ast-class-reference
dataflow-cheat-sheet
- :doc:`Basic query for JavaScript code <basic-query-javascript>`: Learn to write and run a simple CodeQL query using LGTM.
- :doc:`CodeQL library for JavaScript <introduce-libraries-js>`: When you're analyzing a JavaScript program, you can make use of the large collection of classes in the CodeQL library for JavaScript.
- :doc:`CodeQL library for TypeScript <introduce-libraries-ts>`: When you're analyzing a TypeScript program, you can make use of the large collection of classes in the CodeQL library for TypeScript.
- :doc:`Analyzing data flow in JavaScript and TypeScript <dataflow>`: This topic describes how data flow analysis is implemented in the CodeQL libraries for JavaScript/TypeScript and includes examples to help you write your own data flow queries.
- :doc:`Using flow labels for precise data flow analysis <flow-labels>`: You can associate flow labels with each value tracked by the flow analysis to determine whether the flow contains potential vulnerabilities.
- :doc:`Using type tracking for API modeling <type-tracking>`: You can track data through an API by creating a model using the CodeQL type-tracking library for JavaScript.
- :doc:`Abstract syntax tree classes for working with JavaScript and TypeScript programs <ast-class-reference>`: CodeQL has a large selection of classes for representing the abstract syntax tree of JavaScript and TypeScript programs.
- :doc:`Data flow cheat sheet for JavaScript <dataflow-cheat-sheet>`: This article describes parts of the JavaScript libraries commonly used for variant analysis and in data flow queries.

6
docs/language/learn-ql/javascript/flow-labels.rst → docs/language/learn-ql/javascript/using-flow-labels-for-precise-data-flow-analysis.rst
View File

@@ -7,7 +7,7 @@ Overview
--------
You can use basic inter-procedural data-flow analysis and taint tracking as described in
":doc:`Analyzing data flow in JavaScript and TypeScript <dataflow>`" to check whether there is a path in
":doc:`Analyzing data flow in JavaScript and TypeScript <analyzing-data-flow-in-javascript>`" to check whether there is a path in
the data-flow graph from some source node to a sink node that does not pass through any sanitizer
nodes. Another way of thinking about this is that it statically models the flow of data through the
program, and associates a flag with every data value telling us whether it might have come from a
@@ -267,7 +267,7 @@ sanitized value:
}
}
Here is the final query, expressed as a :doc:`path query <../writing-queries/path-queries>` so we can examine paths from sources to sinks
Here is the final query, expressed as a :doc:`path query <../writing-queries/creating-path-queries>` so we can examine paths from sources to sinks
step by step in the UI:
.. code-block:: ql
@@ -398,7 +398,7 @@ string may be an absolute path and whether it may contain ``..`` components.
Further reading
---------------
- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-paths.html>`__"
- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-data-flow-with-path-queries.html>`__"
.. include:: ../../reusables/javascript-further-reading.rst

8
docs/language/learn-ql/javascript/type-tracking.rst → docs/language/learn-ql/javascript/using-type-tracking-for-api-modeling.rst
View File

@@ -10,7 +10,7 @@ usually to recognize method calls and properties accessed on a specific type of
This is an advanced topic and is intended for readers already familiar with the
`SourceNode <https://help.semmle.com/QL/learn-ql/javascript/dataflow.html#source-nodes>`__ class as well as
`taint tracking <https://help.semmle.com/QL/learn-ql/javascript/dataflow.html#using-global-taint-tracking>`__.
`taint tracking <https://help.semmle.com/QL/learn-ql/javascript/dataflow.html#using-global-analyzing-data-flow-and-tracking-tainted-data-in-python>`__.
For TypeScript analysis also consider reading about `static type information <https://help.semmle.com/QL/learn-ql/javascript/introduce-libraries-ts.html#static-type-information>`__ first.
@@ -489,11 +489,11 @@ Prefer type tracking when:
Prefer data-flow configurations when:
- Tracking user-controlled data -- use `taint tracking <https://help.semmle.com/QL/learn-ql/javascript/dataflow.html#using-global-taint-tracking>`__.
- Differentiating between different kinds of user-controlled data -- see ":doc:`Using flow labels for precise data flow analysis <flow-labels>`."
- Tracking user-controlled data -- use `taint tracking <https://help.semmle.com/QL/learn-ql/javascript/dataflow.html#using-global-analyzing-data-flow-and-tracking-tainted-data-in-python>`__.
- Differentiating between different kinds of user-controlled data -- see ":doc:`Using flow labels for precise data flow analysis <using-flow-labels-for-precise-data-flow-analysis>`."
- Tracking transformations of a value through generic utility functions.
- Tracking values through string manipulation.
- Generating a path from source to sink -- see ":doc:`Creating path queries <../writing-queries/path-queries>`."
- Generating a path from source to sink -- see ":doc:`Creating path queries <../writing-queries/creating-path-queries>`."
Lastly, depending on the code base being analyzed, some alternatives to consider are:

0
docs/language/learn-ql/locations.rst → docs/language/learn-ql/providing-locations-in-codeql-queries.rst
View File

2
docs/language/learn-ql/python/control-flow.rst → docs/language/learn-ql/python/analyzing-control-flow-in-python.rst
View File

@@ -112,7 +112,7 @@ Example finding mutually exclusive blocks within the same function
)
select b1, b2
➤ `See this in the query console on LGTM.com <https://lgtm.com/query/671000028/>`__. This typically gives a very large number of results, because it is a common occurrence in normal control flow. It is, however, an example of the sort of control-flow analysis that is possible. Control-flow analyses such as this are an important aid to data flow analysis. For more information, see ":doc:`Analyzing data flow and tracking tainted data in Python <taint-tracking>`."
➤ `See this in the query console on LGTM.com <https://lgtm.com/query/671000028/>`__. This typically gives a very large number of results, because it is a common occurrence in normal control flow. It is, however, an example of the sort of control-flow analysis that is possible. Control-flow analyses such as this are an important aid to data flow analysis. For more information, see ":doc:`Analyzing data flow and tracking tainted data in Python <analyzing-data-flow-and-tracking-tainted-data-in-python>`."
Further reading
---------------

6
docs/language/learn-ql/python/taint-tracking.rst → docs/language/learn-ql/python/analyzing-data-flow-and-tracking-tainted-data-in-python.rst
View File

@@ -15,10 +15,10 @@ Taint tracking differs from basic data flow in that it considers non-value-prese
For example, in the assignment ``dir = path + "/"``, if ``path`` is tainted then ``dir`` is also tainted,
even though there is no data flow from ``path`` to ``path + "/"``.
Separate CodeQL libraries have been written to handle 'normal' data flow and taint tracking in :doc:`C/C++ <../cpp/dataflow>`, :doc:`C# <../csharp/dataflow>`, :doc:`Java <../java/dataflow>`, and :doc:`JavaScript <../javascript/dataflow>`. You can access the appropriate classes and predicates that reason about these different modes of data flow by importing the appropriate library in your query.
Separate CodeQL libraries have been written to handle 'normal' data flow and taint tracking in :doc:`C/C++ <../cpp/analyzing-data-flow-in-cpp>`, :doc:`C# <../csharp/analyzing-data-flow-in-csharp>`, :doc:`Java <../java/analyzing-data-flow-in-java>`, and :doc:`JavaScript <../javascript/analyzing-data-flow-in-javascript>`. You can access the appropriate classes and predicates that reason about these different modes of data flow by importing the appropriate library in your query.
In Python analysis, we can use the same taint tracking library to model both 'normal' data flow and taint flow, but we are still able make the distinction between steps that preserve values and those that don't by defining additional data flow properties.
For further information on data flow and taint tracking with CodeQL, see ":doc:`Introduction to data flow <../intro-to-data-flow>`."
For further information on data flow and taint tracking with CodeQL, see ":doc:`Introduction to data flow <../about-data-flow-analysis>`."
Fundamentals of taint tracking using data flow analysis
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -259,7 +259,7 @@ which defines the simplest possible taint kind class, ``HardcodedValue``, and cu
Further reading
---------------
- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-paths.html>`__"
- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-data-flow-with-path-queries.html>`__"
.. include:: ../../reusables/python-further-reading.rst

0
docs/language/learn-ql/python/basic-query-python.rst → docs/language/learn-ql/python/basic-query-for-python-code.rst
View File

29
docs/language/learn-ql/python/codeql-for-python.rst Normal file
View File

@@ -0,0 +1,29 @@
CodeQL for Python
=================
Experiment and learn how to write effective and efficient queries for CodeQL databases generated from Python codebases.
.. toctree::
:hidden:
basic-query-for-python-code
codeql-library-for-python
functions-in-python
expressions-and-statements-in-python
pointer-analysis-and-type-inference-in-python
analyzing-control-flow-in-python
analyzing-data-flow-and-tracking-tainted-data-in-python
- :doc:`Basic query for Python code <basic-query-for-python-code>`: Learn to write and run a simple CodeQL query using LGTM.
- :doc:`CodeQL library for Python <codeql-library-for-python>`: When you need to analyze a Python program, you can make use of the large collection of classes in the CodeQL library for Python.
- :doc:`Functions in Python <functions-in-python>`: You can use syntactic classes from the standard CodeQL library to find Python functions and identify calls to them.
- :doc:`Expressions and statements in Python <expressions-and-statements-in-python>`: You can use syntactic classes from the CodeQL library to explore how Python expressions and statements are used in a codebase.
- :doc:`Analyzing control flow in Python <analyzing-control-flow-in-python>`: You can write CodeQL queries to explore the control-flow graph of a Python program, for example, to discover unreachable code or mutually exclusive blocks of code.
- :doc:`Pointer analysis and type inference in Python <pointer-analysis-and-type-inference-in-python>`: At runtime, each Python expression has a value with an associated type. You can learn how an expression behaves at runtime by using type-inference classes from the standard CodeQL library.
- :doc:`Analyzing data flow and tracking tainted data in Python <analyzing-data-flow-and-tracking-tainted-data-in-python>`: You can use CodeQL to track the flow of data through a Python program. Tracking user-controlled, or tainted, data is a key technique for security researchers.

4
docs/language/learn-ql/python/introduce-libraries-python.rst → docs/language/learn-ql/python/codeql-library-for-python.rst
View File

@@ -320,7 +320,7 @@ Summary
- ``CallableValue``
- ``ModuleValue``
For more information about these classes, see ":doc:`Pointer analysis and type inference in Python <pointsto-type-infer>`."
For more information about these classes, see ":doc:`Pointer analysis and type inference in Python <pointer-analysis-and-type-inference-in-python>`."
Taint-tracking classes
----------------------
@@ -334,7 +334,7 @@ Summary
- `TaintKind <https://help.semmle.com/qldoc/python/semmle/python/dataflow/TaintTracking.qll/type.TaintTracking$TaintKind.html>`__
- `Configuration <https://help.semmle.com/qldoc/python/semmle/python/dataflow/Configuration.qll/type.Configuration$TaintTracking$Configuration.html>`__
For more information about these classes, see ":doc:`Analyzing data flow and tracking tainted data in Python <taint-tracking>`."
For more information about these classes, see ":doc:`Analyzing data flow and tracking tainted data in Python <analyzing-data-flow-and-tracking-tainted-data-in-python>`."
Further reading

2
docs/language/learn-ql/python/statements-expressions.rst → docs/language/learn-ql/python/expressions-and-statements-in-python.rst
View File

@@ -197,7 +197,7 @@ The short version is usually used as this is easier to read.
Example finding Java-style getters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Returning to the example from ":doc:`Functions in Python <functions>`," the query identified all methods with a single line of code and a name starting with ``get``.
Returning to the example from ":doc:`Functions in Python <functions-in-python>`," the query identified all methods with a single line of code and a name starting with ``get``.
.. code-block:: ql

4
docs/language/learn-ql/python/functions.rst → docs/language/learn-ql/python/functions-in-python.rst
View File

@@ -3,7 +3,7 @@ Functions in Python
You can use syntactic classes from the standard CodeQL library to find Python functions and identify calls to them.
These examples use the standard CodeQL class `Function <https://help.semmle.com/qldoc/python/semmle/python/Function.qll/type.Function$Function.html>`__. For more information, see ":doc:`CodeQL library for Python <introduce-libraries-python>`."
These examples use the standard CodeQL class `Function <https://help.semmle.com/qldoc/python/semmle/python/Function.qll/type.Function$Function.html>`__. For more information, see ":doc:`CodeQL library for Python <codeql-library-for-python>`."
Finding all functions called "get..."
-------------------------------------
@@ -57,7 +57,7 @@ We can modify the query further to include only methods whose body consists of a
and count(f.getAStmt()) = 1
select f, "This function is (probably) a getter."
➤ `See this in the query console on LGTM.com <https://lgtm.com/query/667290044/>`__. This query returns fewer results, but if you examine the results you can see that there are still refinements to be made. This is refined further in ":doc:`Expressions and statements in Python <statements-expressions>`."
➤ `See this in the query console on LGTM.com <https://lgtm.com/query/667290044/>`__. This query returns fewer results, but if you examine the results you can see that there are still refinements to be made. This is refined further in ":doc:`Expressions and statements in Python <expressions-and-statements-in-python>`."
Finding a call to a specific function
-------------------------------------

2
docs/language/learn-ql/python/pointsto-type-infer.rst → docs/language/learn-ql/python/pointer-analysis-and-type-inference-in-python.rst
View File

@@ -181,7 +181,7 @@ The ``Value`` class has a method ``getACall()`` which allows us to find calls to
If we wish to restrict the callables to actual functions we can use the ``FunctionValue`` class, which is a subclass of ``Value`` and corresponds to function objects in Python, in much the same way as the ``ClassValue`` class corresponds to class objects in Python.
Returning to an example from ":doc:`Functions in Python <functions>`," we wish to find calls to the ``eval`` function.
Returning to an example from ":doc:`Functions in Python <functions-in-python>`," we wish to find calls to the ``eval`` function.
The original query looked this:

29
docs/language/learn-ql/python/ql-for-python.rst
View File

@@ -1,29 +0,0 @@
CodeQL for Python
=================
Experiment and learn how to write effective and efficient queries for CodeQL databases generated from Python codebases.
.. toctree::
:hidden:
basic-query-python
introduce-libraries-python
functions
statements-expressions
pointsto-type-infer
control-flow
taint-tracking
- :doc:`Basic query for Python code <basic-query-python>`: Learn to write and run a simple CodeQL query using LGTM.
- :doc:`CodeQL library for Python <introduce-libraries-python>`: When you need to analyze a Python program, you can make use of the large collection of classes in the CodeQL library for Python.
- :doc:`Functions in Python <functions>`: You can use syntactic classes from the standard CodeQL library to find Python functions and identify calls to them.
- :doc:`Expressions and statements in Python <statements-expressions>`: You can use syntactic classes from the CodeQL library to explore how Python expressions and statements are used in a codebase.
- :doc:`Analyzing control flow in Python <control-flow>`: You can write CodeQL queries to explore the control-flow graph of a Python program, for example, to discover unreachable code or mutually exclusive blocks of code.
- :doc:`Pointer analysis and type inference in Python <pointsto-type-infer>`: At runtime, each Python expression has a value with an associated type. You can learn how an expression behaves at runtime by using type-inference classes from the standard CodeQL library.
- :doc:`Analyzing data flow and tracking tainted data in Python <taint-tracking>`: You can use CodeQL to track the flow of data through a Python program. Tracking user-controlled, or tainted, data is a key technique for security researchers.

2
docs/language/learn-ql/ql-training.rst
View File

@@ -25,7 +25,7 @@ When you have selected a presentation, use |arrow-r| and |arrow-l| to navigate b
Press **p** to view the additional notes on slides that have an information icon |info| in the top right corner, and press **f** to enter full-screen mode.
The presentations contain a number of query examples.
We recommend that you download `CodeQL for Visual Studio Code <https://help.semmle.com/codeql/codeql-for-vscode/procedures/setting-up.html>`__ and add the example database for each presentation so that you can find the bugs mentioned in the slides.
We recommend that you download `CodeQL for Visual Studio Code <https://help.semmle.com/codeql/codeql-for-vscode/procedures/setting-up-codeql-in-visual-studio-code.html>`__ and add the example database for each presentation so that you can find the bugs mentioned in the slides.
.. pull-quote::

32
docs/language/learn-ql/writing-queries/introduction-to-queries.rst → docs/language/learn-ql/writing-queries/about-codeql-queries.rst
View File

@@ -13,13 +13,13 @@ CodeQL includes queries to find the most relevant and interesting problems for e
You can add custom queries to `custom query packs <https://lgtm.com/help/lgtm/about-queries#what-are-query-packs>`__ to analyze your projects in `LGTM <https://lgtm.com>`__, use them to analyze a database with the "`CodeQL CLI <https://help.semmle.com/codeql/codeql-cli.html>`__," 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 `here <https://help.semmle.com/QL/learn-ql/>`__, and detailed technical information about QL in the `QL language reference <https://help.semmle.com/QL/ql-handbook/index.html>`__.
This topic is a basic introduction to query files. You can find more information on writing queries for specific programming languages `here <https://help.semmle.com/QL/learn-ql/>`__, and detailed technical information about QL in the `QL language reference <https://help.semmle.com/QL/ql-language-reference/index.html>`__.
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>`__.
Basic query structure
*********************
`Queries <https://help.semmle.com/QL/ql-handbook/queries.html>`__ written with CodeQL have the file extension ``.ql``, and contain a ``select`` clause. Many of the existing queries include additional optional information, and have the following structure::
`Queries <https://help.semmle.com/QL/ql-language-reference/queries.html>`__ written with CodeQL have the file extension ``.ql``, and contain a ``select`` clause. Many of the existing queries include additional optional information, and have the following structure::
/**
*
@@ -35,17 +35,17 @@ Basic query structure
where /* ... logical formula ... */
select /* ... expressions ... */
The following sections describe the information that is typically included in a query file for alerts. Path queries are discussed in more detail in ":doc:`Creating path queries <path-queries>`."
The following sections describe the information that is typically included in a query file for alerts. Path queries are discussed in more detail in ":doc:`Creating path queries <creating-path-queries>`."
Query metadata
==============
Query metadata is used to identify your custom queries when they are added to the GitHub repository or used in your analysis. Metadata provides information about the query's purpose, and also specifies how to interpret and display the query results. For a full list of metadata properties, see ":doc:`Metadata for CodeQL queries <query-metadata>`." The exact metadata requirement depends on how you are going to run your query:
Query metadata is used to identify your custom queries when they are added to the GitHub repository or used in your analysis. Metadata provides information about the query's purpose, and also specifies how to interpret and display the query results. For a full list of metadata properties, see ":doc:`Metadata for CodeQL queries <metadata-for-codeql-queries>`." The exact metadata requirement depends on how you are going to run your query:
- If you are contributing a query to the GitHub repository, please read the `query metadata style guide <https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md>`__.
- If you are adding a custom query to a query pack for analysis using LGTM , see `Writing custom queries to include in LGTM analysis <https://lgtm.com/help/lgtm/writing-custom-queries>`__.
- If you are adding a custom query to a query pack for analysis using LGTM , see `Writing custom queries to include in LGTM analysis <https://lgtm.com/help/lgtm/writing-using-custom-queries-with-the-codeql-cli>`__.
- If you are analyzing a database using the `CodeQL CLI <https://help.semmle.com/codeql/codeql-cli.html>`__, your query metadata must contain ``@kind``.
- If you are running a query in the query console on LGTM or with the CodeQL extension for VS Code, metadata is not mandatory. However, if you want your results to be displayed as either an 'alert' or a 'path', you must specify the correct ``@kind`` property, as explained below. For more information, see `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__ on LGTM.com and "`Analyzing your projects <https://help.semmle.com/codeql/codeql-for-vscode/procedures/using-extension.html>`__" in the CodeQL for VS Code help.
- If you are running a query in the query console on LGTM or with the CodeQL extension for VS Code, metadata is not mandatory. However, if you want your results to be displayed as either an 'alert' or a 'path', you must specify the correct ``@kind`` property, as explained below. For more information, see `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__ on LGTM.com and "`Analyzing your projects <https://help.semmle.com/codeql/codeql-for-vscode/procedures/analyzing-your-projects.html>`__" in the CodeQL for VS Code help.
.. pull-quote::
@@ -61,7 +61,7 @@ Query metadata is used to identify your custom queries when they are added to th
Import statements
=================
Each query generally contains one or more ``import`` statements, which define the `libraries <https://help.semmle.com/QL/ql-handbook/modules.html#library-modules>`__ or `modules <https://help.semmle.com/QL/ql-handbook/modules.html>`__ to import into the query. Libraries and modules provide a way of grouping together related `types <https://help.semmle.com/QL/ql-handbook/types.html>`__, `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__, and other modules. The contents of each library or module that you import can then be accessed by the query.
Each query generally contains one or more ``import`` statements, which define the `libraries <https://help.semmle.com/QL/ql-language-reference/modules.html#library-modules>`__ or `modules <https://help.semmle.com/QL/ql-language-reference/modules.html>`__ to import into the query. Libraries and modules provide a way of grouping together related `types <https://help.semmle.com/QL/ql-language-reference/types.html>`__, `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__, and other modules. The contents of each library or module that you import can then be accessed by the query.
Our `open source repository on GitHub <https://github.com/github/codeql>`__ contains the standard CodeQL libraries for each supported language.
When writing your own alert queries, you would typically import the standard library for the language of the project that you are querying, using ``import`` followed by a language:
@@ -73,25 +73,25 @@ When writing your own alert queries, you would typically import the standard lib
- JavaScript/TypeScript: ``javascript``
- Python: ``python``
There are also libraries containing commonly used predicates, types, and other modules associated with different analyses, including data flow, control flow, and taint-tracking. In order to calculate path graphs, path queries require you to import a data flow library into the query file. For more information, see ":doc:`Creating path queries <path-queries>`."
There are also libraries containing commonly used predicates, types, and other modules associated with different analyses, including data flow, control flow, and taint-tracking. In order to calculate path graphs, path queries require you to import a data flow library into the query file. For more information, see ":doc:`Creating path queries <creating-path-queries>`."
You can explore the contents of all the standard libraries in the `CodeQL library reference documentation <https://help.semmle.com/QL/ql-libraries.html>`__ or in the `GitHub repository <https://github.com/github/codeql>`__.
Optional CodeQL classes and predicates
--------------------------------------
You can customize your analysis by defining your own predicates and classes in the query. For further information, see `Defining a predicate <https://help.semmle.com/QL/ql-handbook/predicates.html#defining-a-predicate>`__ and `Defining a class <https://help.semmle.com/QL/ql-handbook/types.html#defining-a-class>`__.
You can customize your analysis by defining your own predicates and classes in the query. For further information, see `Defining a predicate <https://help.semmle.com/QL/ql-language-reference/predicates.html#defining-a-predicate>`__ and `Defining a class <https://help.semmle.com/QL/ql-language-reference/types.html#defining-a-class>`__.
From clause
===========
The ``from`` clause declares the variables that are used in the query. Each declaration must be of the form ``<type> <variable name>``.
For more information on the available `types <https://help.semmle.com/QL/ql-handbook/types.html>`__, and to learn how to define your own types using `classes <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__, see the `QL language reference <https://help.semmle.com/QL/ql-handbook/index.html>`__.
For more information on the available `types <https://help.semmle.com/QL/ql-language-reference/types.html>`__, and to learn how to define your own types using `classes <https://help.semmle.com/QL/ql-language-reference/types.html#classes>`__, see the `QL language reference <https://help.semmle.com/QL/ql-language-reference/index.html>`__.
Where clause
============
The ``where`` clause defines the logical conditions to apply to the variables declared in the ``from`` clause to generate your results. This clause uses `aggregations <https://help.semmle.com/QL/ql-handbook/expressions.html#aggregations>`__, `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__, and logical `formulas <https://help.semmle.com/QL/ql-handbook/formulas.html>`_ to limit the variables of interest to a smaller set, which meet the defined conditions.
The ``where`` clause defines the logical conditions to apply to the variables declared in the ``from`` clause to generate your results. This clause uses `aggregations <https://help.semmle.com/QL/ql-language-reference/expressions.html#aggregations>`__, `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__, and logical `formulas <https://help.semmle.com/QL/ql-language-reference/formulas.html>`_ to limit the variables of interest to a smaller set, which meet the defined conditions.
The CodeQL libraries group commonly used predicates for specific languages and frameworks. You can also define your own predicates in the body of the query file or in your own custom modules, as described above.
Select clause
@@ -106,9 +106,9 @@ Select clauses for alert queries (``@kind problem``) consist of two 'columns', w
- ``element``: a code element that is identified by the query, which defines where the alert is displayed.
- ``string``: a message, which can also include links and placeholders, explaining why the alert was generated.
You can modify the alert message defined in the final column of the ``select`` statement to give more detail about the alert or path found by the query using links and placeholders. For more information, see ":doc:`Defining the results of a query <select-statement>`."
You can modify the alert message defined in the final column of the ``select`` statement to give more detail about the alert or path found by the query using links and placeholders. For more information, see ":doc:`Defining the results of a query <defining-the-results-of-a-query>`."
Select clauses for path queries (``@kind path-problem``) are crafted to display both an alert and the source and sink of an associated path graph. For more information, see ":doc:`Creating path queries <path-queries>`."
Select clauses for path queries (``@kind path-problem``) are crafted to display both an alert and the source and sink of an associated path graph. For more information, see ":doc:`Creating path queries <creating-path-queries>`."
Viewing the standard CodeQL queries
***********************************
@@ -123,12 +123,12 @@ Contributing queries
Contributions to the standard queries and libraries are very welcome. For more information, see our `contributing guidelines <https://github.com/github/codeql/blob/main/CONTRIBUTING.md>`__.
If you are contributing a query to the open source GitHub repository, writing a custom query for LGTM, or using a custom query in an analysis with the CodeQL CLI, then you need to include extra metadata in your query to ensure that the query results are interpreted and displayed correctly. See the following topics for more information on query metadata:
- ":doc:`Metadata for CodeQL queries <query-metadata>`"
- ":doc:`Metadata for CodeQL queries <metadata-for-codeql-queries>`"
- `Query metadata style guide on GitHub <https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md>`__
Query contributions to the open source GitHub repository may also have an accompanying query help file to provide information about their purpose for other users. For more information on writing query help, see the `Query help style guide on GitHub <https://github.com/github/codeql/blob/main/docs/query-help-style-guide.md>`__ and the ":doc:`Query help files <query-help>`."
Query contributions to the open source GitHub repository may also have an accompanying query help file to provide information about their purpose for other users. For more information on writing query help, see the `Query help style guide on GitHub <https://github.com/github/codeql/blob/main/docs/query-help-style-guide.md>`__ and the ":doc:`Query help files <query-help-files>`."
Query help files
****************
When you write a custom query, we also recommend that you write a query help file to explain the purpose of the query to other users. For more information, see the `Query help style guide <https://github.com/github/codeql/blob/main/docs/query-help-style-guide.md>`__ on GitHub, and the ":doc:`Query help files <query-help>`."
When you write a custom query, we also recommend that you write a query help file to explain the purpose of the query to other users. For more information, see the `Query help style guide <https://github.com/github/codeql/blob/main/docs/query-help-style-guide.md>`__ on GitHub, and the ":doc:`Query help files <query-help-files>`."

25
docs/language/learn-ql/writing-queries/codeql-queries.rst Normal file
View File

@@ -0,0 +1,25 @@
CodeQL queries
##############
CodeQL queries are used in code scanning analyses to find problems in source code, including potential security vulnerabilities.
.. toctree::
:hidden:
about-codeql-queries
metadata-for-codeql-queries
query-help-files
defining-the-results-of-a-query
../providing-locations-in-codeql-queries
../about-data-flow-analysis
creating-path-queries
troubleshooting-query-performance
- :doc:`About CodeQL queries <about-codeql-queries>`: CodeQL queries are used to analyze code for issues related to security, correctness, maintainability, and readability.
- :doc:`Metadata for CodeQL queries <metadata-for-codeql-queries>`: Metadata tells users important information about CodeQL queries. You must include the correct query metadata in a query to be able to view query results in source code.
- :doc:`Query help files <query-help-files>`: Query help files tell users the purpose of a query, and recommend how to solve the potential problem the query finds.
- :doc:`Defining the results of a query <defining-the-results-of-a-query>`: You can control how analysis results are displayed in source code by modifying a query's ``select`` statement.
- :doc:`Providing locations in CodeQL queries <../providing-locations-in-codeql-queries>`: CodeQL includes mechanisms for extracting the location of elements in a codebase. Use these mechanisms when writing custom CodeQL queries and libraries to help display information to users.
- :doc:`About data flow analysis <../about-data-flow-analysis>`: Data flow analysis is used to compute the possible values that a variable can hold at various points in a program, determining how those values propagate through the program and where they are used.
- :doc:`Creating path queries <creating-path-queries>`: You can create path queries to visualize the flow of information through a codebase.
- :doc:`Troubleshooting query performance <troubleshooting-query-performance>`: Improve the performance of your CodeQL queries by following a few simple guidelines.

34
docs/language/learn-ql/writing-queries/path-queries.rst → docs/language/learn-ql/writing-queries/creating-path-queries.rst
View File

@@ -16,17 +16,17 @@ This topic provides information on how to structure a path query file so you can
Note
The alerts generated by path queries are displayed by default in `LGTM <https://lgtm.com>`__ and included in the results generated using the `CodeQL CLI <https://help.semmle.com/codeql/codeql-cli.html>`__. You can also view the path explanations generated by your path query `directly in LGTM <https://lgtm.com/help/lgtm/exploring-data-flow-paths>`__ or in the CodeQL `extension for VS Code <https://help.semmle.com/codeql/codeql-for-vscode.html>`__.
The alerts generated by path queries are displayed by default in `LGTM <https://lgtm.com>`__ and included in the results generated using the `CodeQL CLI <https://help.semmle.com/codeql/codeql-cli.html>`__. You can also view the path explanations generated by your path query `directly in LGTM <https://lgtm.com/help/lgtm/exploring-data-flow-paths>`__ or in the CodeQL `extension for VS Code <https://help.semmle.com/codeql/codeql-for-visual-studio-code.html>`__.
To learn more about modeling data flow with CodeQL, see ":doc:`About data flow analysis <../intro-to-data-flow>`."
To learn more about modeling data flow with CodeQL, see ":doc:`About data flow analysis <../about-data-flow-analysis>`."
For more language-specific information on analyzing data flow, see:
- ":doc:`Analyzing data flow in C/C++ <../cpp/dataflow>`"
- ":doc:`Analyzing data flow in C# <../csharp/dataflow>`"
- ":doc:`Analyzing data flow in Java <../java/dataflow>`"
- ":doc:`Analyzing data flow in JavaScript/TypeScript <../javascript/dataflow>`"
- ":doc:`Analyzing data flow and tracking tainted data in Python <../python/taint-tracking>`"
- ":doc:`Analyzing data flow in C/C++ <../cpp/analyzing-data-flow-in-cpp>`"
- ":doc:`Analyzing data flow in C# <../csharp/analyzing-data-flow-in-csharp>`"
- ":doc:`Analyzing data flow in Java <../java/analyzing-data-flow-in-java>`"
- ":doc:`Analyzing data flow in JavaScript/TypeScript <../javascript/analyzing-data-flow-in-javascript>`"
- ":doc:`Analyzing data flow and tracking tainted data in Python <../python/analyzing-data-flow-and-tracking-tainted-data-in-python>`"
Path query examples
@@ -56,7 +56,7 @@ For C/C++, C#, Java, and JavaScript you should use the following template::
* ...
*/
import <language>
import <ql-language-specification>
import DataFlow::PathGraph
...
@@ -98,13 +98,13 @@ Path query metadata
*******************
Path query metadata must contain the property ``@kind path-problem``–this ensures that query results are interpreted and displayed correctly.
The other metadata requirements depend on how you intend to run the query. For more information, see ":doc:`Metadata for CodeQL queries <query-metadata>`."
The other metadata requirements depend on how you intend to run the query. For more information, see ":doc:`Metadata for CodeQL queries <metadata-for-codeql-queries>`."
Generating path explanations
****************************
In order to generate path explanations, your query needs to compute a `path graph <https://en.wikipedia.org/wiki/Path_graph>`__.
To do this you need to define a `query predicate <https://help.semmle.com/QL/ql-handbook/queries.html#query-predicates>`__ called ``edges`` in your query.
To do this you need to define a `query predicate <https://help.semmle.com/QL/ql-language-reference/queries.html#query-predicates>`__ called ``edges`` in your query.
This predicate defines the edge relations of the graph you are computing, and it is used to compute the paths related to each result that your query generates.
You can import a predefined ``edges`` predicate from a path graph module in one of the standard data flow libraries. In addition to the path graph module, the data flow libraries contain the other ``classes``, ``predicates``, and ``modules`` that are commonly used in data flow analysis. The import statement to use depends on the language that you are analyzing.
@@ -149,9 +149,9 @@ The configuration class is accessed by importing the data flow library. This cla
- ``isSource()`` defines where data may flow from.
- ``isSink()`` defines where data may flow to.
For more information on using the configuration class in your analysis see the sections on global data flow in ":doc:`Analyzing data flow in C/C++ <../cpp/dataflow>`" and ":doc:`Analyzing data flow in C# <../csharp/dataflow>`."
For more information on using the configuration class in your analysis see the sections on global data flow in ":doc:`Analyzing data flow in C/C++ <../cpp/analyzing-data-flow-in-cpp>`" and ":doc:`Analyzing data flow in C# <../csharp/analyzing-data-flow-in-csharp>`."
You can also create a configuration for different frameworks and environments by extending the ``Configuration`` class. For more information, see "`Types <https://help.semmle.com/QL/ql-handbook/types.html#defining-a-class>`__" in the QL language reference.
You can also create a configuration for different frameworks and environments by extending the ``Configuration`` class. For more information, see "`Types <https://help.semmle.com/QL/ql-language-reference/types.html#defining-a-class>`__" in the QL language reference.
If you are querying Python code (and you have used ``import semmle.python.security.Paths`` in your query) you should declare ``TaintedPathSource source, TaintedPathSink sink`` in your ``from`` statement. You do not need to declare a ``Configuration`` class as the definitions of the ``TaintedPathSource`` and ``TaintedPathSink`` contain all of the type information that is required::
@@ -163,7 +163,7 @@ Defining flow conditions
************************
The ``where`` clause defines the logical conditions to apply to the variables declared in the ``from`` clause to generate your results.
This clause can use `aggregations <https://help.semmle.com/QL/ql-handbook/expressions.html#aggregations>`__, `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__, and logical `formulas <https://help.semmle.com/QL/ql-handbook/formulas.html>`_ to limit the variables of interest to a smaller set which meet the defined conditions.
This clause can use `aggregations <https://help.semmle.com/QL/ql-language-reference/expressions.html#aggregations>`__, `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__, and logical `formulas <https://help.semmle.com/QL/ql-language-reference/formulas.html>`_ to limit the variables of interest to a smaller set which meet the defined conditions.
When writing a path queries, you would typically include a predicate that holds only if data flows from the ``source`` to the ``sink``.
@@ -182,16 +182,16 @@ Select clauses for path queries consist of four 'columns', with the following st
select element, source, sink, string
The ``element`` and ``string`` columns represent the location of the alert and the alert message respectively, as explained in ":doc:`About CodeQL queries <introduction-to-queries>`." The second and third columns, ``source`` and ``sink``, are nodes on the path graph selected by the query.
Each result generated by your query is displayed at a single location in the same way as an alert query. Additionally, each result also has an associated path, which can be viewed in LGTM or in the `CodeQL extension for VS Code <https://help.semmle.com/codeql/codeql-for-vscode.html>`__.
The ``element`` and ``string`` columns represent the location of the alert and the alert message respectively, as explained in ":doc:`About CodeQL queries <about-codeql-queries>`." The second and third columns, ``source`` and ``sink``, are nodes on the path graph selected by the query.
Each result generated by your query is displayed at a single location in the same way as an alert query. Additionally, each result also has an associated path, which can be viewed in LGTM or in the `CodeQL extension for VS Code <https://help.semmle.com/codeql/codeql-for-visual-studio-code.html>`__.
The ``element`` that you select in the first column depends on the purpose of the query and the type of issue that it is designed to find. This is particularly important for security issues. For example, if you believe the ``source`` value to be globally invalid or malicious it may be best to display the alert at the ``source``. In contrast, you should consider displaying the alert at the ``sink`` if you believe it is the element that requires sanitization.
The alert message defined in the final column in the ``select`` statement can be developed to give more detail about the alert or path found by the query using links and placeholders. For more information, see ":doc:`Defining the results of a query <select-statement>`."
The alert message defined in the final column in the ``select`` statement can be developed to give more detail about the alert or path found by the query using links and placeholders. For more information, see ":doc:`Defining the results of a query <defining-the-results-of-a-query>`."
Further reading
***************
- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-paths.html>`__"
- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-data-flow-with-path-queries.html>`__"
- `CodeQL repository <https://github.com/github/codeql>`__

6
docs/language/learn-ql/writing-queries/select-statement.rst → docs/language/learn-ql/writing-queries/defining-the-results-of-a-query.rst
View File

@@ -7,7 +7,7 @@ About query results
-------------------
The information contained in the results of a query is controlled by the ``select`` statement. Part of the process of developing a useful query is to make the results clear and easy for other users to understand.
When you write your own queries in the query console or in the CodeQL `extension for VS Code <https://help.semmle.com/codeql/codeql-for-vscode.html>`__ there are no constraints on what can be selected.
When you write your own queries in the query console or in the CodeQL `extension for VS Code <https://help.semmle.com/codeql/codeql-for-visual-studio-code.html>`__ there are no constraints on what can be selected.
However, if you want to use a query to create alerts in LGTM or generate valid analysis results using the `CodeQL CLI <https://help.semmle.com/codeql/codeql-cli.html>`__, you'll need to make the ``select`` statement report results in the required format.
You must also ensure that the query has the appropriate metadata properties defined.
This topic explains how to write your select statement to generate helpful analysis results.
@@ -15,7 +15,7 @@ This topic explains how to write your select statement to generate helpful analy
Overview
--------
Alert queries must have the property ``@kind problem`` defined in their metadata. For more information, see ":doc:`Metadata for CodeQL queries <query-metadata>`."
Alert queries must have the property ``@kind problem`` defined in their metadata. For more information, see ":doc:`Metadata for CodeQL queries <metadata-for-codeql-queries>`."
In their most basic form, the ``select`` statement must select two 'columns':
- **Element**—a code element that's identified by the query. This defines the location of the alert.
@@ -27,7 +27,7 @@ If you look at some of the LGTM queries, you'll see that they can select extra e
Note
An in-depth discussion of ``select`` statements for path queries is not included in this topic. However, you can develop the string column of the ``select`` statement in the same way as for alert queries. For more specific information about path queries, see ":doc:`Creating path queries <path-queries>`."
An in-depth discussion of ``select`` statements for path queries is not included in this topic. However, you can develop the string column of the ``select`` statement in the same way as for alert queries. For more specific information about path queries, see ":doc:`Creating path queries <creating-path-queries>`."
Developing a select statement
-----------------------------

58
docs/language/learn-ql/writing-queries/query-metadata.rst → docs/language/learn-ql/writing-queries/metadata-for-codeql-queries.rst
View File

@@ -6,47 +6,47 @@ Metadata tells users important information about CodeQL queries. You must includ
About query metadata
--------------------
Any query that is run as part of an analysis includes a number of properties, known as query metadata. Metadata is included at the top of each query file as the content of a `QLDoc <https://help.semmle.com/QL/ql-spec/qldoc.html>`__ comment.
This metadata tells LGTM and the CodeQL `extension for VS Code <https://help.semmle.com/codeql/codeql-for-vscode.html>`__ how to handle the query and display its results correctly.
Any query that is run as part of an analysis includes a number of properties, known as query metadata. Metadata is included at the top of each query file as the content of a `QLDoc <https://help.semmle.com/QL/ql-spec/qldoc-comment-specification.html>`__ comment.
This metadata tells LGTM and the CodeQL `extension for VS Code <https://help.semmle.com/codeql/codeql-for-visual-studio-code.html>`__ how to handle the query and display its results correctly.
It also gives other users information about what the query results mean. For more information on query metadata, see the `query metadata style guide <https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md>`__ in our `open source repository <https://github.com/github/codeql>`__ on GitHub.
.. pull-quote::
Note
The exact metadata requirement depends on how you are going to run your query. For more information, see the section on query metadata in ":doc:`About CodeQL queries <introduction-to-queries>`."
The exact metadata requirement depends on how you are going to run your query. For more information, see the section on query metadata in ":doc:`About CodeQL queries <about-codeql-queries>`."
Metadata properties
-------------------
The following properties are supported by all query files:
+-----------------------+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Property | Value | Description |
+=======================+===========================+======================================================================================================================================================================================================================================================================================================================================================+
| ``@description`` | ``<text>`` | A sentence or short paragraph to describe the purpose of the query and *why* the result is useful or important. The description is written in plain text, and uses single quotes (``'``) to enclose code elements. |
+-----------------------+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``@id`` | ``<text>`` | A sequence of words composed of lowercase letters or digits, delimited by ``/`` or ``-``, identifying and classifying the query. Each query must have a **unique** ID. To ensure this, it may be helpful to use a fixed structure for each ID. For example, the standard LGTM queries have the following format: ``<language>/<brief-description>``. |
+-----------------------+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``@kind`` | | ``problem`` | Identifies the query is an alert (``@kind problem``) or a path (``@kind path-problem``). For more information on these query types, see ":doc:`About CodeQL queries <introduction-to-queries>`." |
| | | ``path-problem`` | |
+-----------------------+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``@name`` | ``<text>`` | A statement that defines the label of the query. The name is written in plain text, and uses single quotes (``'``) to enclose code elements. |
+-----------------------+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``@tags`` | | ``correctness`` | These tags group queries together in broad categories to make it easier to search for them and identify them. In addition to the common tags listed here, there are also a number of more specific categories. For more information, see the |
| | | ``maintainability`` | `Query metadata style guide <https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md>`__. |
| | | ``readability`` | |
| | | ``security`` | |
+-----------------------+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``@precision`` | | ``low``   | Indicates the percentage of query results that are true positives (as opposed to false positive results). This, along with the ``@problem.severity`` property, determines whether the results are displayed by default on LGTM. |
| | | ``medium``   | |
| | | ``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. |
| | | ``warning`` | |
| | | ``recommendation`` | |
+-----------------------+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+-----------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Property | Value | Description |
+=======================+===========================+=======================================================================================================================================================================================================================================================================================================================================================================+
| ``@description`` | ``<text>`` | A sentence or short paragraph to describe the purpose of the query and *why* the result is useful or important. The description is written in plain text, and uses single quotes (``'``) to enclose code elements. |
+-----------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``@id`` | ``<text>`` | A sequence of words composed of lowercase letters or digits, delimited by ``/`` or ``-``, identifying and classifying the query. Each query must have a **unique** ID. To ensure this, it may be helpful to use a fixed structure for each ID. For example, the standard LGTM queries have the following format: ``<ql-language-specification>/<brief-description>``. |
+-----------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``@kind`` | | ``problem`` | Identifies the query is an alert (``@kind problem``) or a path (``@kind path-problem``). For more information on these query types, see ":doc:`About CodeQL queries <about-codeql-queries>`." |
| | | ``path-problem`` | |
+-----------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``@name`` | ``<text>`` | A statement that defines the label of the query. The name is written in plain text, and uses single quotes (``'``) to enclose code elements. |
+-----------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``@tags`` | | ``correctness`` | These tags group queries together in broad categories to make it easier to search for them and identify them. In addition to the common tags listed here, there are also a number of more specific categories. For more information, see the |
| | | ``maintainability`` | `Query metadata style guide <https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md>`__. |
| | | ``readability`` | |
| | | ``security`` | |
+-----------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``@precision`` | | ``low`` | Indicates the percentage of query results that are true positives (as opposed to false positive results). This, along with the ``@problem.severity`` property, determines whether the results are displayed by default on LGTM. |
| | | ``medium`` | |
| | | ``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. |
| | | ``warning`` | |
| | | ``recommendation`` | |
+-----------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Additional properties for filter queries
----------------------------------------

0
docs/language/learn-ql/writing-queries/query-help.rst → docs/language/learn-ql/writing-queries/query-help-files.rst
View File

10
docs/language/learn-ql/writing-queries/debugging-queries.rst → docs/language/learn-ql/writing-queries/troubleshooting-query-performance.rst
View File

@@ -9,9 +9,9 @@ About query performance
This topic offers some simple tips on how to avoid common problems that can affect the performance of your queries.
Before reading the tips below, it is worth reiterating a few important points about CodeQL and the QL language:
- CodeQL `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ and `classes <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__ are evaluated to database `tables <https://en.wikipedia.org/wiki/Table_(database)>`__. Large predicates generate large tables with many rows, and are therefore expensive to compute.
- CodeQL `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ and `classes <https://help.semmle.com/QL/ql-language-reference/types.html#classes>`__ are evaluated to database `tables <https://en.wikipedia.org/wiki/Table_(database)>`__. Large predicates generate large tables with many rows, and are therefore expensive to compute.
- The QL language is implemented using standard database operations and `relational algebra <https://en.wikipedia.org/wiki/Relational_algebra>`__ (such as join, projection, and union). For more information about query languages and databases, see `About the QL language <https://help.semmle.com/QL/learn-ql/about-ql.html>`__.
- Queries are evaluated *bottom-up*, which means that a predicate is not evaluated until *all* of the predicates that it depends on are evaluated. For more information on query evaluation, see "`Evaluation of QL programs <https://help.semmle.com/QL/ql-handbook/evaluation.html>`__."
- Queries are evaluated *bottom-up*, which means that a predicate is not evaluated until *all* of the predicates that it depends on are evaluated. For more information on query evaluation, see "`Evaluation of QL programs <https://help.semmle.com/QL/ql-language-reference/evaluations-of-ql-programs.html>`__."
Performance tips
----------------
@@ -54,7 +54,7 @@ To avoid making this mistake, ``this`` should be restricted in the member predic
Use specific types
~~~~~~~~~~~~~~~~~~
"`Types <https://help.semmle.com/QL/ql-handbook/types.html>`__" provide an upper bound on the size of a relation.
"`Types <https://help.semmle.com/QL/ql-language-reference/types.html>`__" provide an upper bound on the size of a relation.
This helps the query optimizer be more effective, so it's generally good to use the most specific types possible. For example::
predicate foo(LoggingCall e)
@@ -90,7 +90,7 @@ Use ``getAQlClass()`` as a debugging tool, but don't include it in the final ver
Avoid complex recursion
~~~~~~~~~~~~~~~~~~~~~~~
"`Recursion <https://help.semmle.com/QL/ql-handbook/recursion.html>`__" is about self-referencing definitions.
"`Recursion <https://help.semmle.com/QL/ql-language-reference/recursion.html>`__" is about self-referencing definitions.
It can be extremely powerful as long as it is used appropriately.
On the whole, you should try to make recursive predicates as simple as possible.
That is, you should define a *base case* that allows the predicate to *bottom out*, along with a single *recursive call*::
@@ -103,7 +103,7 @@ That is, you should define a *base case* that allows the predicate to *bottom ou
.. pull-quote:: Note
The query optimizer has special data structures for dealing with `transitive closures <https://help.semmle.com/QL/ql-handbook/recursion.html#transitive-closures>`__.
The query optimizer has special data structures for dealing with `transitive closures <https://help.semmle.com/QL/ql-language-reference/recursion.html#transitive-closures>`__.
If possible, use a transitive closure over a simple recursive predicate, as it is likely to be computed faster.
Fold predicates

25
docs/language/learn-ql/writing-queries/writing-queries.rst
View File

@@ -1,25 +0,0 @@
CodeQL queries
##############
CodeQL queries are used in code scanning analyses to find problems in source code, including potential security vulnerabilities.
.. toctree::
:hidden:
introduction-to-queries
query-metadata
query-help
select-statement
../locations
../intro-to-data-flow
path-queries
debugging-queries
- :doc:`About CodeQL queries <introduction-to-queries>`: CodeQL queries are used to analyze code for issues related to security, correctness, maintainability, and readability.
- :doc:`Metadata for CodeQL queries <query-metadata>`: Metadata tells users important information about CodeQL queries. You must include the correct query metadata in a query to be able to view query results in source code.
- :doc:`Query help files <query-help>`: Query help files tell users the purpose of a query, and recommend how to solve the potential problem the query finds.
- :doc:`Defining the results of a query <select-statement>`: You can control how analysis results are displayed in source code by modifying a query's ``select`` statement.
- :doc:`Providing locations in CodeQL queries <../locations>`: CodeQL includes mechanisms for extracting the location of elements in a codebase. Use these mechanisms when writing custom CodeQL queries and libraries to help display information to users.
- :doc:`About data flow analysis <../intro-to-data-flow>`: Data flow analysis is used to compute the possible values that a variable can hold at various points in a program, determining how those values propagate through the program and where they are used.
- :doc:`Creating path queries <path-queries>`: You can create path queries to visualize the flow of information through a codebase.
- :doc:`Troubleshooting query performance <debugging-queries>`: Improve the performance of your CodeQL queries by following a few simple guidelines.

0
docs/language/ql-handbook/.gitignore → docs/language/ql-language-reference/.gitignore vendored
View File

2
docs/language/ql-handbook/about-the-ql-language.rst → docs/language/ql-language-reference/about-the-ql-language.rst
View File

@@ -42,7 +42,7 @@ When you write this process in QL, it closely resembles the above structure. Not
For more information about the important concepts and syntactic constructs of QL, see the individual reference topics such as ":doc:`Expressions <expressions>`" and ":doc:`Recursion <recursion>`."
The explanations and examples help you understand how the language works, and how to write more advanced QL code.
For formal specifications of the QL language and QLDoc comments, see the ":doc:`QL language specification <language>`" and ":doc:`QLDoc comment specification <qldoc>`."
For formal specifications of the QL language and QLDoc comments, see the ":doc:`QL language specification <ql-language-specification>`" and ":doc:`QLDoc comment specification <qldoc-comment-specification>`."
QL and object orientation
-------------------------

0
docs/language/ql-handbook/aliases.rst → docs/language/ql-language-reference/aliases.rst
View File

2
docs/language/ql-handbook/annotations.rst → docs/language/ql-language-reference/annotations.rst
View File

@@ -41,7 +41,7 @@ Overview of annotations
This section describes what the different annotations do, and when you can use them.
You can also find a summary table in the Annotations section of the
`QL language specification <https://help.semmle.com/QL/ql-spec/language.html#annotations>`_.
`QL language specification <ql-language-specification#annotations-in-java>`_.
.. index:: abstract
.. _abstract:

0
docs/language/ql-handbook/conf.py → docs/language/ql-language-reference/conf.py
View File

4
docs/language/ql-handbook/evaluation.rst → docs/language/ql-language-reference/evaluation-of-ql-programs.rst
View File

@@ -21,7 +21,7 @@ A QL program is evaluated from the bottom up, so a predicate is usually only eva
all the predicates it depends on are evaluated.
The database includes sets of ordered tuples for the `built-in predicates
<https://help.semmle.com/QL/ql-spec/language.html#built-ins>`_ and :ref:`external predicates <external>`.
<ql-language-specification#built-ins>`_ and :ref:`external predicates <external>`.
Each evaluation starts from these sets of tuples.
The remaining predicates and types in the program are organized into a number of layers, based
on the dependencies between them.
@@ -33,7 +33,7 @@ results of the program. The results are sorted according to any ordering directi
(``order by``) in the queries.
For more details about each step of the evaluation process, see the "`QL language specification
<https://help.semmle.com/QL/ql-spec/language.html#evaluation>`_."
<ql-language-specification#evaluations-of-ql-programs>`_."
Validity of programs
********************

4
docs/language/ql-handbook/expressions.rst → docs/language/ql-language-reference/expressions.rst
View File

@@ -55,7 +55,7 @@ You can express certain values directly in QL, such as numbers, booleans, and st
"hello"
"They said, \"Please escape quotation marks!\""
See `String literals <https://help.semmle.com/QL/ql-spec/language.html#string-literals-string>`_
See `String literals <ql-language-specification#string-literals-string>`_
in the QL language specification for more details.
Note: there is no "date literal" in QL. Instead, to specify a :ref:`date <date>`, you should
@@ -529,7 +529,7 @@ The following table lists some examples of different forms of ``any`` expression
+------------------------------------------+-------------------------------------------------+
.. note::
There is also a `built-in predicate <https://help.semmle.com/QL/ql-spec/language.html#non-member-built-ins>`_
There is also a `built-in predicate <ql-language-specification#non-member-built-ins>`_
``any()``. This is a predicate that always holds.
Unary operations

2
docs/language/ql-handbook/formulas.rst → docs/language/ql-language-reference/formulas.rst
View File

@@ -33,7 +33,7 @@ Order
To compare two expressions using one of these order operators, each expression must have a type
and those types must be :ref:`compatible <type-compatibility>` and
`orderable <https://help.semmle.com/QL/ql-spec/language.html#ordering>`_.
`orderable <ql-language-specification#ordering>`_.
+--------------------------+--------+
| Name | Symbol |

6
docs/language/ql-handbook/index.rst → docs/language/ql-language-reference/index.rst
View File

@@ -19,6 +19,6 @@ Learn all about QL, the powerful query language that underlies the code scanning
recursion
lexical-syntax
name-resolution
evaluation
language
qldoc
evaluation-of-ql-programs
ql-language-specification
qldoc-comment-specification

6
docs/language/ql-handbook/lexical-syntax.rst → docs/language/ql-language-reference/lexical-syntax.rst
View File

@@ -6,7 +6,7 @@ Lexical syntax
The QL syntax includes different kinds of keywords, identifiers, and comments.
For an overview of the lexical syntax, see "`Lexical syntax
<https://help.semmle.com/QL/ql-spec/language.html#lexical-syntax>`_" in the QL language specification.
<ql-language-specification#lexical-syntax>`_" in the QL language specification.
.. index:: comment, QLDoc
.. _comments:
@@ -15,11 +15,11 @@ Comments
********
All standard one-line and multiline comments, as described in the "`QL language specification
<https://help.semmle.com/QL/ql-spec/language.html#comments>`_," are ignored by the QL
<ql-language-specification#comments>`_," are ignored by the QL
compiler and are only visible in the source code.
You can also write another kind of comment, namely **QLDoc comments**. These comments describe
QL entities and are displayed as pop-up information in QL editors. For information about QLDoc
comments, see the "`QLDoc comment specification <https://help.semmle.com/QL/ql-spec/qldoc.html>`_."
comments, see the "`QLDoc comment specification <https://help.semmle.com/QL/ql-spec/qldoc-comment-specification.html>`_."
The following example uses these three different kinds of comments::

4
docs/language/ql-handbook/modules.rst → docs/language/ql-language-reference/modules.rst
View File

@@ -25,7 +25,7 @@ a class ``OneTwoThree``::
}
}
The name of a module can be any `identifier <https://help.semmle.com/QL/ql-spec/language.html#identifiers>`_
The name of a module can be any `identifier <ql-language-specification#identifiers>`_
that starts with an uppercase or lowercase letter.
``.ql`` or ``.qll`` files also implicitly define modules.
@@ -178,5 +178,5 @@ for example ``import javascript as js``.
The ``<module_expression>`` itself can be a module name, a selection, or a qualified
reference. For more information, see ":ref:`name-resolution`."
For information about how import statements are looked up, see "`Module resolution <https://help.semmle.com/QL/ql-spec/language.html#module-resolution>`__"
For information about how import statements are looked up, see "`Module resolution <ql-language-specification#module-resolution>`__"
in the QL language specification.

8
docs/language/ql-handbook/name-resolution.rst → docs/language/ql-language-reference/name-resolution.rst
View File

@@ -74,7 +74,7 @@ statement as follows:
#. If the compiler can't find the library file using the above two checks, it looks up ``examples/security/MyLibrary.qll``
relative to each library path entry.
The library path is usually specified using the ``libraryPathDependencies`` of the ``qlpack.yml`` file, though it may also depend on the tools you use to run your query, and whether you have specified any extra settings.
For more information, see "`Library path <https://help.semmle.com/QL/ql-spec/language.html#library-path>`__" in the QL language specification.
For more information, see "`Library path <ql-language-specification#library-path>`__" in the QL language specification.
If the compiler cannot resolve an import statement, then it gives a compilation error.
@@ -146,7 +146,7 @@ Namespaces
**********
When writing QL, it's useful to understand how namespaces (also known as
`environments <https://help.semmle.com/QL/ql-spec/language.html#name-resolution>`_) work.
`environments <ql-language-specification#name-resolution>`_) work.
As in many other programming languages, a namespace is a mapping from **keys** to
**entities**. A key is a kind of identifier, for example a name, and a QL entity is
@@ -173,7 +173,7 @@ In particular:
- The **global module namespace** is empty.
- The **global type namespace** has entries for the :ref:`primitive types <primitive-types>` ``int``, ``float``,
``string``, ``boolean``, and ``date``, as well as any :ref:`database types <database-types>` defined in the database schema.
- The **global predicate namespace** includes all the `built-in predicates <https://help.semmle.com/QL/ql-spec/language.html#built-ins>`_,
- The **global predicate namespace** includes all the `built-in predicates <ql-language-specification#built-ins>`_,
as well as any :ref:`database predicates <database-predicates>`.
In practice, this means that you can use the built-in types and predicates directly in a QL module (without
@@ -289,7 +289,7 @@ The type namespace of ``S`` has entries for:
The predicate namespace of ``Villagers`` has entries for:
- The predicate ``isBald``, with arity 1.
- Any predicates (and their arities) exported by ``tutorial``.
- The `built-in predicates <https://help.semmle.com/QL/ql-spec/language.html#built-ins>`_.
- The `built-in predicates <ql-language-specification#built-ins>`_.
The predicate namespace of ``S`` has entries for:
- All the above predicates.

4
docs/language/ql-handbook/predicates.rst → docs/language/ql-language-reference/predicates.rst
View File

@@ -33,7 +33,7 @@ The `arity <https://en.wikipedia.org/wiki/Arity>`_ of these predicates is one an
In general, all tuples in a predicate have the same number of elements. The **arity** of
a predicate is that number of elements, not including a possible ``result`` variable. For more information, see ":ref:`predicates-with-result`."
There are a number of `built-in predicates <https://help.semmle.com/QL/ql-spec/language.html#built-ins>`_
There are a number of `built-in predicates <ql-language-specification#built-ins>`_
in QL. You can use these in any queries without needing to :ref:`import <importing-modules>`
any additional modules. In addition to these built-in predicates, you can also define your
own:
@@ -45,7 +45,7 @@ When defining a predicate, you should specify:
#. The keyword ``predicate`` (for a :ref:`predicate without result <predicates-without-result>`),
or the type of the result (for a :ref:`predicate with result <predicates-with-result>`).
#. The name of the predicate. This is an `identifier <https://help.semmle.com/QL/ql-spec/language.html#identifiers>`_
#. The name of the predicate. This is an `identifier <ql-language-specification#identifiers>`_
starting with a lowercase letter.
#. The arguments to the predicate, if any, separated by commas. For each argument, specify the
argument type and an identifier for the argument variable.

0
docs/language/ql-handbook/language.rst → docs/language/ql-language-reference/ql-language-specification.rst
View File

0
docs/language/ql-handbook/qldoc.rst → docs/language/ql-language-reference/qldoc-comment-specification.rst
View File

0
docs/language/ql-handbook/queries.rst → docs/language/ql-language-reference/queries.rst
View File

0
docs/language/ql-handbook/recursion.rst → docs/language/ql-language-reference/recursion.rst
View File

6
docs/language/ql-handbook/types.rst → docs/language/ql-language-reference/types.rst
View File

@@ -48,7 +48,7 @@ independent of the database that you are querying.
QL has a range of built-in operations defined on primitive types. These are available by using dispatch on expressions of the appropriate type. For example, ``1.toString()`` is the string representation of the integer constant ``1``. For a full list of built-in operations available in QL, see the
section on `built-ins <https://help.semmle.com/QL/ql-spec/language.html#built-ins>`__ in the QL language specification.
section on `built-ins <ql-language-specification#built-ins>`__ in the QL language specification.
.. index:: class
.. _classes:
@@ -74,7 +74,7 @@ Defining a class
To define a class, you write:
#. The keyword ``class``.
#. The name of the class. This is an `identifier <https://help.semmle.com/QL/ql-spec/language.html#identifiers>`_
#. The name of the class. This is an `identifier <ql-language-specification#identifiers>`_
starting with an uppercase letter.
#. The types to extend.
#. The :ref:`body of the class <class-bodies>`, enclosed in braces.
@@ -419,7 +419,7 @@ The branch definitions have the following form::
<BranchName>(<arguments>) { <body> }
- The type name and the branch names must be `identifiers <https://help.semmle.com/QL/ql-spec/language.html#identifiers>`_
- The type name and the branch names must be `identifiers <ql-language-specification#identifiers>`_
starting with an uppercase letter. Conventionally, they start with ``T``.
- The different branches of an algebraic datatype are separated by ``or``.
- The arguments to a branch, if any, are :ref:`variable declarations <variable-declarations>`

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

@@ -20,7 +20,7 @@ Declaring a variable
********************
All variable declarations consist of a :ref:`type <types>` and a name for the variable.
The name can be any `identifier <https://help.semmle.com/QL/ql-spec/language.html#identifiers>`_
The name can be any `identifier <ql-language-specification#identifiers>`_
that starts with an uppercase or lowercase letter.
For example, ``int i``, ``SsaDefinitionNode node``, and ``LocalScopeVariable lsv`` declare

2
docs/language/reusables/codeql-ref-tools-further-reading.rst
View File

@@ -1,2 +1,2 @@
- "`QL language reference <https://help.semmle.com/QL/ql-handbook>`__"
- "`QL language reference <https://help.semmle.com/QL/ql-language-reference>`__"
- "`CodeQL tools <https://help.semmle.com/codeql/codeql-tools.html>`__"