Merge pull request #2257 from jf205/codeql-training-material

docs: update terminology in training material

Author: shati-patel

docs/language/learn-ql/ql-training.rst

@@ -1,19 +1,19 @@
-QL training and variant analysis examples
-#########################################
+CodeQL training and variant analysis examples
+=============================================
 
-QL and variant analysis
-=======================
+CodeQL and variant analysis
+---------------------------
 
 `Variant analysis <https://semmle.com/variant-analysis>`__ is the process of using a known vulnerability as a seed to find similar problems in your code. Security engineers typically perform variant analysis to identify possible vulnerabilities and to ensure that these threats are properly fixed across multiple code bases.
 
-`QL <https://semmle.com/ql>`__ is Semmle's variant analysis engine, and it is also the technology that underpins LGTM, Semmle's community driven security analysis platform. Together, QL and LGTM provide continuous monitoring and scalable variant analysis for your projects, even if you don’t have your own team of dedicated security engineers. You can read more about using QL and LGTM in variant analysis in the `Semmle blog <https://blog.semmle.com/tags/variant-analysis>`__.
+`CodeQL <https://semmle.com/ql>`__ is the code analysis engine that underpins LGTM, Semmle's community driven security analysis platform. Together, CodeQL and LGTM provide continuous monitoring and scalable variant analysis for your projects, even if you don’t have your own team of dedicated security engineers. You can read more about using CodeQL and LGTM in variant analysis in the `Semmle blog <https://blog.semmle.com/tags/variant-analysis>`__.
 
-The QL language is easy to learn, and exploring code using QL is the most efficient way to perform variant analysis. 
+CodeQL is easy to learn, and exploring code using CodeQL is the most efficient way to perform variant analysis. 
 
-Learning QL for variant analysis
-================================
+Learning CodeQL for variant analysis
+------------------------------------
 
-Start learning how to use QL in variant analysis for a specific language by looking at the topics below. Each topic links to a short presentation on the QL language, QL libraries, or an example variant discovered using QL.
+Start learning how to use CodeQL in variant analysis for a specific language by looking at the topics below. Each topic links to a short presentation on CodeQL, its libraries, or an example variant discovered using CodeQL.
 
 .. |arrow-l| unicode:: U+2190
 
@@ -24,43 +24,43 @@ Start learning how to use QL in variant analysis for a specific language by look
 When you have selected a presentation, use |arrow-r| and |arrow-l| to navigate between slides.
 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 QL query examples.
+The presentations contain a number of query examples.
 We recommend that you download `QL for Eclipse <https://help.semmle.com/ql-for-eclipse/Content/WebHelp/home-page.html>`__ and import the example snapshot for each presentation so that you can find the bugs mentioned in the slides. 
 
 
 .. pull-quote:: 
 
    Information
 
-   The presentations listed below are used in QL language and variant analysis training sessions run by Semmle engineers. 
+   The presentations listed below are used in CodeQL and variant analysis training sessions run by Semmle engineers. 
    Therefore, be aware that the slides are designed to be presented by an instructor. 
    If you are using the slides without an instructor, please use the additional notes to help guide you through the examples. 
 
-QL and variant analysis for C/C++
----------------------------------
+CodeQL and variant analysis for C/C++
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- `Introduction to variant analysis: QL for C/C++ <../ql-training/cpp/intro-ql-cpp.html>`__–an introduction to variant analysis and QL for C/C++ programmers.
+- `Introduction to variant analysis: CodeQL for C/C++ <../ql-training/cpp/intro-ql-cpp.html>`__–an introduction to variant analysis and CodeQL for C/C++ programmers.
 - `Example: Bad overflow guard <../ql-training/cpp/bad-overflow-guard.html>`__–an example of iterative query development to find bad overflow guards in a C++ project.
-- `Program representation: QL for C/C++ <../ql-training/cpp/program-representation-cpp.html>`__–information on how QL analysis represents C/C++ programs. 
-- `Introduction to local data flow <../ql-training/cpp/data-flow-cpp.html>`__–an introduction to analyzing local data flow in C/C++ using QL, including an example demonstrating how to develop a query to find a real CVE.
+- `Program representation: CodeQL for C/C++ <../ql-training/cpp/program-representation-cpp.html>`__–information on how CodeQL analysis represents C/C++ programs. 
+- `Introduction to local data flow <../ql-training/cpp/data-flow-cpp.html>`__–an introduction to analyzing local data flow in C/C++ using CodeQL, including an example demonstrating how to develop a query to find a real CVE.
 - `Exercise: snprintf overflow <../ql-training/cpp/snprintf.html>`__–an example demonstrating how to develop a data flow query.
-- `Introduction to global data flow <../ql-training/cpp/global-data-flow-cpp.html>`__–an introduction to analyzing global data flow in C/C++ using QL.
-- `Analyzing control flow: QL for C/C++  <../ql-training/cpp/control-flow-cpp.html>`__–an introduction to analyzing control flow in C/C++ using QL.
+- `Introduction to global data flow <../ql-training/cpp/global-data-flow-cpp.html>`__–an introduction to analyzing global data flow in C/C++ using CodeQL.
+- `Analyzing control flow: CodeQL for C/C++  <../ql-training/cpp/control-flow-cpp.html>`__–an introduction to analyzing control flow in C/C++ using CodeQL.
 
