github · jketema · Feb 13, 2023 · Feb 13, 2023 · Feb 13, 2023 · Feb 13, 2023
diff --git a/cpp/ql/lib/semmle/code/cpp/dataflow/new/DataFlow.qll b/cpp/ql/lib/semmle/code/cpp/dataflow/new/DataFlow.qll
@@ -0,0 +1,30 @@
+/**
+ * Provides a library for local (intra-procedural) and global (inter-procedural)
+ * data flow analysis: deciding whether data can flow from a _source_ to a
+ * _sink_. This library differs from the one in `semmle.code.cpp.dataflow` in that
+ * this library uses the IR (Intermediate Representation) library, which provides
+ * a more precise semantic representation of the program, whereas the other dataflow
+ * library uses the more syntax-oriented ASTs. This library should provide more accurate
+ * results than the AST-based library in most scenarios.
+ *
+ * Unless configured otherwise, _flow_ means that the exact value of
+ * the source may reach the sink. To track flow where the exact value
+ * may not be preserved, import `semmle.code.cpp.dataflow.new.TaintTracking`.
+ *
+ * To use global (interprocedural) data flow, extend the class
+ * `DataFlow::Configuration` as documented on that class. To use local
+ * (intraprocedural) data flow between expressions, call
+ * `DataFlow::localExprFlow`. For more general cases of local data flow, call
+ * `DataFlow::localFlow` or `DataFlow::localFlowStep` with arguments of type
+ * `DataFlow::Node`.
+ */
+
+import cpp
+
+/**
+ * Provides classes for performing local (intra-procedural) and
+ * global (inter-procedural) data flow analyses.
+ */
+module DataFlow {
+  import semmle.code.cpp.ir.dataflow.internal.DataFlowImpl
+}
diff --git a/cpp/ql/lib/semmle/code/cpp/dataflow/new/DataFlow2.qll b/cpp/ql/lib/semmle/code/cpp/dataflow/new/DataFlow2.qll
@@ -0,0 +1,20 @@
+/**
+ * Provides a `DataFlow2` module, which is a copy of the `DataFlow` module. Use
+ * this class when data-flow configurations must depend on each other. Two
+ * classes extending `DataFlow::Configuration` should never depend on each
+ * other, but one of them should instead depend on a
+ * `DataFlow2::Configuration`, a `DataFlow3::Configuration`, or a
+ * `DataFlow4::Configuration`.
+ *
+ * See `semmle.code.cpp.dataflow.new.DataFlow` for the full documentation.
+ */
+
+import cpp
+
+/**
+ * Provides classes for performing local (intra-procedural) and
+ * global (inter-procedural) data flow analyses.
+ */
+module DataFlow2 {
+  import semmle.code.cpp.ir.dataflow.internal.DataFlowImpl2
+}
diff --git a/cpp/ql/lib/semmle/code/cpp/dataflow/new/DataFlow3.qll b/cpp/ql/lib/semmle/code/cpp/dataflow/new/DataFlow3.qll
@@ -0,0 +1,20 @@
+/**
+ * Provides a `DataFlow3` module, which is a copy of the `DataFlow` module. Use
+ * this class when data-flow configurations must depend on each other. Two
+ * classes extending `DataFlow::Configuration` should never depend on each
+ * other, but one of them should instead depend on a
+ * `DataFlow2::Configuration`, a `DataFlow3::Configuration`, or a
+ * `DataFlow4::Configuration`.
+ *
+ * See `semmle.code.cpp.dataflow.new.DataFlow` for the full documentation.
+ */
+
+import cpp
+
+/**
+ * Provides classes for performing local (intra-procedural) and
+ * global (inter-procedural) data flow analyses.
+ */
+module DataFlow3 {
+  import semmle.code.cpp.ir.dataflow.internal.DataFlowImpl3
+}
diff --git a/cpp/ql/lib/semmle/code/cpp/dataflow/new/DataFlow4.qll b/cpp/ql/lib/semmle/code/cpp/dataflow/new/DataFlow4.qll
@@ -0,0 +1,20 @@
+/**
+ * Provides a `DataFlow4` module, which is a copy of the `DataFlow` module. Use
+ * this class when data-flow configurations must depend on each other. Two
+ * classes extending `DataFlow::Configuration` should never depend on each
+ * other, but one of them should instead depend on a
+ * `DataFlow2::Configuration`, a `DataFlow3::Configuration`, or a
+ * `DataFlow4::Configuration`.
+ *
+ * See `semmle.code.cpp.dataflow.new.DataFlow` for the full documentation.
+ */
+
+import cpp
+
+/**
+ * Provides classes for performing local (intra-procedural) and
+ * global (inter-procedural) data flow analyses.
+ */
+module DataFlow4 {
+  import semmle.code.cpp.ir.dataflow.internal.DataFlowImpl4
+}
diff --git a/cpp/ql/lib/semmle/code/cpp/dataflow/new/TaintTracking.qll b/cpp/ql/lib/semmle/code/cpp/dataflow/new/TaintTracking.qll
@@ -0,0 +1,27 @@
+/**
+ * Provides classes for performing local (intra-procedural) and
+ * global (inter-procedural) taint-tracking analyses.
+ *
+ * We define _taint propagation_ informally to mean that a substantial part of
+ * the information from the source is preserved at the sink. For example, taint
+ * propagates from `x` to `x + 100`, but it does not propagate from `x` to `x >
+ * 100` since we consider a single bit of information to be too little.
+ *
+ * To use global (interprocedural) taint tracking, extend the class
+ * `TaintTracking::Configuration` as documented on that class. To use local
+ * (intraprocedural) taint tracking between expressions, call
+ * `TaintTracking::localExprTaint`. For more general cases of local taint
+ * tracking, call `TaintTracking::localTaint` or
+ * `TaintTracking::localTaintStep` with arguments of type `DataFlow::Node`.
+ */
+
+import semmle.code.cpp.ir.dataflow.DataFlow
+import semmle.code.cpp.ir.dataflow.DataFlow2
+
+/**
+ * Provides classes for performing local (intra-procedural) and
+ * global (inter-procedural) taint-tracking analyses.
+ */
+module TaintTracking {
+  import semmle.code.cpp.ir.dataflow.internal.tainttracking1.TaintTrackingImpl
+}
diff --git a/cpp/ql/lib/semmle/code/cpp/dataflow/new/TaintTracking2.qll b/cpp/ql/lib/semmle/code/cpp/dataflow/new/TaintTracking2.qll
@@ -0,0 +1,20 @@
+/**
+ * Provides a `TaintTracking2` module, which is a copy of the `TaintTracking`
+ * module. Use this class when data-flow configurations or taint-tracking
+ * configurations must depend on each other. Two classes extending
+ * `DataFlow::Configuration` should never depend on each other, but one of them
+ * should instead depend on a `DataFlow2::Configuration`, a
+ * `DataFlow3::Configuration`, or a `DataFlow4::Configuration`. The
+ * `TaintTracking::Configuration` class extends `DataFlow::Configuration`, and
+ * `TaintTracking2::Configuration` extends `DataFlow2::Configuration`.
+ *
+ * See `semmle.code.cpp.dataflow.new.TaintTracking` for the full documentation.
+ */
+
+/**
+ * Provides classes for performing local (intra-procedural) and
+ * global (inter-procedural) taint-tracking analyses.
+ */
+module TaintTracking2 {
+  import semmle.code.cpp.ir.dataflow.internal.tainttracking2.TaintTrackingImpl
+}
diff --git a/cpp/ql/lib/semmle/code/cpp/dataflow/new/TaintTracking3.qll b/cpp/ql/lib/semmle/code/cpp/dataflow/new/TaintTracking3.qll
@@ -0,0 +1,20 @@
+/**
+ * Provides a `TaintTracking3` module, which is a copy of the `TaintTracking`
+ * module. Use this class when data-flow configurations or taint-tracking
+ * configurations must depend on each other. Two classes extending
+ * `DataFlow::Configuration` should never depend on each other, but one of them
+ * should instead depend on a `DataFlow2::Configuration`, a
+ * `DataFlow3::Configuration`, or a `DataFlow4::Configuration`. The
+ * `TaintTracking::Configuration` class extends `DataFlow::Configuration`, and
+ * `TaintTracking2::Configuration` extends `DataFlow2::Configuration`.
+ *
+ * See `semmle.code.cpp.dataflow.new.TaintTracking` for the full documentation.
+ */
+
+/**
+ * Provides classes for performing local (intra-procedural) and
+ * global (inter-procedural) taint-tracking analyses.
+ */
+module TaintTracking3 {
+  import semmle.code.cpp.ir.dataflow.internal.tainttracking3.TaintTrackingImpl
+}
diff --git a/cpp/ql/lib/semmle/code/cpp/ir/dataflow/DataFlow.qll b/cpp/ql/lib/semmle/code/cpp/ir/dataflow/DataFlow.qll
@@ -8,8 +8,8 @@
  * results than the AST-based library in most scenarios.
  *
  * Unless configured otherwise, _flow_ means that the exact value of
- * the source may reach the sink. We do not track flow across pointer
- * dereferences or array indexing.
+ * the source may reach the sink. To track flow where the exact value
+ * may not be preserved, import `semmle.code.cpp.ir.dataflow.TaintTracking`.
  *
  * To use global (interprocedural) data flow, extend the class
  * `DataFlow::Configuration` as documented on that class. To use local