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

Author: owen-mc

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)
     )

csharp/ql/lib/semmle/code/csharp/dataflow/internal/ExternalFlow.qll

@@ -4,13 +4,17 @@
  * Provides classes and predicates for dealing with MaD flow models specified
  * in data extensions and CSV format.
  *
- * The CSV specification has the following columns:
+ * The extensible relations have the following columns:
  * - Sources:
  *   `namespace; type; subtypes; name; signature; ext; output; kind; provenance`
  * - Sinks:
  *   `namespace; type; subtypes; name; signature; ext; input; kind; provenance`
  * - Summaries:
  *   `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`
  * - Neutrals:
  *   `namespace; type; name; signature; kind; provenance`
  *   A neutral is used to indicate that a callable is neutral with respect to flow (no summary), source (is not a source) or sink (is not a sink).
@@ -69,14 +73,17 @@
  *    - "Field[f]": Selects the contents of field `f`.
  *    - "Property[p]": Selects the contents of property `p`.
  *
- * 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. For neutrals the kind can be `summary`,
  *    `source` or `sink` to indicate that the neutral is neutral with respect to
  *    flow (no summary), source (is not a source) or sink (is not a sink).
- * 9. The `provenance` column is a tag to indicate the origin and verification of a model.
+ * 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:
@@ -230,11 +237,11 @@ module ModelValidation {
       result = "Unrecognized provenance description \"" + provenance + "\" in " + pred + " model."
     )
     or
-    exists(string acceptingvalue |
-      barrierGuardModel(_, _, _, _, _, _, _, acceptingvalue, _, _, _) and
-      invalidAcceptingValue(acceptingvalue) and
+    exists(string acceptingValue |
+      barrierGuardModel(_, _, _, _, _, _, _, acceptingValue, _, _, _) and
+      invalidAcceptingValue(acceptingValue) and
       result =
-        "Unrecognized accepting value description \"" + acceptingvalue +
+        "Unrecognized accepting value description \"" + acceptingValue +
           "\" in barrier guard model."
     )
   }
@@ -482,13 +489,13 @@ private module Cached {
 
   private predicate barrierGuardChecks(Guard g, Expr e, GuardValue gv, TKindModelPair kmp) {
     exists(
-      SourceSinkInterpretationInput::InterpretNode n, AcceptingValue acceptingvalue, string kind,
+      SourceSinkInterpretationInput::InterpretNode n, 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)
+      gv = convertAcceptingValue(acceptingValue)
     |
       g.(Call).getAnArgument() = e or g.(QualifiableExpr).getQualifier() = e
     )

csharp/ql/lib/semmle/code/csharp/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
 );
 
 /**

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

@@ -253,13 +253,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 namespace, string type, boolean subtypes, string name, string signature, string ext
     |
-      barrierGuardModel(namespace, type, subtypes, name, signature, ext, input, acceptingvalue,
+      barrierGuardModel(namespace, type, subtypes, name, signature, ext, input, acceptingValue,
         kind, provenance, model) and
       e = interpretElement(namespace, type, subtypes, name, signature, ext, _)
     )

go/ql/lib/semmle/go/dataflow/ExternalFlow.qll

@@ -4,13 +4,17 @@
  * Provides classes and predicates for dealing with flow models specified
  * in data extensions and CSV format.
  *
- * The CSV specification has the following columns:
+ * The extensible relations have the following columns:
  * - Sources:
  *   `package; type; subtypes; name; signature; ext; output; kind; provenance`
  * - Sinks:
  *   `package; type; subtypes; name; signature; ext; input; kind; provenance`
  * - Summaries:
  *   `package; type; subtypes; name; signature; ext; input; output; kind; provenance`
+ * - Barriers:
+ *   `package; type; subtypes; name; signature; ext; output; kind; provenance`
+ * - BarrierGuards:
+ *   `package; type; subtypes; name; signature; ext; input; acceptingValue; kind; provenance`
  * - Neutrals:
  *   `package; type; name; signature; kind; provenance`
  *   A neutral is used to indicate that a callable is neutral with respect to flow (no summary), source (is not a source) or sink (is not a sink).
@@ -78,11 +82,23 @@
  *    - "MapValue": Selects a value in a map.
  *    - "Dereference": Selects the value referenced by a pointer.
  *
- * 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.
  */
 overlay[local?]
 module;
