From 7edebbeaffe10c5d8b7774666c34d8d58d6e194c Mon Sep 17 00:00:00 2001
From: Rasmus Lerchedahl Petersen <yoff@github.com>
Date: Wed, 6 Sep 2023 11:46:49 +0200
Subject: [PATCH] Python: Add QLDocs

---
 .../dataflow/NoSQLInjectionCustomizations.qll | 26 +++++++++++++++++++
 .../security/dataflow/NoSQLInjectionQuery.qll |  7 +++++
 2 files changed, 33 insertions(+)

diff --git a/python/ql/lib/semmle/python/security/dataflow/NoSQLInjectionCustomizations.qll b/python/ql/lib/semmle/python/security/dataflow/NoSQLInjectionCustomizations.qll
index 54c85ccf195..d3348b8df8d 100644
--- a/python/ql/lib/semmle/python/security/dataflow/NoSQLInjectionCustomizations.qll
+++ b/python/ql/lib/semmle/python/security/dataflow/NoSQLInjectionCustomizations.qll
@@ -1,41 +1,65 @@
+/**
+ * Provides default sources, sinks and sanitizers for detecting
+ * "NoSql injection"
+ * vulnerabilities, as well as extension points for adding your own.
+ */
+
 import python
 import semmle.python.dataflow.new.DataFlow
 import semmle.python.dataflow.new.RemoteFlowSources
 import semmle.python.Concepts
 
+/**
+ * Provides default sources, sinks and sanitizers for detecting
+ * "NoSql injection"
+ * vulnerabilities, as well as extension points for adding your own.
+ */
 module NoSqlInjection {
   private newtype TFlowState =
     TStringInput() or
     TDictInput()
 
+  /** A flow state, tracking the structure of the input. */
   abstract class FlowState extends TFlowState {
+    /** Gets a textual representation of this element. */
     abstract string toString();
   }
 
+  /** A state where input is only a string. */
   class StringInput extends FlowState, TStringInput {
     override string toString() { result = "StringInput" }
   }
 
+  /** A state where input is a dictionary. */
   class DictInput extends FlowState, TDictInput {
     override string toString() { result = "DictInput" }
   }
 
+  /** A source allowing string inputs. */
   abstract class StringSource extends DataFlow::Node { }
 
+  /** A source allowing dictionary inputs. */
   abstract class DictSource extends DataFlow::Node { }
 
+  /** A sink vulnerable to user controlled strings. */
   abstract class StringSink extends DataFlow::Node { }
 
+  /** A sink vulnerable to user controlled dictionaries. */
   abstract class DictSink extends DataFlow::Node { }
 
+  /** A data flow node where a string is converted into a dictionary. */
   abstract class StringToDictConversion extends DataFlow::Node {
+    /** Gets the argument that specifies the string to be converted. */
     abstract DataFlow::Node getAnInput();
 
+    /** Gets the resulting dictionary. */
     abstract DataFlow::Node getOutput();
   }
 
+  /** A remote flow source considered a source of user controlled strings. */
   class RemoteFlowSourceAsStringSource extends RemoteFlowSource, StringSource { }
 
+  /** A NoSQL query that is vulnerable to user controlled strings. */
   class NoSqlQueryAsStringSink extends StringSink {
     NoSqlQueryAsStringSink() {
       exists(NoSqlQuery noSqlQuery | this = noSqlQuery.getQuery() |
@@ -44,10 +68,12 @@ module NoSqlInjection {
     }
   }
 
+  /** A NoSQL query that is vulnerable to user controlled dictionaries. */
   class NoSqlQueryAsDictSink extends DictSink {
     NoSqlQueryAsDictSink() { this = any(NoSqlQuery noSqlQuery).getQuery() }
   }
 
+  /** A JSON decoding converts a string to a dictionary. */
   class JsonDecoding extends Decoding, StringToDictConversion {
     JsonDecoding() { this.getFormat() = "JSON" }
 
diff --git a/python/ql/lib/semmle/python/security/dataflow/NoSQLInjectionQuery.qll b/python/ql/lib/semmle/python/security/dataflow/NoSQLInjectionQuery.qll
index 8a0e31ed544..da3432e44ad 100644
--- a/python/ql/lib/semmle/python/security/dataflow/NoSQLInjectionQuery.qll
+++ b/python/ql/lib/semmle/python/security/dataflow/NoSQLInjectionQuery.qll
@@ -1,9 +1,16 @@
+/**
+ * Provides a taint-tracking configuration for detecting NoSQL injection vulnerabilities
+ */
+
 import python
 import semmle.python.dataflow.new.DataFlow
 import semmle.python.dataflow.new.TaintTracking
 import semmle.python.Concepts
 private import NoSQLInjectionCustomizations::NoSqlInjection as C
 
+/**
+ * A taint-tracking configuration for detecting NoSQL injection vulnerabilities.
+ */
 module Config implements DataFlow::StateConfigSig {
   class FlowState = C::FlowState;