Add backward dataflow edges through modelled function invocations.

Also add convenience abstract classes for easily modelling new functions as fluent or value-preserving.

Author: smowton

java/ql/src/semmle/code/java/dataflow/internal/DataFlowUtil.qll

@@ -368,6 +368,36 @@ predicate hasNonlocalValue(FieldRead fr) {
  */
 predicate localFlowStep(Node node1, Node node2) { simpleLocalFlowStep(node1, node2) }
 
+/**
+ * A method or constructor that returns the exact value of one of its parameters or the qualifier.
+ *
+ * Extend this class and override `returnsValue` to add additional value-preserving steps through a
+ * method that should be added to the basic local flow step relation.
+ *
+ * These steps will be visible for all global data-flow purposes, as well as via
+ * `DataFlow::Node.getASuccessor` and other related functions exposing intraprocedural dataflow.
+ */
+abstract class ValuePreservingCallable extends Callable {
+  /**
+   * Holds if this callable returns precisely the value passed into argument `arg`.
+   * `arg` is a parameter index, or is -1 to indicate the qualifier.
+   */
+  abstract predicate returnsValue(int arg);
+}
+
+/**
+ * A method or constructor that returns the exact value of its qualifier (e.g., `return this;`)
+ *
+ * Extend this class and override `returnsValue` to add additional value-preserving steps through a
+ * method that should be added to the basic local flow step relation.
+ *
+ * These steps will be visible for all global data-flow purposes, as well as via
+ * `DataFlow::Node.getASuccessor` and other related functions exposing intraprocedural dataflow.
+ */
+abstract class FluentMethod extends ValuePreservingCallable {
+  override predicate returnsValue(int arg) { arg = -1 }
+}
+
 /**
  * INTERNAL: do not use.
  *
@@ -408,6 +438,17 @@ predicate simpleLocalFlowStep(Node node1, Node node2) {
   or
   summaryStep(node1, node2, "value")
   or
+  exists(MethodAccess ma, ValuePreservingCallable c, int argNo |
+    ma.getCallee() = c and c.returnsValue(argNo)
+  |
+    node2.asExpr() = ma and
+    (
+      node1.asExpr() = ma.getArgument(argNo)
+      or
+      argNo = -1 and node1.asExpr() = ma.getQualifier()
+    )
+  )
+  or
   exists(MethodAccess ma, Method m |
     ma = node2.asExpr() and
     m = ma.getMethod() and

java/ql/test/library-tests/dataflow/fluent-methods/Test.java

@@ -6,6 +6,16 @@ public Test fluentNoop() {
     return this;
   }
 
+  public Test modelledFluentMethod() {
+    // A model in the accompanying .ql file will indicate that the qualifier flows to the return value.
+    return null;
+  }
+
+  public static Test modelledIdentity(Test t) {
+    // A model in the accompanying .ql file will indicate that the argument flows to the return value.
+    return null;
+  }
+
   public Test indirectlyFluentNoop() {
     return this.fluentNoop();
   }
@@ -47,4 +57,16 @@ public static void test3() {
     sink(t.get()); // $hasTaintFlow=y
   }
 
+  public static void testModel1() {
+    Test t = new Test();
+    t.indirectlyFluentNoop().modelledFluentMethod().fluentSet(source()).fluentNoop();
+    sink(t.get()); // $hasTaintFlow=y
+  }
+
+  public static void testModel2() {
+    Test t = new Test();
+    Test.modelledIdentity(t).indirectlyFluentNoop().modelledFluentMethod().fluentSet(source()).fluentNoop();
+    sink(t.get()); // $hasTaintFlow=y
+  }
+
 }

java/ql/test/library-tests/dataflow/fluent-methods/flow.ql

@@ -1,5 +1,6 @@
 import java
 import semmle.code.java.dataflow.DataFlow
+import semmle.code.java.dataflow.FlowSteps
 import TestUtilities.InlineExpectationsTest
 
 class Conf extends DataFlow::Configuration {
@@ -14,6 +15,16 @@ class Conf extends DataFlow::Configuration {
   }
 }
 
+class Model extends DataFlow::FluentMethod {
+  Model() { this.getName() = "modelledFluentMethod" }
+}
+
+class IdentityModel extends DataFlow::ValuePreservingCallable {
+  IdentityModel() { this.getName() = "modelledIdentity" }
+
+  override predicate returnsValue(int arg) { arg = 0 }
+}
+
 class HasFlowTest extends InlineExpectationsTest {
   HasFlowTest() { this = "HasFlowTest" }