@@ -250,11 +266,11 @@ module ModelValidation {
       result = "Unrecognized provenance description \"" + provenance + "\" in " + pred + " model."
     )
     or
-    exists(string acceptingvalue |
-      barrierGuardModel(_, _, _, _, _, _, _, acceptingvalue, _, _, _) and
-      invalidAcceptingValue(acceptingvalue) and
+    exists(string acceptingValue |
+      barrierGuardModel(_, _, _, _, _, _, _, acceptingValue, _, _, _) and
+      invalidAcceptingValue(acceptingValue) and
       result =
-        "Unrecognized accepting value description \"" + acceptingvalue +
+        "Unrecognized accepting value description \"" + acceptingValue +
           "\" in barrier guard model."
     )
   }
@@ -462,13 +478,13 @@ private module Cached {
 
   private predicate barrierGuardChecks(DataFlow::Node 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)
+      gv = convertAcceptingValue(acceptingValue)
     |
       g.asExpr().(CallExpr).getAnArgument() = e // TODO: qualifier?
     )

go/ql/lib/semmle/go/dataflow/internal/ExternalFlowExtensions.qll

@@ -35,7 +35,7 @@ extensible predicate barrierModel(
  */
 extensible predicate barrierGuardModel(
   string package, 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
 );
 
 /**

go/ql/lib/semmle/go/dataflow/internal/FlowSummaryImpl.qll

@@ -174,13 +174,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)
     )

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

@@ -4,13 +4,17 @@
  * Provides classes and predicates for dealing with flow models specified
  * in data extensions and CSV format.
  *
- * The CSV specification has the following columns:
+ * The extensible relations have the following columns:
  * - Sources:
  *   `package; type; subtypes; name; signature; ext; output; kind; provenance`
  * - Sinks:
  *   `package; type; subtypes; name; signature; ext; input; kind; provenance`
  * - Summaries:
  *   `package; type; subtypes; name; signature; ext; input; output; kind; provenance`
+ * - Barriers:
+ *   `package; type; subtypes; name; signature; ext; output; kind; provenance`
+ * - BarrierGuards:
+ *   `package; type; subtypes; name; signature; ext; input; acceptingValue; kind; provenance`
  * - Neutrals:
  *   `package; type; name; signature; kind; provenance`
  *   A neutral is used to indicate that a callable is neutral with respect to flow (no summary), source (is not a source) or sink (is not a sink).
@@ -69,14 +73,17 @@
  *      in the given range. The range is inclusive at both ends.
  *    - "ReturnValue": Selects the return value of a call to the selected element.
  *    - "Element": Selects the collection elements of the selected element.
- * 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. For neutrals the kind can be `summary`,
  *    `source` or `sink` to indicate that the neutral is neutral with respect to
  *    flow (no summary), source (is not a source) or sink (is not a sink).
- * 9. The `provenance` column is a tag to indicate the origin and verification of a model.
+ * 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:
@@ -358,11 +365,11 @@ module ModelValidation {
       result = "Unrecognized provenance description \"" + provenance + "\" in " + pred + " model."
     )
     or
-    exists(string acceptingvalue |
-      barrierGuardModel(_, _, _, _, _, _, _, acceptingvalue, _, _, _) and
-      invalidAcceptingValue(acceptingvalue) and
+    exists(string acceptingValue |
+      barrierGuardModel(_, _, _, _, _, _, _, acceptingValue, _, _, _) and
+      invalidAcceptingValue(acceptingValue) and
       result =
-        "Unrecognized accepting value description \"" + acceptingvalue +
+        "Unrecognized accepting value description \"" + acceptingValue +
           "\" in barrier guard model."
     )
   }
@@ -583,13 +590,13 @@ private module Cached {
 
   private predicate barrierGuardChecks(Guard g, Expr e, GuardValue gv, TKindModelPair kmp) {
     exists(
-      SourceSinkInterpretationInput::InterpretNode n, AcceptingValue acceptingvalue, string kind,
+      SourceSinkInterpretationInput::InterpretNode n, 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)
+      gv = convertAcceptingValue(acceptingValue)
     |
       g.(Call).getAnArgument() = e or g.(MethodCall).getQualifier() = e
     )