Merge pull request #21331 from jketema/must-flow

C++: Modernize `MustFlow` and fix `allowInterproceduralFlow` in the case of direct recursion

Author: jketema

cpp/ql/lib/change-notes/2026-02-14-must-flow-fix.md

@@ -0,0 +1,4 @@
+---
+category: fix
+---
+* The `allowInterproceduralFlow` predicate of must-flow data flow configurations now correctly handles direct recursion.

cpp/ql/lib/change-notes/2026-02-14-must-flow.md

@@ -0,0 +1,4 @@
+---
+category: breaking
+---
+* `MustFlow`, the inter-procedural must-flow data flow analysis library, has been re-worked to use parameterized modules. Like in the case of data flow and taint tracking, instead of extending the `MustFlowConfiguration` class, the user should now implement a module with the `MustFlow::ConfigSig` signature, and instantiate the `MustFlow::Global` parameterized module with the implemented module.

cpp/ql/lib/semmle/code/cpp/ir/dataflow/MustFlow.qll

@@ -8,83 +8,145 @@ private import cpp
 private import semmle.code.cpp.ir.IR
 
 /**
- * A configuration of a data flow analysis that performs must-flow analysis. This is different
- * from `DataFlow.qll` which performs may-flow analysis (i.e., it finds paths where the source _may_
- * flow to the sink).
- *
- * Like in `DataFlow.qll`, each use of the `MustFlow.qll` library must define its own unique extension
- * of this abstract class. To create a configuration, extend this class with a subclass whose
- * characteristic predicate is a unique singleton string and override `isSource`, `isSink` (and
- * `isAdditionalFlowStep` if additional steps are required).
+ * Provides an inter-procedural must-flow data flow analysis.
  */