-QL and variant analysis for Java
---------------------------------
+CodeQL and variant analysis for Java
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- `Introduction to variant analysis: QL for Java <../ql-training/java/intro-ql-java.html>`__–an introduction to variant analysis and QL for Java programmers.
+- `Introduction to variant analysis: CodeQL for Java <../ql-training/java/intro-ql-java.html>`__–an introduction to variant analysis and CodeQL for Java programmers.
 - `Example: Query injection <../ql-training/java/query-injection-java.html>`__–an example of iterative query development to find unsanitized SPARQL injections in a Java project.
-- `Program representation: QL for Java <../ql-training/java/program-representation-java.html>`__–information on how QL analysis represents Java programs. 
-- `Introduction to local data flow <../ql-training/java/data-flow-java.html>`__–an introduction to analyzing local data flow in Java using QL, including an example demonstrating how to develop a query to find a real CVE.
+- `Program representation: CodeQL for Java <../ql-training/java/program-representation-java.html>`__–information on how CodeQL analysis represents Java programs. 
+- `Introduction to local data flow <../ql-training/java/data-flow-java.html>`__–an introduction to analyzing local data flow in Java using CodeQL, including an example demonstrating how to develop a query to find a real CVE.
 - `Exercise: Apache Struts <../ql-training/java/apache-struts-java.html>`__–an example demonstrating how to develop a data flow query.
-- `Introduction to global data flow <../ql-training/java/global-data-flow-java.html>`__–an introduction to analyzing global data flow in Java using QL.
+- `Introduction to global data flow <../ql-training/java/global-data-flow-java.html>`__–an introduction to analyzing global data flow in Java using CodeQL.
 
 More resources
---------------
+~~~~~~~~~~~~~~
 
-- If you are completely new to QL, look at our introductory topics in :ref:`Getting started <getting-started>`.
-- To find more detailed information about how to write QL queries for specific languages, visit the links in :ref:`Writing QL queries <writing-ql-queries>`.
-- To read more about how QL queries have been used in Semmle's security research, and to read about new QL developments, visit the `Semmle blog <https://blog.semmle.com>`__. 
+- If you are completely new to CodeQL, look at our introductory topics in :doc:`Learning CodeQL <index>`.
+- To find more detailed information about how to write queries for specific languages, visit the links in :ref:`Writing CodeQL queries <writing-ql-queries>`.
+- To read more about how CodeQL queries have been used in Semmle's security research, and to read about new CodeQL developments, visit the `Semmle blog <https://blog.semmle.com>`__. 
 - Find more examples of queries written by Semmle's own security researchers in the `Semmle Demos repository <https://github.com/semmle/demos>`__ on GitHub.

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

