Merge pull request #2879 from hubwriter/alistairs-docs-preparation-csharp

CodeQL migration: C# topics - change titles & add intros (2174)

Author: hubwriter

docs/language/learn-ql/csharp/dataflow.rst

@@ -1,11 +1,13 @@
 Analyzing data flow in C#
 =========================
 
-Overview
---------
+You can use CodeQL to track the flow of data through a C# program to its use. 
 
-This topic 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 utilize the libraries for local data flow, global data flow, and taint tracking.
+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:`Introduction to data flow analysis with CodeQL <../intro-to-data-flow>`.
 
@@ -17,7 +19,7 @@ Local data flow is data flow within a single method or callable. Local data flow
 Using local data flow
 ~~~~~~~~~~~~~~~~~~~~~
 
-The local data flow library is in the module ``DataFlow``, which defines the class ``Node`` denoting any element that data can flow through. ``Node``\ s are divided into expression nodes (``ExprNode``) and parameter nodes (``ParameterNode``). It is possible to map between data flow nodes and expressions/parameters using the member predicates ``asExpr`` and ``asParameter``:
+The local data flow library is in the module ``DataFlow``, which defines the class ``Node`` denoting any element that data can flow through. ``Node``\ s are divided into expression nodes (``ExprNode``) and parameter nodes (``ParameterNode``). You can map between data flow nodes and expressions/parameters using the member predicates ``asExpr`` and ``asParameter``:
 
 .. code-block:: ql
 
@@ -45,9 +47,9 @@ or using the predicates ``exprNode`` and ``parameterNode``:
       */
      ParameterNode parameterNode(Parameter p) { ... }
 
-The predicate ``localFlowStep(Node nodeFrom, Node nodeTo)`` holds if there is an immediate data flow edge from the node ``nodeFrom`` to the node ``nodeTo``. The predicate can be applied recursively (using the ``+`` and ``*`` operators), or it is possible to use the predefined recursive predicate ``localFlow``.
+The predicate ``localFlowStep(Node nodeFrom, Node nodeTo)`` holds if there is an immediate data flow edge from the node ``nodeFrom`` to the node ``nodeTo``. You can apply the predicate recursively, by using the ``+`` and ``*`` operators, or you can use the predefined recursive predicate ``localFlow``.
 
-For example, finding flow from a parameter ``source`` to an expression ``sink`` in zero or more local steps can be achieved as follows:
+For example, you can find flow from a parameter ``source`` to an expression ``sink`` in zero or more local steps:
 
 .. code-block:: ql
 
@@ -65,9 +67,9 @@ Local taint tracking extends local data flow by including non-value-preserving f
 
 If ``x`` is a tainted string then ``y`` is also tainted.
 
-The local taint tracking library is in the module ``TaintTracking``. Like local data flow, a predicate ``localTaintStep(DataFlow::Node nodeFrom, DataFlow::Node nodeTo)`` holds if there is an immediate taint propagation edge from the node ``nodeFrom`` to the node ``nodeTo``. The predicate can be applied recursively (using the ``+`` and ``*`` operators), or it is possible to use the predefined recursive predicate ``localTaint``.
+The local taint tracking library is in the module ``TaintTracking``. Like local data flow, a predicate ``localTaintStep(DataFlow::Node nodeFrom, DataFlow::Node nodeTo)`` holds if there is an immediate taint propagation edge from the node ``nodeFrom`` to the node ``nodeTo``. You can apply the predicate recursively, by using the ``+`` and ``*`` operators, or you can use the predefined recursive predicate ``localTaint``.
 
-For example, finding taint propagation from a parameter ``source`` to an expression ``sink`` in zero or more local steps can be achieved as follows:
+For example, you can find taint propagation from a parameter ``source`` to an expression ``sink`` in zero or more local steps:
 
 .. code-block:: ql
 
@@ -76,7 +78,7 @@ For example, finding taint propagation from a parameter ``source`` to an express
 Examples
 ~~~~~~~~
 
-The following query finds the filename passed to ``System.IO.File.Open``:
+This query finds the filename passed to ``System.IO.File.Open``:
 
 .. code-block:: ql
 
@@ -99,7 +101,7 @@ Unfortunately this will only give the expression in the argument, not the values
      and DataFlow::localFlow(DataFlow::exprNode(src), DataFlow::exprNode(call.getArgument(0)))
    select src
 
-Then we can make the source more specific, for example an access to a public parameter. The following query finds where a public parameter is used to open a file:
+Then we can make the source more specific, for example an access to a public parameter. This query finds instances where a public parameter is used to open a file:
 
 .. code-block:: ql
 
@@ -112,7 +114,7 @@ Then we can make the source more specific, for example an access to a public par
      and call.getEnclosingCallable().(Member).isPublic()
    select p, "Opening a file from a public method."
 
-The following example finds calls to ``String.Format`` where the format string isn't hard-coded:
+This query finds calls to ``String.Format`` where the format string isn't hard-coded:
 
 .. code-block:: ql
 