-abstract class MustFlowConfiguration extends string {
-  bindingset[this]
-  MustFlowConfiguration() { any() }
-
-  /**
-   * Holds if `source` is a relevant data flow source.
-   */
-  abstract predicate isSource(Instruction source);
-
+module MustFlow {
   /**
-   * Holds if `sink` is a relevant data flow sink.
+   * An input configuration of a data flow analysis that performs must-flow analysis. This is different
+   * from `DataFlow.qll` which performs may-flow analysis (i.e., it finds paths where the source _may_
+   * flow to the sink).
    */
-  abstract predicate isSink(Operand sink);
-
-  /**
-   * Holds if data flow through `instr` is prohibited.
-   */
-  predicate isBarrier(Instruction instr) { none() }
+  signature module ConfigSig {
+    /**
+     * Holds if `source` is a relevant data flow source.
+     */
+    predicate isSource(Instruction source);
+
+    /**
+     * Holds if `sink` is a relevant data flow sink.
+     */
+    predicate isSink(Operand sink);
+
+    /**
+     * Holds if data flow through `instr` is prohibited.
+     */
+    default predicate isBarrier(Instruction instr) { none() }
+
+    /**
+     * Holds if the additional flow step from `node1` to `node2` must be taken
+     * into account in the analysis.
+     */
+    default predicate isAdditionalFlowStep(Operand node1, Instruction node2) { none() }
+
+    /** Holds if this configuration allows flow from arguments to parameters. */
+    default predicate allowInterproceduralFlow() { any() }
+  }
 
   /**
-   * Holds if the additional flow step from `node1` to `node2` must be taken
-   * into account in the analysis.
+   * Constructs a global must-flow computation.
    */
-  predicate isAdditionalFlowStep(Operand node1, Instruction node2) { none() }
-
-  /** Holds if this configuration allows flow from arguments to parameters. */
-  predicate allowInterproceduralFlow() { any() }
+  module Global<ConfigSig Config> {
+    import Config
+
+    /**
+     * Holds if data must flow from `source` to `sink`.
+     *
+     * The corresponding paths are generated from the end-points and the graph
+     * included in the module `PathGraph`.
+     */
+    predicate flowPath(PathNode source, PathSink sink) {
+      isSource(source.getInstruction()) and
+      source.getASuccessor*() = sink
+    }
+
+    /** Holds if `node` flows from a source. */
+    pragma[nomagic]
+    private predicate flowsFromSource(Instruction node) {
+      not isBarrier(node) and
+      (
+        isSource(node)
+        or
+        exists(Instruction mid |
+          step(mid, node) and
+          flowsFromSource(mid)
+        )
+      )
+    }
+
+    /** Holds if `node` flows to a sink. */
+    pragma[nomagic]
+    private predicate flowsToSink(Instruction node) {
+      flowsFromSource(node) and
+      (
+        isSink(node.getAUse())
+        or
+        exists(Instruction mid |
+          step(node, mid) and
+          flowsToSink(mid)
+        )
+      )
+    }
 
-  /**
-   * Holds if data must flow from `source` to `sink` for this configuration.
-   *
-   * The corresponding paths are generated from the end-points and the graph
-   * included in the module `PathGraph`.
-   */
-  final predicate hasFlowPath(MustFlowPathNode source, MustFlowPathSink sink) {
-    this.isSource(source.getInstruction()) and
-    source.getASuccessor*() = sink
+    /** Holds if `nodeFrom` flows to `nodeTo`. */
+    private predicate step(Instruction nodeFrom, Instruction nodeTo) {
+      Cached::localStep(nodeFrom, nodeTo)
+      or
+      allowInterproceduralFlow() and
+      Cached::flowThroughCallable(nodeFrom, nodeTo)
+      or
+      isAdditionalFlowStep(nodeFrom.getAUse(), nodeTo)
+    }
+
+    private newtype TLocalPathNode =
+      MkLocalPathNode(Instruction n) {
+        flowsToSink(n) and
+        (
+          isSource(n)
+          or
+          exists(PathNode mid | step(mid.getInstruction(), n))
+        )
+      }
+
+    /** A `Node` that is in a path from a source to a sink. */
+    class PathNode extends TLocalPathNode {
+      Instruction n;
+
+      PathNode() { this = MkLocalPathNode(n) }
+
+      /** Gets the underlying node. */
+      Instruction getInstruction() { result = n }
+
+      /** Gets a textual representation of this node. */
+      string toString() { result = n.getAst().toString() }
+
+      /** Gets the location of this element. */
+      Location getLocation() { result = n.getLocation() }
+
+      /** Gets a successor node, if any. */
+      PathNode getASuccessor() { step(this.getInstruction(), result.getInstruction()) }
+    }
+
+    private class PathSink extends PathNode {
+      PathSink() { isSink(this.getInstruction().getAUse()) }
+    }
+
+    /**
+     * Provides the query predicates needed to include a graph in a path-problem query.
+     */
+    module PathGraph {
+      private predicate reach(PathNode n) { n instanceof PathSink or reach(n.getASuccessor()) }
+
+      /** Holds if `(a,b)` is an edge in the graph of data flow path explanations. */
+      query predicate edges(PathNode a, PathNode b) { a.getASuccessor() = b and reach(b) }
+
+      /** Holds if `n` is a node in the graph of data flow path explanations. */
+      query predicate nodes(PathNode n, string key, string val) {
+        reach(n) and key = "semmle.label" and val = n.toString()
+      }
+    }
   }
 }
 
-/** Holds if `node` flows from a source. */
-pragma[nomagic]
-private predicate flowsFromSource(Instruction node, MustFlowConfiguration config) {
-  not config.isBarrier(node) and
-  (
-    config.isSource(node)
-    or
-    exists(Instruction mid |
-      step(mid, node, config) and
-      flowsFromSource(mid, pragma[only_bind_into](config))
-    )
-  )
-}
-
-/** Holds if `node` flows to a sink. */
-pragma[nomagic]
-private predicate flowsToSink(Instruction node, MustFlowConfiguration config) {
-  flowsFromSource(node, pragma[only_bind_into](config)) and
-  (
-    config.isSink(node.getAUse())
-    or
-    exists(Instruction mid |
-      step(node, mid, config) and
-      flowsToSink(mid, pragma[only_bind_into](config))
-    )
-  )
-}
-
 cached
 private module Cached {
   /** Holds if `p` is the `n`'th parameter of the non-virtual function `f`. */
@@ -102,7 +164,7 @@ private module Cached {
     not f.isVirtual() and
     call.getPositionalArgument(n) = instr and
     f = call.getStaticCallTarget() and
-    getEnclosingNonVirtualFunctionInitializeParameter(init, f) and
+    isEnclosingNonVirtualFunctionInitializeParameter(init, f) and
     init.getParameter().getIndex() = pragma[only_bind_into](pragma[only_bind_out](n))
   }
 
@@ -111,7 +173,7 @@ private module Cached {
    * corresponding initialization instruction that receives the value of `instr` in `f`.
    */
   pragma[noinline]
-  private predicate getPositionalArgumentInitParam(
+  private predicate isPositionalArgumentInitParam(
     CallInstruction call, Instruction instr, InitializeParameterInstruction init, Function f
   ) {
     exists(int n |
@@ -126,42 +188,43 @@ private module Cached {
    * `instr` in `f`.
    */
   pragma[noinline]
-  private predicate getThisArgumentInitParam(
+  private predicate isThisArgumentInitParam(
     CallInstruction call, Instruction instr, InitializeParameterInstruction init, Function f
   ) {
     not f.isVirtual() and
     call.getStaticCallTarget() = f and
-    getEnclosingNonVirtualFunctionInitializeParameter(init, f) and
+    isEnclosingNonVirtualFunctionInitializeParameter(init, f) and
     call.getThisArgument() = instr and
     init.getIRVariable() instanceof IRThisVariable
   }
 
   /** Holds if `f` is the enclosing non-virtual function of `init`. */
-  private predicate getEnclosingNonVirtualFunctionInitializeParameter(
+  private predicate isEnclosingNonVirtualFunctionInitializeParameter(
     InitializeParameterInstruction init, Function f
   ) {
     not f.isVirtual() and
     init.getEnclosingFunction() = f
   }
 
   /** Holds if `f` is the enclosing non-virtual function of `init`. */
-  private predicate getEnclosingNonVirtualFunctionInitializeIndirection(
+  private predicate isEnclosingNonVirtualFunctionInitializeIndirection(
     InitializeIndirectionInstruction init, Function f
   ) {
     not f.isVirtual() and
     init.getEnclosingFunction() = f
   }
 
   /**
-   * Holds if `instr` is an argument (or argument indirection) to a call, and
-   * `succ` is the corresponding initialization instruction in the call target.
+   * Holds if `argument` is an argument (or argument indirection) to a call, and
+   * `parameter` is the corresponding initialization instruction in the call target.
    */
-  private predicate flowThroughCallable(Instruction argument, Instruction parameter) {
+  cached
+  predicate flowThroughCallable(Instruction argument, Instruction parameter) {
     // Flow from an argument to a parameter
     exists(CallInstruction call, InitializeParameterInstruction init | init = parameter |
-      getPositionalArgumentInitParam(call, argument, init, call.getStaticCallTarget())
+      isPositionalArgumentInitParam(call, argument, init, call.getStaticCallTarget())
       or
-      getThisArgumentInitParam(call, argument, init, call.getStaticCallTarget())
+      isThisArgumentInitParam(call, argument, init, call.getStaticCallTarget())
     )
     or
     // Flow from argument indirection to parameter indirection
@@ -170,7 +233,7 @@ private module Cached {
     |
       init = parameter and
       read.getPrimaryInstruction() = call and
-      getEnclosingNonVirtualFunctionInitializeIndirection(init, call.getStaticCallTarget())
+      isEnclosingNonVirtualFunctionInitializeIndirection(init, call.getStaticCallTarget())
     |
       exists(int n |
         read.getSideEffectOperand().getAnyDef() = argument and
@@ -205,92 +268,10 @@ private module Cached {
   }
 
   cached
-  predicate step(Instruction nodeFrom, Instruction nodeTo) {
+  predicate localStep(Instruction nodeFrom, Instruction nodeTo) {
     exists(Operand mid |
       instructionToOperandStep(nodeFrom, mid) and
       operandToInstructionStep(mid, nodeTo)
     )
-    or
-    flowThroughCallable(nodeFrom, nodeTo)
-  }
-}
-
-/**
- * Gets the enclosing callable of `n`. Unlike `n.getEnclosingCallable()`, this
- * predicate ensures that joins go from `n` to the result instead of the other
- * way around.
- */
-pragma[inline]
-private IRFunction getEnclosingCallable(Instruction n) {
-  pragma[only_bind_into](result) = pragma[only_bind_out](n).getEnclosingIRFunction()
-}
-
-/** Holds if `nodeFrom` flows to `nodeTo`. */
-private predicate step(Instruction nodeFrom, Instruction nodeTo, MustFlowConfiguration config) {
-  exists(config) and
-  Cached::step(pragma[only_bind_into](nodeFrom), pragma[only_bind_into](nodeTo)) and
-  (
-    config.allowInterproceduralFlow()
-    or
-    getEnclosingCallable(nodeFrom) = getEnclosingCallable(nodeTo)
-  )
-  or
-  config.isAdditionalFlowStep(nodeFrom.getAUse(), nodeTo)
-}
-
-private newtype TLocalPathNode =
-  MkLocalPathNode(Instruction n, MustFlowConfiguration config) {
-    flowsToSink(n, config) and
-    (
-      config.isSource(n)
-      or
-      exists(MustFlowPathNode mid | step(mid.getInstruction(), n, config))
-    )
-  }
-
-/** A `Node` that is in a path from a source to a sink. */
-class MustFlowPathNode extends TLocalPathNode {
-  Instruction n;
-
-  MustFlowPathNode() { this = MkLocalPathNode(n, _) }
-
-  /** Gets the underlying node. */
-  Instruction getInstruction() { result = n }
-
-  /** Gets a textual representation of this node. */
-  string toString() { result = n.getAst().toString() }
-
-  /** Gets the location of this element. */
-  Location getLocation() { result = n.getLocation() }
-
-  /** Gets a successor node, if any. */
-  MustFlowPathNode getASuccessor() {
-    step(this.getInstruction(), result.getInstruction(), this.getConfiguration())
-  }
-
-  /** Gets the associated configuration. */
-  MustFlowConfiguration getConfiguration() { this = MkLocalPathNode(_, result) }
-}
-
-private class MustFlowPathSink extends MustFlowPathNode {
-  MustFlowPathSink() { this.getConfiguration().isSink(this.getInstruction().getAUse()) }
-}
-
-/**
- * Provides the query predicates needed to include a graph in a path-problem query.
- */
-module PathGraph {
-  private predicate reach(MustFlowPathNode n) {
-    n instanceof MustFlowPathSink or reach(n.getASuccessor())
-  }
-
-  /** Holds if `(a,b)` is an edge in the graph of data flow path explanations. */
-  query predicate edges(MustFlowPathNode a, MustFlowPathNode b) {
-    a.getASuccessor() = b and reach(b)
-  }
-
-  /** Holds if `n` is a node in the graph of data flow path explanations. */
-  query predicate nodes(MustFlowPathNode n, string key, string val) {
-    reach(n) and key = "semmle.label" and val = n.toString()
   }
 }