Merge pull request #21584 from owen-mc/shared/update-mad-comments

Shared: update code comments explaining models-as-data format to include barriers and barrier guards

cpp/ql/lib/semmle/code/cpp/dataflow/ExternalFlow.qll

@@ -6,11 +6,15 @@
  *
  * The extensible relations have the following columns:
  * - Sources:
- *   `namespace; type; subtypes; name; signature; ext; output; kind`
+ *   `namespace; type; subtypes; name; signature; ext; output; kind; provenance`
  * - Sinks:
- *   `namespace; type; subtypes; name; signature; ext; input; kind`
+ *   `namespace; type; subtypes; name; signature; ext; input; kind; provenance`
  * - Summaries:
- *   `namespace; type; subtypes; name; signature; ext; input; output; kind`
+ *   `namespace; type; subtypes; name; signature; ext; input; output; kind; provenance`
+ * - Barriers:
+ *   `namespace; type; subtypes; name; signature; ext; output; kind; provenance`
+ * - BarrierGuards:
+ *   `namespace; type; subtypes; name; signature; ext; input; acceptingValue; kind; provenance`
  *
  * The interpretation of a row is similar to API-graphs with a left-to-right
  * reading.
@@ -87,11 +91,23 @@
  *    value, and
  *    - flow from the _second_ indirection of the 0th argument to the first
  *    indirection of the return value, etc.
- * 8. The `kind` column is a tag that can be referenced from QL to determine to
+ * 8. The `acceptingValue` column of barrier guard models specifies the condition
+ *    under which the guard blocks flow. It can be one of "true" or "false". In
+ *    the future "no-exception", "not-zero", "null", "not-null" may be supported.
+ * 9. The `kind` column is a tag that can be referenced from QL to determine to
  *    which classes the interpreted elements should be added. For example, for
  *    sources "remote" indicates a default remote flow source, and for summaries
  *    "taint" indicates a default additional taint step and "value" indicates a
  *    globally applicable value-preserving step.
+ * 10. The `provenance` column is a tag to indicate the origin and verification of a model.
+ *    The format is {origin}-{verification} or just "manual" where the origin describes
+ *    the origin of the model and verification describes how the model has been verified.
+ *    Some examples are:
+ *    - "df-generated": The model has been generated by the model generator tool.
+ *    - "df-manual": The model has been generated by the model generator and verified by a human.
+ *    - "manual": The model has been written by hand.
+ *    This information is used in a heuristic for dataflow analysis to determine, if a
+ *    model or source code should be used for determining flow.
  */
 
 import cpp
@@ -931,13 +947,13 @@ private module Cached {
 
   private predicate barrierGuardChecks(IRGuardCondition g, Expr e, boolean gv, TKindModelPair kmp) {
     exists(
-      SourceSinkInterpretationInput::InterpretNode n, Public::AcceptingValue acceptingvalue,
+      SourceSinkInterpretationInput::InterpretNode n, Public::AcceptingValue acceptingValue,
       string kind, string model
     |
-      isBarrierGuardNode(n, acceptingvalue, kind, model) and
+      isBarrierGuardNode(n, acceptingValue, kind, model) and
       n.asNode().asExpr() = e and
       kmp = TMkPair(kind, model) and
-      gv = convertAcceptingValue(acceptingvalue).asBooleanValue() and
+      gv = convertAcceptingValue(acceptingValue).asBooleanValue() and
       n.asNode().(Private::ArgumentNode).getCall().asCallInstruction() = g
     )
   }
@@ -954,14 +970,14 @@ private module Cached {
   ) {
     exists(
       SourceSinkInterpretationInput::InterpretNode interpretNode,
-      Public::AcceptingValue acceptingvalue, string kind, string model, int indirectionIndex,
+      Public::AcceptingValue acceptingValue, string kind, string model, int indirectionIndex,
       Private::ArgumentNode arg
     |
-      isBarrierGuardNode(interpretNode, acceptingvalue, kind, model) and
+      isBarrierGuardNode(interpretNode, acceptingValue, kind, model) and
       arg = interpretNode.asNode() and
       arg.asIndirectExpr(indirectionIndex) = e and
       kmp = MkKindModelPairIntPair(TMkPair(kind, model), indirectionIndex) and
-      gv = convertAcceptingValue(acceptingvalue).asBooleanValue() and
+      gv = convertAcceptingValue(acceptingValue).asBooleanValue() and
       arg.getCall().asCallInstruction() = g
     )
   }

cpp/ql/lib/semmle/code/cpp/dataflow/internal/ExternalFlowExtensions.qll

@@ -33,7 +33,7 @@ extensible predicate barrierModel(
  */
 extensible predicate barrierGuardModel(
   string namespace, string type, boolean subtypes, string name, string signature, string ext,
-  string input, string acceptingvalue, string kind, string provenance, QlBuiltins::ExtensionId madId
+  string input, string acceptingValue, string kind, string provenance, QlBuiltins::ExtensionId madId
 );
 
 /**

cpp/ql/lib/semmle/code/cpp/dataflow/internal/FlowSummaryImpl.qll

@@ -162,13 +162,13 @@ module SourceSinkInterpretationInput implements
   }
 
   predicate barrierGuardElement(
-    Element e, string input, Public::AcceptingValue acceptingvalue, string kind,
+    Element e, string input, Public::AcceptingValue acceptingValue, string kind,
     Public::Provenance provenance, string model
   ) {
     exists(
       string package, string type, boolean subtypes, string name, string signature, string ext
     |
-      barrierGuardModel(package, type, subtypes, name, signature, ext, input, acceptingvalue, kind,
+      barrierGuardModel(package, type, subtypes, name, signature, ext, input, acceptingValue, kind,
         provenance, model) and
       e = interpretElement(package, type, subtypes, name, signature, ext)
     )