C++: Update the doc text for C/C++.

Author: geoffw0

docs/codeql/codeql-language-guides/customizing-library-models-for-cpp.rst

@@ -1,7 +1,7 @@
-.. _customizing-library-models-for-csharp:
+.. _customizing-library-models-for-cpp:
 
-Customizing library models for C#
-=================================
+Customizing library models for C and C++
+========================================
 
 You can model the methods and callables that control data flow in any framework or library. This is especially useful for custom frameworks or niche libraries, that are not supported by the standard CodeQL libraries.
 
@@ -10,28 +10,28 @@ You can model the methods and callables that control data flow in any framework
 About this article
 ------------------
 
-This article contains reference material about how to define custom models for sources, sinks, and flow summaries for C# dependencies in data extension files.
+This article contains reference material about how to define custom models for sources, sinks, and flow summaries for C and C++ dependencies in data extension files.
 
 About data extensions
 ---------------------
 
-You can customize analysis by defining models (summaries, sinks, and sources) of your code's C#/.NET dependencies in data extension files. Each model defines the behavior of one or more elements of your library or framework, such as methods, properties, and callables. When you run dataflow analysis, these models expand the potential sources and sinks tracked by dataflow analysis and improve the precision of results.
+You can customize analysis by defining models (summaries, sinks, and sources) of your code's C and C++ dependencies in data extension files. Each model defines the behavior of one or more elements of your library or framework, such as callables. When you run dataflow analysis, these models expand the potential sources and sinks tracked by dataflow analysis and improve the precision of results.
 
-Most of the security queries search for paths from a source of untrusted input to a sink that represents a vulnerability. This is known as taint tracking. Each source is a starting point for dataflow analysis to track tainted data and each sink is an end point.
+Many of the security queries search for paths from a source of untrusted input to a sink that represents a vulnerability. This is known as taint tracking. Each source is a starting point for dataflow analysis to track tainted data and each sink is an end point.
 
 Taint tracking queries also need to know how data can flow through elements that are not included in the source code. These are modeled as summaries. A summary model enables queries to synthesize the flow behavior through elements in dependency code that is not stored in your repository.
 
 Syntax used to define an element in an extension file
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Each model of an element is defined using a data extension where each tuple constitutes a model.
-A data extension file to extend the standard C# queries included with CodeQL is a YAML file with the form:
+A data extension file to extend the standard CPP queries included with CodeQL is a YAML file with the form:
 
 .. code-block:: yaml
 
    extensions:
      - addsTo:
-         pack: codeql/csharp-all
+         pack: codeql/cpp-all
          extensible: <name of extensible predicate>
        data:
          - <tuple1>
@@ -50,30 +50,31 @@ Publish data extension files in a CodeQL model pack to share
 
 You can group one or more data extension files into a CodeQL model pack and publish it to the GitHub Container Registry. This makes it easy for anyone to download the model pack and use it to extend their analysis. For more information, see `Creating a CodeQL model pack <https://docs.github.com/en/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#creating-a-codeql-model-pack>`__ and `Publishing and using CodeQL packs <https://docs.github.com/en/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs/>`__ in the CodeQL CLI documentation.
 
-Extensible predicates used to create custom models in C#
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Extensible predicates used to create custom models in C and C++
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The CodeQL library for C# analysis exposes the following extensible predicates:
+The CodeQL library for CPP analysis exposes the following extensible predicates:
 
-- ``sourceModel(namespace, type, subtypes, name, signature, ext, output, kind, provenance)``. This is used to model sources of potentially tainted data. The ``kind`` of the sources defined using this predicate determine which threat model they are associated with. Different threat models can be used to customize the sources used in an analysis. For more information, see ":ref:`Threat models <threat-models-csharp>`."
+- ``sourceModel(namespace, type, subtypes, name, signature, ext, output, kind, provenance)``. This is used to model sources of potentially tainted data. The ``kind`` of the sources defined using this predicate determine which threat model they are associated with. Different threat models can be used to customize the sources used in an analysis. For more information, see ":ref:`Threat models <threat-models-cpp>`."
 - ``sinkModel(namespace, type, subtypes, name, signature, ext, input, kind, provenance)``. This is used to model sinks where tainted data may be used in a way that makes the code vulnerable.
 - ``summaryModel(namespace, type, subtypes, name, signature, ext, input, output, kind, provenance)``. This is used to model flow through elements.