@@ -139,7 +141,7 @@ Global data flow tracks data flow throughout the entire program, and is therefor
 Using global data flow
 ~~~~~~~~~~~~~~~~~~~~~~
 
-The global data flow library is used by extending the class ``DataFlow::Configuration`` as follows:
+The global data flow library is used by extending the class ``DataFlow::Configuration``:
 
 .. code-block:: ql
 
@@ -157,12 +159,12 @@ The global data flow library is used by extending the class ``DataFlow::Configur
      }
    }
 
-The following predicates are defined in the configuration:
+These predicates are defined in the configuration:
 
--  ``isSource`` - defines where data may flow from
--  ``isSink`` - defines where data may flow to
--  ``isBarrier`` - optionally, restricts the data flow
--  ``isAdditionalFlowStep`` - optionally, adds additional flow steps
+-  ``isSource`` - defines where data may flow from.
+-  ``isSink`` - defines where data may flow to.
+-  ``isBarrier`` - optionally, restricts the data flow.
+-  ``isAdditionalFlowStep`` - optionally, adds additional flow steps.
 
 The characteristic predicate (``MyDataFlowConfiguration()``) defines the name of the configuration, so ``"..."`` must be replaced with a unique name.
 
@@ -177,7 +179,7 @@ The data flow analysis is performed using the predicate ``hasFlow(DataFlow::Node
 Using global taint tracking
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Global taint tracking is to global data flow what local taint tracking is to local data flow. That is, global taint tracking extends global data flow with additional non-value-preserving steps. The global taint tracking library is used by extending the class ``TaintTracking::Configuration`` as follows:
+Global taint tracking is to global data flow what local taint tracking is to local data flow. That is, global taint tracking extends global data flow with additional non-value-preserving steps. The global taint tracking library is used by extending the class ``TaintTracking::Configuration``:
 
 .. code-block:: ql
 
@@ -195,12 +197,12 @@ Global taint tracking is to global data flow what local taint tracking is to loc
      }
    }
 
-The following predicates are defined in the configuration:
+These predicates are defined in the configuration:
 
--  ``isSource`` - defines where taint may flow from
--  ``isSink`` - defines where taint may flow to
--  ``isSanitizer`` - optionally, restricts the taint flow
--  ``isAdditionalTaintStep`` - optionally, adds additional taint steps
+-  ``isSource`` - defines where taint may flow from.
+-  ``isSink`` - defines where taint may flow to.
+-  ``isSanitizer`` - optionally, restricts the taint flow.
+-  ``isAdditionalTaintStep`` - optionally, adds additional taint steps.
 
 Similar to global data flow, the characteristic predicate (``MyTaintTrackingConfiguration()``) defines the unique name of the configuration and the taint analysis is performed using the predicate ``hasFlow(DataFlow::Node source, DataFlow::Node sink)``.
 
