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

python/ql/lib/semmle/python/frameworks/data/internal/ApiGraphModels.qll

@@ -10,6 +10,10 @@
  *   `type, path, kind`
  * - Summaries:
  *   `type, path, input, output, kind`
+ * - Barriers:
+ *   `type, path, kind`
+ * - BarrierGuards:
+ *   `type, path, acceptingValue, kind`
  * - Types:
  *   `type1, type2, path`
  *
@@ -42,7 +46,8 @@
  * 3. The `input` and `output` columns specify how data enters and leaves the element selected by the
  *    first `(type, path)` tuple. Both strings are `.`-separated access paths
  *    of the same syntax as the `path` column.
- * 4. The `kind` column is a tag that can be referenced from QL to determine to
+ * 4. The `acceptingValue` column of barrier guard models specifies which branch of the guard is blocking flow. It can be "true" or "false".
+ * 5. 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
@@ -355,11 +360,11 @@ private predicate barrierModel(string type, string path, string kind, string mod
 
 /** Holds if a barrier guard model exists for the given parameters. */
 private predicate barrierGuardModel(
-  string type, string path, string branch, string kind, string model
+  string type, string path, string acceptingValue, string kind, string model
 ) {
   // No deprecation adapter for barrier models, they were not around back then.
   exists(QlBuiltins::ExtensionId madId |
-    Extensions::barrierGuardModel(type, path, branch, kind, madId) and
+    Extensions::barrierGuardModel(type, path, acceptingValue, kind, madId) and
     model = "MaD:" + madId.toString()
   )
 }
@@ -783,16 +788,16 @@ module ModelOutput {
     }
 
     /**
-     * Holds if a barrier model contributed `barrier` with the given `kind` for the given `branch`.
+     * Holds if a barrier model contributed `barrier` with the given `kind` for the given `acceptingValue`.
      */
     cached
-    API::Node getABarrierGuardNode(string kind, boolean branch, string model) {
-      exists(string type, string path, string branch_str |
-        branch = true and branch_str = "true"
+    API::Node getABarrierGuardNode(string kind, boolean acceptingValue, string model) {
+      exists(string type, string path, string acceptingValue_str |
+        acceptingValue = true and acceptingValue_str = "true"
         or
-        branch = false and branch_str = "false"
+        acceptingValue = false and acceptingValue_str = "false"
       |
-        barrierGuardModel(type, path, branch_str, kind, model) and
+        barrierGuardModel(type, path, acceptingValue_str, kind, model) and
         result = getNodeFromPath(type, path)
       )
     }
@@ -856,12 +861,12 @@ module ModelOutput {
   API::Node getABarrierNode(string kind) { result = getABarrierNode(kind, _) }
 
   /**
-   * Holds if an external model contributed `barrier-guard` with the given `kind` and `branch`.
+   * Holds if an external model contributed `barrier-guard` with the given `kind` and `acceptingValue`.
    *
    * INTERNAL: Do not use.
    */
-  API::Node getABarrierGuardNode(string kind, boolean branch) {
-    result = getABarrierGuardNode(kind, branch, _)
+  API::Node getABarrierGuardNode(string kind, boolean acceptingValue) {
+    result = getABarrierGuardNode(kind, acceptingValue, _)
   }
 
   /**

python/ql/lib/semmle/python/frameworks/data/internal/ApiGraphModelsExtensions.qll

@@ -33,11 +33,11 @@ extensible predicate barrierModel(
  * of the given `kind` and `madId` is the data extension row number.
  * `path` is assumed to lead to a parameter of a call (possibly `self`), and
  * the call is guarding the parameter.
- * `branch` is either `true` or `false`, indicating which branch of the guard
- * is protecting the parameter.
+ * `acceptingValue` is either `true` or `false`, indicating which branch of
+ * the guard is protecting the parameter.
  */
 extensible predicate barrierGuardModel(
-  string type, string path, string branch, string kind, QlBuiltins::ExtensionId madId
+  string type, string path, string acceptingValue, string kind, QlBuiltins::ExtensionId madId
 );
 
 /**