-- ``neutralModel(namespace, type, name, signature, kind, provenance)``. This is similar to a summary model but used to model the flow of values that have only a minor impact on the dataflow analysis. Manual neutral models (those with a provenance such as ``manual`` or ``ai-manual``) can be used to override generated summary models (those with a provenance such as ``df-generated``), so that the summary model will be ignored. Other than that, neutral models have no effect.
 
 The extensible predicates are populated using the models defined in data extension files.
 
 Examples of custom model definitions
 ------------------------------------
 
-The examples in this section are taken from the standard CodeQL C# query pack published by GitHub. They demonstrate how to add tuples to extend extensible predicates that are used by the standard queries.
+TODO: one good example might do, but we currently have zero.
+
+The examples in this section are taken from the standard CodeQL CPP query pack published by GitHub. They demonstrate how to add tuples to extend extensible predicates that are used by the standard queries.
 
 Example: Taint sink in the ``System.Data.SqlClient`` namespace
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This example shows how the C# query pack models the argument of the ``SqlCommand`` constructor as a SQL injection sink.
+This example shows how the CPP query pack models the argument of the ``SqlCommand`` constructor as a SQL injection sink.
 This is the constructor of the ``SqlCommand`` class, which is located in the ``System.Data.SqlClient`` namespace.
 