@@ -485,6 +485,7 @@ ul {
   margin-left: 2.2em;
   margin-bottom: 1em;
   position: relative;
+  width: 90%;
 }
 /* line 300, ../scss/default.scss */
 ul li {
@@ -1300,13 +1301,13 @@ aside.gdbar img {
 .title-slide hgroup h1 {
   font-size: 2em;
   line-height: 1.4;
-  /*letter-spacing: -3px;*/
   color: white;
   margin: auto;
   display: block;
   position: absolute;
   top: 0;
   bottom: 10%;
+  left: 1.25em;
   height: 0;
 }
 /* line 898, ../scss/default.scss */
@@ -1430,31 +1431,19 @@ hgroup .pre {
   color: #5c31ff;
 }
 
-/* title slide (deck title, subtitle, semmle logo)*/
+/* title slide (deck title, subtitle)*/
 
 .title-slide {
   background-image: url("../../title-slide.svg");
   background-size: cover;
 }
 
-.semmle-logo sup {
-  vertical-align: super;
-  font-size: 0.3em;
-  font-weight: 100;
-}
-
-.title-slide .semmle-logo {
-  color: white;
-  font-size: 1.2em;
-  position: absolute;
-  top: 10%;
-}
-
 .title-slide p {
   color: white;
   font-size: 1em;
   position: absolute;
   bottom: 30%;
+  left: 2.6em;
 }
 
 .title-slide hgroup .pre {
@@ -1464,6 +1453,7 @@ hgroup .pre {
 .subheading {
   position: absolute;
   top: 62.5%;
+  left: 0;
 }
 
 .subheading p {
@@ -1569,7 +1559,7 @@ p.first.admonition-title {
   text-align: left;
   font-size: 0.8em;
   width: 100%;
-  overflow: scroll;
+  overflow: auto;
   border: 1px solid black;
 }
 
@@ -1608,7 +1598,7 @@ p.first.admonition-title {
   display: block;
   position: fixed;
   top: 0;
-  right: -1%;
+  right: 0;
   font-size: 1.2em;
 }
 

docs/language/ql-training/_static-training/title-slide.svg

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# QL training slides build configuration file
+# CodeQL training slides build configuration file
 #
 # This file is execfile()d with the current directory set to its
 # containing dir.
@@ -59,7 +59,7 @@ def setup(sphinx):
 master_doc = 'index'
 
 # General information about the project.
-project = u'QL training and variant analysis examples'
+project = u'CodeQL training and variant analysis examples'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -77,18 +77,18 @@ def setup(sphinx):
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-html_title = 'QL training and variant analysis examples'
+html_title = 'CodeQL training and variant analysis examples'
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'QL training'
+htmlhelp_basename = 'CodeQL training'
 # The Semmle version info for the current release you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = u'1.21'
+version = u'1.22'
 # The full version, including alpha/beta/rc tags.
-release = u'1.21'
+release = u'1.22'
 copyright = u'2019 Semmle Ltd'
 author = u'Semmle Ltd'
 

docs/language/ql-training/conf.py

@@ -2,11 +2,7 @@
 Example: Bad overflow guard
 ===========================
 
-QL for C/C++
-
-.. container:: semmle-logo
-
-   Semmle :sup:`TM`
+CodeQL for C/C++
 
 .. rst-class:: setup
 
@@ -16,17 +12,17 @@ Setup
 For this example you should download:
 
 - `QL for Eclipse <https://help.semmle.com/ql-for-eclipse/Content/WebHelp/install-plugin-free.html>`__
-- `ChakraCore snapshot <https://downloads.lgtm.com/snapshots/cpp/microsoft/chakracore/ChakraCore-revision-2017-April-12--18-13-26.zip>`__
+- `ChakraCore database <https://downloads.lgtm.com/snapshots/cpp/microsoft/chakracore/ChakraCore-revision-2017-April-12--18-13-26.zip>`__
 
 .. note::
 
    For the examples in this presentation, we will be analyzing `ChakraCore <https://github.com/microsoft/ChakraCore>`__.
 
    You can query the project in `the query console <https://lgtm.com/query/project:2034240708/lang:cpp/>`__ on LGTM.com.
 
-   .. insert snapshot-note.rst to explain differences between snapshot available to download and the version available in the query console.
+   .. insert database-note.rst to explain differences between database available to download and the version available in the query console.
 
-   .. include:: ../slide-snippets/snapshot-note.rst
+   .. include:: ../slide-snippets/database-note.rst
 
    .. resume slides
 
@@ -127,13 +123,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 +149,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 +176,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 +212,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.
 
@@ -233,4 +229,4 @@ The final query
 .. literalinclude:: ../query-examples/cpp/bad-overflow-guard-3.ql
    :language: ql
 
-This query finds a single result in our historic snapshot, which was `a genuine bug in ChakraCore <https://github.com/Microsoft/ChakraCore/commit/2500e1cdc12cb35af73d5c8c9b85656aba6bab4d>`__.
+This query finds a single result in our historic database, which was `a genuine bug in ChakraCore <https://github.com/Microsoft/ChakraCore/commit/2500e1cdc12cb35af73d5c8c9b85656aba6bab4d>`__.

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

@@ -2,11 +2,7 @@
 Analyzing control flow
 ======================
 
-QL for C/C++
-
-.. container:: semmle-logo
-
-   Semmle :sup:`TM`
+CodeQL for C/C++
 
 .. Include information slides here
 
@@ -18,17 +14,17 @@ Setup
 For this example you should download:
 
 - `QL for Eclipse <https://help.semmle.com/ql-for-eclipse/Content/WebHelp/install-plugin-free.html>`__
-- `ChakraCore snapshot <https://downloads.lgtm.com/snapshots/cpp/microsoft/chakracore/ChakraCore-revision-2017-April-12--18-13-26.zip>`__
+- `ChakraCore database <https://downloads.lgtm.com/snapshots/cpp/microsoft/chakracore/ChakraCore-revision-2017-April-12--18-13-26.zip>`__
 
 .. note::
 
    For the examples in this presentation, we will be analyzing `ChakraCore <https://github.com/microsoft/ChakraCore>`__.
 
    You can query the project in `the query console <https://lgtm.com/query/project:2034240708/lang:cpp/>`__ on LGTM.com.
 
-   .. insert snapshot-note.rst to explain differences between snapshot available to download and the version available in the query console.
+   .. insert database-note.rst to explain differences between database available to download and the version available in the query console.
 
-   .. include:: ../slide-snippets/snapshot-note.rst
+   .. include:: ../slide-snippets/database-note.rst
 
    .. resume slides
 
@@ -93,7 +89,7 @@ Control flow graphs
 Modeling control flow
 =====================
 
-The control flow is modeled with a QL class, ``ControlFlowNode``. Examples of control flow nodes include statements and expressions.
+The control flow is modeled with a CodeQL class, ``ControlFlowNode``. Examples of control flow nodes include statements and expressions.
 
 - ``ControlFlowNode`` provides API for traversing the control flow graph:
 
@@ -226,7 +222,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