docs: address first round of review comments on other slides and add intro to ql decks

Author: james

docs/language/ql-training-rst/_static-training/slides-semmle-2/static/theme/css/default.css

@@ -480,6 +480,7 @@ ul {
 ul li {
   margin-bottom: 0.5em;
   color: #2c2a8a;
+   line-height: 1.3em;
 }
 /* line 303, ../scss/default.scss */
 ul li ul {
@@ -494,9 +495,10 @@ ul li ul li:before {
 /* line 314, ../scss/default.scss */
 ul > li:before {
   content: '\00B7';
-  margin-left: -1em;
+  margin-left: -0.5em;
   position: absolute;
   font-weight: 600;
+  font-size: 2em;
 }
 /* line 321, ../scss/default.scss */
 ul ul {
@@ -1415,16 +1417,8 @@ slide {
   background-size: cover;
 }
 
-.agenda-slide h1 {
-  padding:0;
-}
 
-.background2 h1, .background2 p {
-  color: white;
-}
-
-
-/* Title slide styles */
+/* Custom slide styles */
 
 .semmle-logo sup {
   vertical-align: super;
@@ -1442,6 +1436,23 @@ slide {
   color: white;
   font-size: 1.2em;
 }
+
+.agenda-slide h1 {
+  padding:0;
+}
+
+.background2 h1, .background2 p {
+  color: white;
+}
+
+hgroup .pre {
+  color: #5c31ff;
+}
+
+.title-slide hgroup .pre {
+  color: white;
+}
+
 /* James column experiments */
 
 .column-left {

docs/language/ql-training-rst/conf.py

@@ -120,5 +120,7 @@ def setup(sphinx):
                       'nosidebar':True,
                       }
 
+# Exclude the slide snippets from the build
+exclude_patterns = ['slide-snippets']
 
 ##############################################################################

docs/language/ql-training-rst/cpp/bad-overflow-guard.rst

@@ -5,32 +5,22 @@ Example: Bad overflow guard
 
    Semmle :sup:`TM`
 
+.. Include information slides here
 
-Getting started and setting up
-==============================
+.. include:: ../slide-snippets/info.rst
 
-To try the examples in this presentation you should download:
+QL snapshot
+===========
 
-- `QL for Eclipse <https://help.semmle.com/ql-for-eclipse/Content/WebHelp/install-plugin-free.html>`__
-- Snapshot: `ChakraCore <https://downloads.lgtm.com/snapshots/cpp/microsoft/chakracore/ChakraCore-revision-2017-April-12--18-13-26.zip>`__
+For the examples in this presentation, we will be analyzing `ChakraCore <https://github.com/microsoft/ChakraCore>`__.
 
-More resources:
+We recommend you download `this historic snapshot <https://downloads.lgtm.com/snapshots/cpp/microsoft/chakracore/ChakraCore-revision-2017-April-12--18-13-26.zip>`__ to analyze in QL for Eclipse.
 
-- To learn more about the main features of QL, try looking at the `QL language handbook <https://help.semmle.com/QL/ql-handbook/>`__.
-- For further information about writing queries in QL, see `Writing QL queries <https://help.semmle.com/QL/learn-ql/ql/writing-queries/writing-queries.html>`__.
+Alternatively, you can query the project in `the query console <https://lgtm.com/query/project:2034240708/lang:cpp/>`__ on LGTM.com.
 
 .. note::
 
-  To run the queries featured in this training presentation, we recommend you download the free-to-use `QL for Eclipse plugin <https://help.semmle.com/ql-for-eclipse/Content/WebHelp/getting-started.html>`__.
-
-  This plugin allows you to locally access the latest features of QL, including the standard QL libraries and queries. It also provides standard IDE features such as syntax highlighting, jump-to-definition, and tab completion.
-
-  A good project to start analyzing is `ChakraCore <https://github.com/microsoft/ChakraCore>`__–a suitable snapshot to query is available by visiting the link on the slide.
-
-  Alternatively, you can query any project (including ChakraCore) in the  `query console on LGTM.com <https://lgtm.com/query/project:2034240708/lang:cpp/>`__. 
-
-  Note that results generated in the query console are likely to differ to those generated in the QL plugin. LGTM.com analyzes the most recent revisions of each project that has been added–the snapshot available to download above is for an historical version of the code base.
-
+   Note that results generated in the query console are likely to differ to those generated in the QL plugin as LGTM.com analyzes the most recent revisions of each project that has been added–the snapshot available to download above is based on an historical version of the code base.
 
 Checking for overflow in C
 ==========================

docs/language/ql-training-rst/cpp/control-flow-cpp.rst

@@ -4,31 +4,23 @@ Analyzing control flow for C/C++
 .. container:: semmle-logo
 
    Semmle :sup:`TM`
-   
-Getting started and setting up
-==============================
-
-To try the examples in this presentation you should download:
-
-- `QL for Eclipse <https://help.semmle.com/ql-for-eclipse/Content/WebHelp/install-plugin-free.html>`__
-- Snapshot: `ChakraCore <https://downloads.lgtm.com/snapshots/cpp/microsoft/chakracore/ChakraCore-revision-2017-April-12--18-13-26.zip>`__
 
-More resources:
+.. Include information slides here
 
-- To learn more about the main features of QL, try looking at the `QL language handbook <https://help.semmle.com/QL/ql-handbook/>`__.
-- For further information about writing queries in QL, see `Writing QL queries <https://help.semmle.com/QL/learn-ql/ql/writing-queries/writing-queries.html>`__.
+.. include:: ../slide-snippets/info.rst
 
-.. note::
+QL snapshot
+===========
 
-  To run the queries featured in this training presentation, we recommend you download the free-to-use `QL for Eclipse plugin <https://help.semmle.com/ql-for-eclipse/Content/WebHelp/getting-started.html>`__.
+For the examples in this presentation, we will be analyzing `ChakraCore <https://github.com/microsoft/ChakraCore>`__.
 
-  This plugin allows you to locally access the latest features of QL, including the standard QL libraries and queries. It also provides standard IDE features such as syntax highlighting, jump-to-definition, and tab completion.
+We recommend you download `this historic snapshot <https://downloads.lgtm.com/snapshots/cpp/microsoft/chakracore/ChakraCore-revision-2017-April-12--18-13-26.zip>`__ to analyze in QL for Eclipse.
 
-  A good project to start analyzing is `ChakraCore <https://github.com/microsoft/ChakraCore>`__–a suitable snapshot to query is available by visiting the link on the slide.
+Alternatively, you can query the project in `the query console <https://lgtm.com/query/project:2034240708/lang:cpp/>`__ on LGTM.com.
 
-  Alternatively, you can query any project (including ChakraCore) in the  `query console on LGTM.com <https://lgtm.com/query/project:2034240708/lang:cpp/>`__. 
+.. note::
 
-  Note that results generated in the query console are likely to differ to those generated in the QL plugin. LGTM.com analyzes the most recent revisions of each project that has been added–the snapshot available to download above is based on an historical version of the code base.
+   Note that results generated in the query console are likely to differ to those generated in the QL plugin as LGTM.com analyzes the most recent revisions of each project that has been added–the snapshot available to download above is based on an historical version of the code base.
 
 Agenda
 ======
@@ -116,7 +108,7 @@ Find calls to free that are reachable from an allocation on the same variable:
 
 .. note::
 
-   Predicates allocationCall and freeCall are defined in the standard library and model a number of standard alloc/free-like functions.
+   Predicates ``allocationCall`` and ``freeCall`` are defined in the standard library and model a number of standard alloc/free-like functions.
 
 Exercise: use after free
 ========================
@@ -125,12 +117,12 @@ Based on this query, write a query that finds accesses to the variable that occu
 
 .. rst-class:: build
 
-- What do you find? What problems occur with this approach to detecting  use-after-free vulnerabilities?
+- What do you find? What problems occur with this approach to detecting use-after-free vulnerabilities?
 
 .. rst-class:: build
 
    .. literalinclude:: ../query-examples/cpp/control-flow-cpp-2.ql 
-         :language: ql
+      :language: ql
 
 Utilizing recursion
 ===================
@@ -300,7 +292,7 @@ Write a query that finds all calls to a field called ``error_exit``.
 
 .. code-block:: ql
 
-   class CallThroughVariable extends ExprCall { … }
+   class CallThroughVariable extends ExprCall { ... }
    
    class ErrorExitCall extends CallThroughVariable {
      override Field v;
@@ -322,7 +314,7 @@ Override ``ControlFlowNode`` to mark calls to ``error_exit`` as non-returning.
 
 .. code-block:: ql
 
-   class CallThroughVariable extends ExprCall { … }
+   class CallThroughVariable extends ExprCall { ... }
    
    class ErrorExitCall extends CallThroughVariable {
      override Field v;

docs/language/ql-training-rst/cpp/data-flow-cpp.rst

@@ -7,30 +7,22 @@ Introduction to data flow
 
 Finding string formatting vulnerabilities in C/C++
 
-Getting started and setting up
-==============================
+.. Include information slides here
 
-To try the examples in this presentation you should download:
+.. include:: ../slide-snippets/info.rst
 
-- `QL for Eclipse <https://help.semmle.com/ql-for-eclipse/Content/WebHelp/install-plugin-free.html>`__
-- Snapshot: `dotnet/coreclr <http://downloads.lgtm.com/snapshots/cpp/dotnet/coreclr/dotnet_coreclr_fbe0c77.zip>`__
+QL snapshot
+===========
 
-More resources:
+For the examples in this presentation, we will be analyzing `dotnet/coreclr <https://github.com/dotnet/coreclr>`__.
 
-- To learn more about the main features of QL, try looking at the `QL language handbook <https://help.semmle.com/QL/ql-handbook/>`__.
-- For further information about writing queries in QL, see `Writing QL queries <https://help.semmle.com/QL/learn-ql/ql/writing-queries/writing-queries.html>`__.
+We recommend you download `this historic snapshot <http://downloads.lgtm.com/snapshots/cpp/dotnet/coreclr/dotnet_coreclr_fbe0c77.zip>`__ to analyze in QL for Eclipse.
 
-.. note::
-
-  To run the queries featured in this training presentation, we recommend you download the free-to-use `QL for Eclipse plugin <https://help.semmle.com/ql-for-eclipse/Content/WebHelp/getting-started.html>`__.
-
-  This plugin allows you to locally access the latest features of QL, including the standard QL libraries and queries. It also provides standard IDE features such as syntax highlighting, jump-to-definition, and tab completion.
+Alternatively, you can query the project in `the query console <https://lgtm.com/query/projects:1505958977333/lang:cpp/>`__ on LGTM.com.
 
-  A good project to start analyzing is `ChakraCore <https://github.com/dotnet/coreclr>`__–a suitable snapshot to query is available by visiting the link on the slide.
-
-  Alternatively, you can query any project (including ChakraCore) in the  `query console on LGTM.com <https://lgtm.com/query/projects:1505958977333/lang:cpp/>`__. 
+.. note::
 
-  Note that results generated in the query console are likely to differ to those generated in the QL plugin as LGTM.com analyzes the most recent revisions of each project that has been added–the snapshot available to download above is based on an historical version of the code base.
+   Note that results generated in the query console are likely to differ to those generated in the QL plugin as LGTM.com analyzes the most recent revisions of each project that has been added–the snapshot available to download above is based on an historical version of the code base.
 
 Agenda
 ======
@@ -68,7 +60,7 @@ Let’s write a query to identify instances of `CWE-134 <https://cwe.mitre.org/d
 
   In this case, we have one more format specifier than we have arguments. In a managed language such as Java or C#, this simply leads to a runtime exception. However, in C/C++, the formatting functions are typically implemented by reading values from the stack without any validation of the number of arguments. This means a mismatch in the number of format specifiers and format arguments can lead to information disclosure.
 
-  Of course, in practice this happens rarely with *constant* formatting strings. Instead, it’s most problematic when the formatting string can be specified by the user, allowing an attacker to provide a formatting string with the wrong number of format specifiers. Furthermore, if an attacker can control the format string, they may be able to provide the %n format specifier, which causes ``printf`` to write the number characters in the generated output string to a specified location.
+  Of course, in practice this happens rarely with *constant* formatting strings. Instead, it’s most problematic when the formatting string can be specified by the user, allowing an attacker to provide a formatting string with the wrong number of format specifiers. Furthermore, if an attacker can control the format string, they may be able to provide the ``%n`` format specifier, which causes ``printf`` to write the number characters in the generated output string to a specified location.
 
   See https://en.wikipedia.org/wiki/Uncontrolled_format_string for more background.
 
@@ -107,26 +99,29 @@ We need something better.
 
   .. code-block:: cpp
 
-    const char *format = align == AlignLeft ? "%-*.*s" : "%*.*s";
-
-     if (IsDMLEnabled())
-         DMLOut(format, width, precision, mValue);
-     else
-         ExtOut(format, width, precision, mValue);
+          const char *format = align == AlignLeft ? "%-*.*s" : "%*.*s";
+      
+                if (IsDMLEnabled())
+                    DMLOut(format, width, precision, mValue);
+                else
+                    ExtOut(format, width, precision, mValue);
 
   Here, ``DMLOut`` and ``ExtOut`` are macros that expand to formatting calls. The format specifier is not constant, in the sense that the format argument is not a string literal. However, it is clearly one of two possible constants, both with the same number of format specifiers.
 
-  What we need is a way to determine whether the format argument is ever set to something that is not constant.
+  What we need is a way to determine whether the format argument is ever set to something that is, not constant.
 
 Data flow analysis
 ==================
 
 - Models flow of data through the program.
 - Implemented in the module ``semmle.code.cpp.dataflow.DataFlow``.
 - Class ``DataFlow::Node`` represents program elements that have a value, such as expressions and function parameters.
+
   - Nodes of the data flow graph.
+
 - Various predicated represent flow between these nodes.
-  Edges of the data flow graph.
+  
+  - Edges of the data flow graph.
 
 .. note::
 
@@ -183,8 +178,7 @@ Local vs global data flow
 - Local (“intra-procedural”) data flow models flow within one function; feasible to compute for all functions in a snapshot
 - Global (“inter-procedural”) data flow models flow across function calls; not feasible to compute for all functions in a snapshot
 - Different APIs, so discussed separately
-
-This slide deck focuses on the former.
+- This slide deck focuses on the former.
 
 .. note::
 
@@ -212,14 +206,14 @@ To use the data flow library, add the following import:
 .. code-block:: ql
 
    module DataFlow {
-     class Node extends … { … }
+     class Node extends ... { ... }
      predicate localFlow(Node source, Node sink) {
                localFlowStep*(source, sink)
             }
-     … 
+     ... 
    }
 
-So all references will need to be qualified (that is ``DataFlow::Node``)
+So all references will need to be qualified (that is, ``DataFlow::Node``)
 
 .. note::
 
@@ -248,7 +242,7 @@ Data flow graph
 
   The ``DataFlow::Node`` class is shared between both the local and global data flow graphs–the primary difference is the edges, which in the “global” case can link different functions.
 
-  ``localFlowStep`` is the “single step” flow relation–that is it describes single edges in the local data flow graph. ``localFlow`` represents the `transitive <https://help.semmle.com/QL/ql-handbook/recursion.html#transitive-closures>`__ closure of this relation–in other words, it contains every pair of nodes where the second node is reachable from the first in the data flow graph.
+  ``localFlowStep`` is the “single step” flow relation–that is, it describes single edges in the local data flow graph. ``localFlow`` represents the `transitive <https://help.semmle.com/QL/ql-handbook/recursion.html#transitive-closures>`__ closure of this relation–in other words, it contains every pair of nodes where the second node is reachable from the first in the data flow graph.
 
   The data flow graph is separate from the `AST <https://en.wikipedia.org/wiki/Abstract_syntax_tree>`__, to allow for flexibility in how data flow is modeled. There are a small number of data flow node types–expression nodes, parameter nodes, uninitialized variable nodes, and definition by reference nodes. Each node provides mapping functions to and from the relevant AST (for example ``Expr``, ``Parameter`` etc.) or symbol table (for example ``Variable``) classes.
 
@@ -306,7 +300,7 @@ Define a subclass of ``DataFlow::Node`` representing “source” nodes, that is
 Revisiting non-constant format strings
 ======================================
 
-Refine the query to find calls to ``printf``-like functions where the format argument derives from a local source that is not a constant string.
+Refine the query to find calls to ``printf``-like functions where the format argument derives from a local source that is, not a constant string.
 
 .. rst-class:: build
 
@@ -320,6 +314,7 @@ Audit the results and apply any refinements you deem necessary.
 Suggestions:
 
 - Replace ``DataFlow::localFlowStep`` with a custom predicate that includes steps through global variable definitions.
+
   **Hint**: Use class ``GlobalVariable`` and its member predicates ``getAnAssignedValue()`` and ``getAnAccess()``.
 
 - Exclude calls in wrapper functions that just forward their format argument to another ``printf``-like function; instead, flag calls to those functions.
@@ -330,4 +325,4 @@ Beyond local data flow
 - Results are still underwhelming.
 - Dealing with parameter passing becomes cumbersome.
 - Instead, let’s turn the problem around and find user-controlled data that flows into a ``printf`` format argument, potentially through calls.
-- This needs **global data flow**.
+- This needs **global data flow**.