-.. code-block:: csharp
+.. code-block:: csharp TODO
 
    public static void TaintSink(SqlConnection conn, string query) {
         SqlCommand command = new SqlCommand(query, connection) // The argument to this method is a SQL injection sink.
@@ -86,7 +87,7 @@ We need to add a tuple to the ``sinkModel``\(namespace, type, subtypes, name, si
 
    extensions:
      - addsTo:
-         pack: codeql/csharp-all
+         pack: codeql/cpp-all
          extensible: sinkModel
        data:
          - ["System.Data.SqlClient", "SqlCommand", False, "SqlCommand", "(System.String,System.Data.SqlClient.SqlConnection)", "", "Argument[0]", "sql-injection", "manual"]
@@ -109,10 +110,10 @@ The remaining values are used to define the ``access path``, the ``kind``, and t
 
 Example: Taint source from the ``System.Net.Sockets`` namespace
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This example shows how the C# query pack models the return value from the ``GetStream`` method as a ``remote`` source.
+This example shows how the CPP query pack models the return value from the ``GetStream`` method as a ``remote`` source.
 This is the ``GetStream`` method in the ``TcpClient`` class, which is located in the ``System.Net.Sockets`` namespace.
 
-.. code-block:: csharp
+.. code-block:: csharp TODO
 
    public static void Tainted(TcpClient client) {
        NetworkStream stream = client.GetStream(); // The return value of this method is a remote source of taint.
@@ -125,7 +126,7 @@ We need to add a tuple to the ``sourceModel``\(namespace, type, subtypes, name,
 
    extensions:
      - addsTo:
-         pack: codeql/csharp-all
+         pack: codeql/cpp-all
          extensible: sourceModel
        data:
          - ["System.Net.Sockets", "TcpClient", False, "GetStream", "()", "", "ReturnValue", "remote", "manual"]
@@ -144,15 +145,15 @@ The sixth value should be left empty and is out of scope for this documentation.
 The remaining values are used to define the ``access path``, the ``kind``, and the ``provenance`` (origin) of the source.
 
 - The seventh value ``ReturnValue`` is the access path to the return of the method, which means that it is the return value that should be considered a source of tainted input.
-- The eighth value ``remote`` is the kind of the source. The source kind is used to define the threat model where the source is in scope. ``remote`` applies to many of the security related queries as it means a remote source of untrusted data. As an example the SQL injection query uses ``remote`` sources. For more information, see ":ref:`Threat models <threat-models-csharp>`."
+- The eighth value ``remote`` is the kind of the source. The source kind is used to define the threat model where the source is in scope. ``remote`` applies to many of the security related queries as it means a remote source of untrusted data. As an example the SQL injection query uses ``remote`` sources. For more information, see ":ref:`Threat models <threat-models-cpp>`."
 - The ninth value ``manual`` is the provenance of the source, which is used to identify the origin of the source.
 
 Example: Add flow through the ``Concat`` method
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This example shows how the C# query pack models flow through a method for a simple case.
+This example shows how the CPP query pack models flow through a method for a simple case.
 This pattern covers many of the cases where we need to summarize flow through a method that is stored in a library or framework outside the repository.
 
-.. code-block:: csharp
+.. code-block:: cpp TODO
 
    public static void TaintFlow(string s1, string s2) {
        string t = String.Concat(s1, s2); // There is taint flow from s1 and s2 to t.
@@ -165,7 +166,7 @@ We need to add tuples to the ``summaryModel``\(namespace, type, subtypes, name,
 
    extensions:
      - addsTo:
-         pack: codeql/csharp-all
+         pack: codeql/cpp-all
          extensible: summaryModel
        data:
          - ["System", "String", False, "Concat", "(System.Object,System.Object)", "", "Argument[0]", "ReturnValue", "taint", "manual"]
@@ -198,7 +199,7 @@ It would also be possible to merge the two rows into one by using a comma-separa
 
    extensions:
      - addsTo:
-         pack: codeql/csharp-all
+         pack: codeql/cpp-all
          extensible: summaryModel
        data:
          - ["System", "String", False, "Concat", "(System.Object,System.Object)", "", "Argument[0,1]", "ReturnValue", "taint", "manual"]
@@ -207,9 +208,9 @@ This row defines flow from both the first and the second argument to the return
 
 Example: Add flow through the ``Trim`` method
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This example shows how the C# query pack models flow through a method for a simple case.
+This example shows how the CPP query pack models flow through a method for a simple case.
 
-.. code-block:: csharp
+.. code-block:: cpp TODO
 
    public static void TaintFlow(string s) {
        string t = s.Trim(); // There is taint flow from s to t.
@@ -222,7 +223,7 @@ We need to add a tuple to the ``summaryModel``\(namespace, type, subtypes, name,
 
    extensions:
      - addsTo:
-         pack: codeql/csharp-all
+         pack: codeql/cpp-all
          extensible: summaryModel
        data:
          - ["System", "String", False, "Trim", "()", "", "Argument[this]", "ReturnValue", "taint", "manual"]
@@ -250,10 +251,10 @@ The remaining values are used to define the ``access path``, the ``kind``, and t
 
 Example: Add flow through the ``Select`` method
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This example shows how the C# query pack models a more complex flow through a method.
+This example shows how the CPP query pack models a more complex flow through a method.
 Here we model flow through higher order methods and collection types, as well as how to handle extension methods and generics.
 
-.. code-block:: csharp
+.. code-block:: cpp TODO
 
    public static void TaintFlow(IEnumerable<string> stream) {
      IEnumerable<string> lines = stream.Select(item => item + "\n");
@@ -266,7 +267,7 @@ We need to add tuples to the ``summaryModel``\(namespace, type, subtypes, name,
 
    extensions:
      - addsTo:
-         pack: codeql/csharp-all
+         pack: codeql/cpp-all
          extensible: summaryModel
        data:
          - ["System.Linq", "Enumerable", False, "Select<TSource,TResult>", "(System.Collections.Generic.IEnumerable<TSource>,System.Func<TSource,TResult>)", "", "Argument[0].Element", "Argument[1].Parameter[0]", "value", "manual"]
@@ -307,41 +308,7 @@ For the remaining values for both rows:
 
 That is, the first row specifies that values can flow from the elements of the qualifier enumerable into the first argument of the function provided to ``Select``.  The second row specifies that values can flow from the return value of the function to the elements of the enumerable returned from ``Select``.
 
-Example: Add a ``neutral`` method
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This example shows how we can model a method as being neutral with respect to flow. We will also cover how to model a property by modeling the getter of the ``Now`` property of the ``DateTime`` class as neutral.
-A neutral model is used to define that there is no flow through a method.
-
-.. code-block:: csharp
-
-   public static void TaintFlow() {
-       System.DateTime t = System.DateTime.Now; // There is no flow from Now to t.
-       ...
-   }
-
-We need to add a tuple to the ``neutralModel``\(namespace, type, name, signature, kind, provenance) extensible predicate by updating a data extension file.
-
-.. code-block:: yaml
-
-   extensions:
-   - addsTo:
-       pack: codeql/csharp-all
-       extensible: neutralModel
-     data:
-       - ["System", "DateTime", "get_Now", "()", "summary", "manual"]
-
-
-Since we are adding a neutral model, we need to add tuples to the ``neutralModel`` extensible predicate.
-The first four values identify the callable (in this case the getter of the ``Now`` property) to be modeled as a neutral, the fifth value is the kind, and the sixth value is the provenance (origin) of the neutral.
-
-- The first value ``System`` is the namespace name.
-- The second value ``DateTime`` is the class (type) name.
-- The third value ``get_Now`` is the method name. Getter and setter methods are named ``get_<name>`` and ``set_<name>`` respectively.
-- The fourth value ``()`` is the method input type signature.
-- The fifth value ``summary`` is the kind of the neutral.
-- The sixth value ``manual`` is the provenance of the neutral.
-
-.. _threat-models-csharp:
+.. _threat-models-cpp:
 
 Threat models
 -------------