mirror of
https://github.com/github/codeql.git
synced 2026-04-30 03:05:15 +02:00
docs: update ql terminology
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
Example: Bad overflow guard
|
||||
===========================
|
||||
|
||||
QL for C/C++
|
||||
CodeQL for C/C++
|
||||
|
||||
.. container:: semmle-logo
|
||||
|
||||
@@ -127,13 +127,13 @@ This happens even though the overflow check passed!
|
||||
|
||||
.. rst-class:: background2
|
||||
|
||||
Developing a QL query
|
||||
=====================
|
||||
Developing a CodeQL query
|
||||
=========================
|
||||
|
||||
Finding bad overflow guards
|
||||
|
||||
QL query: bad overflow guards
|
||||
=============================
|
||||
CodeQL query: bad overflow guards
|
||||
==================================
|
||||
|
||||
Let’s look for overflow guards of the form ``v + b < v``, using the classes
|
||||
``AddExpr``, ``Variable`` and ``RelationalOperation`` from the ``cpp`` library.
|
||||
@@ -153,10 +153,10 @@ Let’s look for overflow guards of the form ``v + b < v``, using the classes
|
||||
- a ``RelationalOperation``: the overflow comparison check.
|
||||
- a ``Variable``: used as an argument to both the addition and comparison.
|
||||
|
||||
- The ``where`` part of the query ties these three QL variables together using `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ defined in the `standard QL for C/C++ library <https://help.semmle.com/qldoc/cpp/>`__.
|
||||
- The ``where`` part of the query ties these three variables together using `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ defined in the `standard CodeQL for C/C++ library <https://help.semmle.com/qldoc/cpp/>`__.
|
||||
|
||||
QL query: bad overflow guards
|
||||
=============================
|
||||
CodeQL query: bad overflow guards
|
||||
=================================
|
||||
|
||||
We want to ensure the operands being added have size less than 4 bytes.
|
||||
|
||||
@@ -180,8 +180,8 @@ We can get the size (in bytes) of a type using the ``getSize()`` method.
|
||||
- We therefore write a helper predicate for small expressions.
|
||||
- This predicate effectively represents the set of all expressions in the database where the size of the type of the expression is less than 4 bytes, that is, less than 32-bits.
|
||||
|
||||
QL query: bad overflow guards
|
||||
=============================
|
||||
CodeQL query: bad overflow guards
|
||||
==================================
|
||||
|
||||
We can ensure the operands being added have size less than 4 bytes, using our new predicate.
|
||||
|
||||
@@ -216,8 +216,8 @@ Now our query becomes:
|
||||
- The “range” part, ``op = a.getAnOperand()``, restricts ``op`` to being one of the two operands to the addition.
|
||||
- The “condition” part, ``isSmall(op)``, says that the ``forall`` holds only if the condition (that the ``op`` is small) holds for everything in the range–that is, both the arguments to the addition.
|
||||
|
||||
QL query: bad overflow guards
|
||||
=============================
|
||||
CodeQL query: bad overflow guards
|
||||
=================================
|
||||
|
||||
Sometimes the result of the addition is cast to a small type of size less than 4 bytes, preventing automatic widening. We don’t want our query to flag these instances.
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
Analyzing control flow
|
||||
======================
|
||||
|
||||
QL for C/C++
|
||||
CodeQL for C/C++
|
||||
|
||||
.. container:: semmle-logo
|
||||
|
||||
@@ -226,7 +226,7 @@ A ``GuardCondition`` is a ``Boolean`` condition that controls one or more basic
|
||||
Further materials
|
||||
=================
|
||||
|
||||
- QL for C/C++: https://help.semmle.com/QL/learn-ql/ql/cpp/ql-for-cpp.html
|
||||
- CodeQL for C/C++: https://help.semmle.com/QL/learn-ql/ql/cpp/ql-for-cpp.html
|
||||
- API reference: https://help.semmle.com/qldoc/cpp
|
||||
|
||||
.. rst-class:: end-slide
|
||||
|
||||
@@ -86,9 +86,9 @@ Write a query that flags ``printf`` calls where the format argument is not a ``S
|
||||
|
||||
.. note::
|
||||
|
||||
This first query is about finding places where the format specifier is not a constant string. In QL for C/C++, constant strings are modeled as ``StringLiteral`` nodes, so we are looking for calls to format functions where the format specifier argument is not a string literal.
|
||||
This first query is about finding places where the format specifier is not a constant string. In CodeQL for C/C++, constant strings are modeled as ``StringLiteral`` nodes, so we are looking for calls to format functions where the format specifier argument is not a string literal.
|
||||
|
||||
The `C/C++ standard libraries <https://help.semmle.com/qldoc/cpp/>`__ include many different formatting functions that may be vulnerable to this particular attack–including ``printf``, ``snprintf``, and others. Furthermore, each of these different formatting functions may include the format string in a different position in the argument list. Instead of laboriously listing all these different variants, we can make use of the QL for C/C++ standard library class ``FormattingFunction``, which provides an interface that models common formatting functions in C/C++.
|
||||
The `C/C++ standard libraries <https://help.semmle.com/qldoc/cpp/>`__ include many different formatting functions that may be vulnerable to this particular attack–including ``printf``, ``snprintf``, and others. Furthermore, each of these different formatting functions may include the format string in a different position in the argument list. Instead of laboriously listing all these different variants, we can make use of the CodeQL for C/C++ standard library class ``FormattingFunction``, which provides an interface that models common formatting functions in C/C++.
|
||||
|
||||
Meh...
|
||||
======
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
Introduction to global data flow
|
||||
================================
|
||||
|
||||
QL for C/C++
|
||||
CodeQL for C/C++
|
||||
|
||||
.. container:: semmle-logo
|
||||
|
||||
@@ -77,7 +77,7 @@ The library class ``SecurityOptions`` provides a (configurable) model of what co
|
||||
|
||||
.. note::
|
||||
|
||||
We first define what it means to be a *source* of tainted data for this particular problem. In this case, what we care about is whether the format string can be provided by an external user to our application or service. As there are many such ways external data could be introduced into the system, the standard QL libraries for C/C++ include an extensible API for modeling user input. In this case, we will simply use the predefined set of *user inputs*, which includes arguments provided to command line applications.
|
||||
We first define what it means to be a *source* of tainted data for this particular problem. In this case, what we care about is whether the format string can be provided by an external user to our application or service. As there are many such ways external data could be introduced into the system, the standard CodeQL libraries for C/C++ include an extensible API for modeling user input. In this case, we will simply use the predefined set of *user inputs*, which includes arguments provided to command line applications.
|
||||
|
||||
|
||||
Defining sinks (exercise)
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
Introduction to variant analysis
|
||||
================================
|
||||
|
||||
QL for C/C++
|
||||
CodeQL for C/C++
|
||||
|
||||
.. container:: semmle-logo
|
||||
|
||||
@@ -56,14 +56,14 @@ Oops
|
||||
|
||||
.. note::
|
||||
|
||||
Here’s a simple (artificial) bug, which we’ll develop a QL query to catch.
|
||||
Here’s a simple (artificial) bug, which we’ll develop a query to catch.
|
||||
|
||||
This function writes a value to a given location in an array, first trying to do a bounds check to validate that the location is within bounds. However, the return statement has been commented out, leaving a redundant if statement and no bounds checking.
|
||||
|
||||
This case can act as our “patient zero” in the variant analysis game.
|
||||
|
||||
A simple QL query
|
||||
=================
|
||||
A simple CodeQL query
|
||||
=====================
|
||||
|
||||
.. literalinclude:: ../query-examples/cpp/empty-if-cpp.ql
|
||||
:language: ql
|
||||
@@ -72,9 +72,9 @@ A simple QL query
|
||||
|
||||
We are going to write a simple query which finds “if statements” with empty “then” blocks, so we can highlight the results like those on the previous slide. The query can be run in the `query console on LGTM <https://lgtm.com/query>`__, or in your `IDE <https://lgtm.com/help/lgtm/running-queries-ide>`__.
|
||||
|
||||
A `QL query <https://help.semmle.com/QL/ql-handbook/queries.html>`__ consists of a “select” clause that indicates what results should be returned. Typically it will also provide a “from” clause to declare some variables, and a “where” clause to state conditions over those variables. For more information on the structure of query files (including links to useful topics in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__), see `Introduction to query files <https://help.semmle.com/QL/learn-ql/ql/writing-queries/introduction-to-queries.html>`__.
|
||||
A `query <https://help.semmle.com/QL/ql-handbook/queries.html>`__ consists of a “select” clause that indicates what results should be returned. Typically it will also provide a “from” clause to declare some variables, and a “where” clause to state conditions over those variables. For more information on the structure of query files (including links to useful topics in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__), see `Introduction to query files <https://help.semmle.com/QL/learn-ql/ql/writing-queries/introduction-to-queries.html>`__.
|
||||
|
||||
In our example here, the first line of the query imports the `C/C++ standard QL library <https://help.semmle.com/qldoc/cpp/>`__, which defines concepts like ``IfStmt`` and ``Block``.
|
||||
In our example here, the first line of the query imports the `CodeQL for C/C++ standard library <https://help.semmle.com/qldoc/cpp/>`__, which defines concepts like ``IfStmt`` and ``Block``.
|
||||
The query proper starts by declaring two variables–ifStmt and block. These variables represent sets of values in the database, according to the type of each of the variables. For example, ifStmt has the type IfStmt, which means it represents the set of all if statements in the program.
|
||||
|
||||
If we simply selected these two variables::
|
||||
@@ -97,8 +97,8 @@ A simple QL query
|
||||
|
||||
|
||||
|
||||
Structure of a QL query
|
||||
=======================
|
||||
Structure of a query
|
||||
====================
|
||||
|
||||
A **query file** has the extension ``.ql`` and contains a **query clause**, and optionally **predicates**, **classes**, and **modules**.
|
||||
|
||||
@@ -110,14 +110,14 @@ Each query library also implicitly defines a module.
|
||||
|
||||
.. note::
|
||||
|
||||
QL queries are always contained in query files with the file extension ``.ql``. `Quick queries <https://help.semmle.com/ql-for-eclipse/Content/WebHelp/quick-query.html>`__, run in `QL for Eclipse <https://help.semmle.com/ql-for-eclipse/Content/WebHelp/home-page.html>`__, are no exception: the quick query window maintains a temporary QL file in the background.
|
||||
Queries are always contained in query files with the file extension ``.ql``. `Quick queries <https://help.semmle.com/ql-for-eclipse/Content/WebHelp/quick-query.html>`__, run in `QL for Eclipse <https://help.semmle.com/ql-for-eclipse/Content/WebHelp/home-page.html>`__, are no exception: the quick query window maintains a temporary query file in the background.
|
||||
|
||||
Parts of queries can be lifted into `QL library files <https://help.semmle.com/QL/ql-handbook/modules.html#library-modules>`__ with the extension ``qll``. Definitions within such libraries can be brought into scope using ``import`` statements, and similarly QLL files can import each other’s definitions using “import” statements.
|
||||
Parts of queries can be lifted into `library files <https://help.semmle.com/QL/ql-handbook/modules.html#library-modules>`__ with the extension ``qll``. Definitions within such libraries can be brought into scope using ``import`` statements, and similarly QLL files can import each other’s definitions using “import” statements.
|
||||
|
||||
Logic can be encapsulated as user-defined `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ and `classes <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__, and organized into `modules <https://help.semmle.com/QL/ql-handbook/modules.html>`__. Each QLL file implicitly defines a module, but QL and QLL files can also contain explicit module definitions, as we will see later.
|
||||
|
||||
Predicates in QL
|
||||
================
|
||||
Predicates
|
||||
==========
|
||||
|
||||
A predicate allows you to pull out and name parts of a query.
|
||||
|
||||
@@ -135,14 +135,14 @@ A predicate allows you to pull out and name parts of a query.
|
||||
|
||||
.. note::
|
||||
|
||||
A QL predicate takes zero or more parameters, and its body is a condition on those parameters. The predicate may (or may not) hold. Predicates may also be recursive, simply by referring to themselves (directly or indirectly).
|
||||
A `predicate <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ takes zero or more parameters, and its body is a condition on those parameters. The predicate may (or may not) hold. Predicates may also be `recursive <https://help.semmle.com/QL/ql-handbook/predicates.html#recursive-predicates>`__, simply by referring to themselves (directly or indirectly).
|
||||
|
||||
You can imagine a predicate to be a self-contained from-where-select statement, that produces an intermediate relation, or table. In this case, the ``isEmpty`` predicate will be the set of all blocks which are empty.
|
||||
|
||||
Classes in QL
|
||||
=============
|
||||
Classes
|
||||
=======
|
||||
|
||||
A QL class allows you to name a set of values and define (member) predicates on them.
|
||||
A class allows you to name a set of values and define (member) predicates on them.
|
||||
|
||||
A class has at least one supertype and optionally a **characteristic predicate**; it contains the values that belong to *all* supertypes *and* satisfy the characteristic predicate, if provided.
|
||||
|
||||
@@ -162,8 +162,8 @@ Member predicates are inherited and can be overridden.
|
||||
|
||||
In the example, declaring a variable “EmptyBlock e” will allow it to range over only those blocks that have zero statements.
|
||||
|
||||
Classes in QL continued
|
||||
=======================
|
||||
Classes continued
|
||||
=================
|
||||
|
||||
.. container:: column-left
|
||||
|
||||
@@ -198,7 +198,7 @@ Iterative query refinement
|
||||
|
||||
.. note::
|
||||
|
||||
QL makes it very easy to experiment with analysis ideas. A common workflow is to start with a simple query (like our “redundant if-statement” example), examine a few results, refine the query based on any patterns that emerge and repeat.
|
||||
CodeQL makes it very easy to experiment with analysis ideas. A common workflow is to start with a simple query (like our “redundant if-statement” example), examine a few results, refine the query based on any patterns that emerge and repeat.
|
||||
|
||||
As an exercise, refine the redundant-if query based on the observation that if the if-statement has an “else” clause, then even if the body of the “then” clause is empty, it’s not actually redundant.
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
Program representation
|
||||
======================
|
||||
|
||||
QL for C/C++
|
||||
CodeQL for C/C++
|
||||
|
||||
.. container:: semmle-logo
|
||||
|
||||
@@ -25,8 +25,8 @@ Agenda
|
||||
|
||||
.. resume slides
|
||||
|
||||
AST QL classes
|
||||
==============
|
||||
AST classes
|
||||
===========
|
||||
|
||||
Important AST classes include:
|
||||
|
||||
@@ -66,9 +66,9 @@ Working with variables
|
||||
Working with functions
|
||||
======================
|
||||
|
||||
Functions are represented by the Function QL class. Each declaration or definition of a function is represented by a ``FunctionDeclarationEntry``.
|
||||
Functions are represented by the Function class. Each declaration or definition of a function is represented by a ``FunctionDeclarationEntry``.
|
||||
|
||||
Calls to functions are modeled by QL class Call and its subclasses:
|
||||
Calls to functions are modeled by class Call and its subclasses:
|
||||
|
||||
- ``Call.getTarget()`` gets the declared target of the call; undefined for calls through function pointers
|
||||
- ``Function.getACallToThisFunction()`` gets a call to this function
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
Exercise: ``snprintf`` overflow
|
||||
===============================
|
||||
|
||||
QL for C/C++
|
||||
CodeQL for C/C++
|
||||
|
||||
.. container:: semmle-logo
|
||||
|
||||
|
||||
Reference in New Issue
Block a user