@@ -214,7 +216,7 @@ The class ``RemoteSourceFlow`` (defined in module ``semmle.code.csharp.dataflow.
 Example
 ~~~~~~~
 
-The following example shows a data flow configuration that uses all public API parameters as data sources.
+This query shows a data flow configuration that uses all public API parameters as data sources:
 
 .. code-block:: ql
 
@@ -236,30 +238,30 @@ The following example shows a data flow configuration that uses all public API p
 Class hierarchy
 ~~~~~~~~~~~~~~~
 
--  ``DataFlow::Configuration`` - base class for custom global data flow analysis
--  ``DataFlow::Node`` - an element behaving as a data flow node
+-  ``DataFlow::Configuration`` - base class for custom global data flow analysis.
+-  ``DataFlow::Node`` - an element behaving as a data flow node.
 
-   -  ``DataFlow::ExprNode`` - an expression behaving as a data flow node
-   -  ``DataFlow::ParameterNode`` - a parameter data flow node representing the value of a parameter at function entry
+   -  ``DataFlow::ExprNode`` - an expression behaving as a data flow node.
+   -  ``DataFlow::ParameterNode`` - a parameter data flow node representing the value of a parameter at function entry.
 
-      -  ``PublicCallableParameter`` - a parameter to a public method/callable in a public class
+      -  ``PublicCallableParameter`` - a parameter to a public method/callable in a public class.
 
-   -  ``RemoteSourceFlow`` - data flow from network/remote input
+   -  ``RemoteSourceFlow`` - data flow from network/remote input.
 
-      -  ``AspNetRemoteFlowSource`` - data flow from remote ASP.NET user input
+      -  ``AspNetRemoteFlowSource`` - data flow from remote ASP.NET user input.
 
-         -  ``AspNetQueryStringRemoteFlowSource`` - data flow from ``System.Web.HttpRequest``
-         -  ``AspNetUserInputRemoveFlowSource`` - data flow from ``System.Web.IO.WebControls.TextBox``
+         -  ``AspNetQueryStringRemoteFlowSource`` - data flow from ``System.Web.HttpRequest``.
+         -  ``AspNetUserInputRemoveFlowSource`` - data flow from ``System.Web.IO.WebControls.TextBox``.
 
-      -  ``WcfRemoteFlowSource`` - data flow from a WCF web service
-      -  ``AspNetServiceRemoteFlowSource`` - data flow from an ASP.NET web service
+      -  ``WcfRemoteFlowSource`` - data flow from a WCF web service.
+      -  ``AspNetServiceRemoteFlowSource`` - data flow from an ASP.NET web service.
 
--  ``TaintTracking::Configuration`` - base class for custom global taint tracking analysis
+-  ``TaintTracking::Configuration`` - base class for custom global taint tracking analysis.
 
 Examples
 ~~~~~~~~
 
-The following data flow configuration tracks data flow from environment variables to opening files:
+This data flow configuration tracks data flow from environment variables to opening files:
 
 .. code-block:: ql
 
@@ -300,42 +302,42 @@ Exercise 4: Using the answers from 2 and 3, write a query to find all global dat
 Extending library data flow
 ---------------------------
 
-*Library* data flow defines how data flows through libraries where the source code is not available, such as the .NET Framework, third-party libraries or proprietary libraries.
+Library data flow defines how data flows through libraries where the source code is not available, such as the .NET Framework, third-party libraries or proprietary libraries.
 
 To define new library data flow, extend the class ``LibraryTypeDataFlow`` from the module ``semmle.code.csharp.dataflow.LibraryTypeDataFlow``. Override the predicate ``callableFlow`` to define how data flows through the methods in the class. ``callableFlow`` has the signature
 
 .. code-block:: ql
 
    predicate callableFlow(CallableFlowSource source, CallableFlowSink sink, SourceDeclarationCallable callable, boolean preservesValue)
 
--  ``callable`` - the ``Callable`` (such as a method, constructor, property getter or setter) performing the data flow
--  ``source`` - the data flow input
--  ``sink`` - the data flow output
+-  ``callable`` - the ``Callable`` (such as a method, constructor, property getter or setter) performing the data flow.
+-  ``source`` - the data flow input.
+-  ``sink`` - the data flow output.
 -  ``preservesValue`` - whether the flow step preserves the value, for example if ``x`` is a string then ``x.ToString()`` preserves the value where as ``x.ToLower()`` does not.
 
 Class hierarchy
 ~~~~~~~~~~~~~~~
 
 -  ``Callable`` - a callable (methods, accessors, constructors etc.)
 
-   -  ``SourceDeclarationCallable`` - an unconstructed callable
+   -  ``SourceDeclarationCallable`` - an unconstructed callable.
 
--  ``CallableFlowSource`` - the input of data flow into the callable
+-  ``CallableFlowSource`` - the input of data flow into the callable.
 
-   -  ``CallableFlowSourceQualifier`` - the data flow comes from the object itself
-   -  ``CallableFlowSourceArg`` - the data flow comes from an argument to the call
+   -  ``CallableFlowSourceQualifier`` - the data flow comes from the object itself.
+   -  ``CallableFlowSourceArg`` - the data flow comes from an argument to the call.
 
--  ``CallableFlowSink`` - the output of data flow from the callable
+-  ``CallableFlowSink`` - the output of data flow from the callable.
 
-   -  ``CallableFlowSinkQualifier`` - the output is to the object itself
-   -  ``CallableFlowSinkReturn`` - the output is returned from the call
-   -  ``CallableFlowSinkArg`` - the output is an argument
-   -  ``CallableFlowSinkDelegateArg`` - the output flows through a delegate argument (for example, LINQ)
+   -  ``CallableFlowSinkQualifier`` - the output is to the object itself.
+   -  ``CallableFlowSinkReturn`` - the output is returned from the call.
+   -  ``CallableFlowSinkArg`` - the output is an argument.
+   -  ``CallableFlowSinkDelegateArg`` - the output flows through a delegate argument (for example, LINQ).
 
 Example
 ~~~~~~~
 
-The following example is adapted from ``LibraryTypeDataFlow.qll``. It declares data flow through the class ``System.Uri``, including the constructor, the ``ToString`` method, and the properties ``Query``, ``OriginalString``, and ``PathAndQuery``.
+This example is adapted from ``LibraryTypeDataFlow.qll``. It declares data flow through the class ``System.Uri``, including the constructor, the ``ToString`` method, and the properties ``Query``, ``OriginalString``, and ``PathAndQuery``.
 
 .. code-block:: ql
 
@@ -489,7 +491,7 @@ Exercise 4
 Exercise 5
 ~~~~~~~~~~
 
-All properties can flow data. We can declare this as follows:
+All properties can flow data:
 
 .. code-block:: ql
 
@@ -545,8 +547,8 @@ This can be adapted from the ``SystemUriFlow`` class:
      }
    }
 
-What next?
-----------
+Further reading
+---------------
 
 -  Learn about the standard libraries used to write queries for C# in :doc:`Introducing the C# libraries <introduce-libraries-csharp>`.
 -  Find out more about QL in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__ and `QL language specification <https://help.semmle.com/QL/ql-spec/language.html>`__.