Docs: Update data flow documentation to the new API.

Author: aschackmull

docs/codeql/codeql-language-guides/analyzing-data-flow-in-cpp-new.rst

@@ -168,74 +168,61 @@ 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 implementing the signature ``DataFlow::ConfigSig`` and applying the module ``DataFlow::Global<ConfigSig>`` as follows:
 
 .. code-block:: ql
 
    import semmle.code.cpp.dataflow.new.DataFlow
 
-   class MyDataFlowConfiguration extends DataFlow::Configuration {
-     MyDataFlowConfiguration() { this = "MyDataFlowConfiguration" }
-
-     override predicate isSource(DataFlow::Node source) {
+   module MyFlowConfiguration implements DataFlow::ConfigSig {
+     predicate isSource(DataFlow::Node source) {
        ...
      }
 
-     override predicate isSink(DataFlow::Node sink) {
+     predicate isSink(DataFlow::Node sink) {
        ...
      }
    }
 
+   module MyFlow = DataFlow::Global<MyFlowConfiguration>;
+
 The following predicates are defined in the configuration:
 
 -  ``isSource``—defines where data may flow from
 -  ``isSink``—defines where data may flow to
 -  ``isBarrier``—optional, restricts the data flow
--  ``isBarrierGuard``—optional, restricts the data flow
 -  ``isAdditionalFlowStep``—optional, adds additional flow steps
 
-The characteristic predicate ``MyDataFlowConfiguration()`` defines the name of the configuration, so ``"MyDataFlowConfiguration"`` should be replaced by the name of your class.
-
-The data flow analysis is performed using the predicate ``hasFlow(DataFlow::Node source, DataFlow::Node sink)``:
+The data flow analysis is performed using the predicate ``flow(DataFlow::Node source, DataFlow::Node sink)``:
 
 .. code-block:: ql
 
-   from MyDataFlowConfiguration dataflow, DataFlow::Node source, DataFlow::Node sink
-   where dataflow.hasFlow(source, sink)
+   from DataFlow::Node source, DataFlow::Node sink
+   where MyFlow::flow(source, sink)
    select source, "Data flow to $@.", sink, sink.toString()
 
 Using global taint tracking
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Global taint tracking is to global data flow as 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 as 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 applying the module ``TaintTracking::Global<ConfigSig>`` to your configuration instead of ``DataFlow::Global<ConfigSig>`` as follows:
 
 .. code-block:: ql
 
    import semmle.code.cpp.dataflow.new.TaintTracking
 
-   class MyTaintTrackingConfiguration extends TaintTracking::Configuration {
-     MyTaintTrackingConfiguration() { this = "MyTaintTrackingConfiguration" }
-
-     override predicate isSource(DataFlow::Node source) {
+   module MyFlowConfiguration implements DataFlow::ConfigSig {
+     predicate isSource(DataFlow::Node source) {
        ...
      }
 
-     override predicate isSink(DataFlow::Node sink) {
+     predicate isSink(DataFlow::Node sink) {
        ...
      }
    }
 
-The following predicates are defined in the configuration:
-
--  ``isSource``—defines where taint may flow from
--  ``isSink``—defines where taint may flow to
--  ``isSanitizer``—optional, restricts the taint flow
--  ``isSanitizerGuard``—optional, restricts the taint flow
--  ``isAdditionalTaintStep``—optional, adds additional taint steps
+   module MyFlow = TaintTracking::Global<MyFlowConfiguration>;
 
-Similar to global data flow, the characteristic predicate ``MyTaintTrackingConfiguration()`` defines the unique name of the configuration, so ``"MyTaintTrackingConfiguration"`` should be replaced by the name of your class.
-
-The taint tracking analysis is performed using the predicate ``hasFlow(DataFlow::Node source, DataFlow::Node sink)``.
+The resulting module is completely similar to the one obtained from ``DataFlow::Global<ConfigSig>``.
 
 Examples
 ~~~~~~~~
@@ -247,53 +234,50 @@ The following data flow configuration tracks data flow from environment variable
    import cpp
    import semmle.code.cpp.dataflow.new.DataFlow
 
-   class EnvironmentToFileConfiguration extends DataFlow::Configuration {
-     EnvironmentToFileConfiguration() { this = "EnvironmentToFileConfiguration" }
-
-     override predicate isSource(DataFlow::Node source) {
+   module EnvironmentToFileConfiguration implements DataFlow::ConfigSig {
+     predicate isSource(DataFlow::Node source) {
        exists(Function getenv |
          source.asIndirectExpr(1).(FunctionCall).getTarget() = getenv and
          getenv.hasGlobalName("getenv")
        )
      }
 
-     override predicate isSink(DataFlow::Node sink) {
+     predicate isSink(DataFlow::Node sink) {
        exists(FunctionCall fc |
          sink.asIndirectExpr(1) = fc.getArgument(0) and
          fc.getTarget().hasGlobalName("fopen")
        )
      }
    }
 
+   module EnvironmentToFileFlow = DataFlow::Global<EnvironmentToFileConfiguration>;
+
    from
-     Expr getenv, Expr fopen, EnvironmentToFileConfiguration config, DataFlow::Node source,
-     DataFlow::Node sink
+     Expr getenv, Expr fopen, DataFlow::Node source, DataFlow::Node sink
    where
      source.asIndirectExpr(1) = getenv and
      sink.asIndirectExpr(1) = fopen and
-     config.hasFlow(source, sink)
+     EnvironmentToFileFlow::flow(source, sink)
    select fopen, "This 'fopen' uses data from $@.", getenv, "call to 'getenv'"
 
-The following taint-tracking configuration tracks data from a call to ``ntohl`` to an array index operation. It uses the ``Guards`` library to recognize expressions that have been bounds-checked, and defines ``isSanitizer`` to prevent taint from propagating through them. It also uses ``isAdditionalTaintStep`` to add flow from loop bounds to loop indexes.
+The following taint-tracking configuration tracks data from a call to ``ntohl`` to an array index operation. It uses the ``Guards`` library to recognize expressions that have been bounds-checked, and defines ``isBarrier`` to prevent taint from propagating through them. It also uses ``isAdditionalFlowStep`` to add flow from loop bounds to loop indexes.
 
 .. code-block:: ql
 
    import cpp
    import semmle.code.cpp.controlflow.Guards
    import semmle.code.cpp.dataflow.new.TaintTracking
 
-   class NetworkToBufferSizeConfiguration extends TaintTracking::Configuration {
-     NetworkToBufferSizeConfiguration() { this = "NetworkToBufferSizeConfiguration" }
-
-     override predicate isSource(DataFlow::Node node) {
+   module NetworkToBufferSizeConfiguration implements DataFlow::ConfigSig {
+     predicate isSource(DataFlow::Node node) {
        node.asExpr().(FunctionCall).getTarget().hasGlobalName("ntohl")
      }
 
-     override predicate isSink(DataFlow::Node node) {
+     predicate isSink(DataFlow::Node node) {
        exists(ArrayExpr ae | node.asExpr() = ae.getArrayOffset())
      }
 
-     override predicate isAdditionalTaintStep(DataFlow::Node pred, DataFlow::Node succ) {
+     predicate isAdditionalFlowStep(DataFlow::Node pred, DataFlow::Node succ) {
        exists(Loop loop, LoopCounter lc |
          loop = lc.getALoop() and
          loop.getControllingExpr().(RelationalOperation).getGreaterOperand() = pred.asExpr()
@@ -302,7 +286,7 @@ The following taint-tracking configuration tracks data from a call to ``ntohl``
        )
      }
 
-     override predicate isSanitizer(DataFlow::Node node) {
+     predicate isBarrier(DataFlow::Node node) {
        exists(GuardCondition gc, Variable v |
          gc.getAChild*() = v.getAnAccess() and
          node.asExpr() = v.getAnAccess() and
@@ -312,8 +296,10 @@ The following taint-tracking configuration tracks data from a call to ``ntohl``
      }
    }
 
-   from DataFlow::Node ntohl, DataFlow::Node offset, NetworkToBufferSizeConfiguration conf
-   where conf.hasFlow(ntohl, offset)
+   module NetworkToBufferSizeFlow = TaintTracking::Global<NetworkToBufferSizeConfiguration>;
+
+   from DataFlow::Node ntohl, DataFlow::Node offset
+   where NetworkToBufferSizeFlow::flow(ntohl, offset)
    select offset, "This array offset may be influenced by $@.", ntohl,
      "converted data from the network"
 
@@ -353,28 +339,27 @@ Exercise 2
    import cpp
    import semmle.code.cpp.dataflow.new.DataFlow
 
-   class LiteralToGethostbynameConfiguration extends DataFlow::Configuration {
-     LiteralToGethostbynameConfiguration() { this = "LiteralToGethostbynameConfiguration" }
-
-     override predicate isSource(DataFlow::Node source) {
+   module LiteralToGethostbynameConfiguration implements DataFlow::ConfigSig {
+     predicate isSource(DataFlow::Node source) {
        source.asIndirectExpr(1) instanceof StringLiteral
      }
 
-     override predicate isSink(DataFlow::Node sink) {
+     predicate isSink(DataFlow::Node sink) {
        exists(FunctionCall fc |
          sink.asIndirectExpr(1) = fc.getArgument(0) and
          fc.getTarget().hasName("gethostbyname")
        )
      }
    }
 
+   module LiteralToGethostbynameFlow = DataFlow::Global<LiteralToGethostbynameConfiguration>;
+
    from
-     StringLiteral sl, FunctionCall fc, LiteralToGethostbynameConfiguration cfg, DataFlow::Node source,
-     DataFlow::Node sink
+     StringLiteral sl, FunctionCall fc, DataFlow::Node source, DataFlow::Node sink
    where
      source.asIndirectExpr(1) = sl and
      sink.asIndirectExpr(1) = fc.getArgument(0) and
-     cfg.hasFlow(source, sink)
+     LiteralToGethostbynameFlow::flow(source, sink)
    select sl, fc
 
 Exercise 3
@@ -401,26 +386,25 @@ Exercise 4
      GetenvSource() { this.asIndirectExpr(1).(FunctionCall).getTarget().hasGlobalName("getenv") }
    }
 
-   class GetenvToGethostbynameConfiguration extends DataFlow::Configuration {
-     GetenvToGethostbynameConfiguration() { this = "GetenvToGethostbynameConfiguration" }
-
-     override predicate isSource(DataFlow::Node source) { source instanceof GetenvSource }
+   module GetenvToGethostbynameConfiguration implements DataFlow::ConfigSig {
+     predicate isSource(DataFlow::Node source) { source instanceof GetenvSource }
 
-     override predicate isSink(DataFlow::Node sink) {
+     predicate isSink(DataFlow::Node sink) {
        exists(FunctionCall fc |
          sink.asIndirectExpr(1) = fc.getArgument(0) and
          fc.getTarget().hasName("gethostbyname")
        )
      }
    }
 
+   module GetenvToGethostbynameFlow = DataFlow::Global<GetenvToGethostbynameConfiguration>;
+
    from
-     Expr getenv, FunctionCall fc, GetenvToGethostbynameConfiguration cfg, DataFlow::Node source,
-     DataFlow::Node sink
+     Expr getenv, FunctionCall fc, DataFlow::Node source, DataFlow::Node sink
    where
      source.asIndirectExpr(1) = getenv and
      sink.asIndirectExpr(1) = fc.getArgument(0) and
-     cfg.hasFlow(source, sink)
+     GetenvToGethostbynameFlow::flow(source, sink)
    select getenv, fc
 
 Further reading
@@ -430,4 +414,4 @@ Further reading
 
 
 .. include:: ../reusables/cpp-further-reading.rst
-.. include:: ../reusables/codeql-ref-tools-further-reading.rst
+.. include:: ../reusables/codeql-ref-tools-further-reading.rst