Write documentation

jorgectf · jorgectf · commit a2e8d88a07df · 2021-04-09T01:47:44.000+02:00
diff --git a/python/ql/src/experimental/semmle/python/Concepts.qll b/python/ql/src/experimental/semmle/python/Concepts.qll
@@ -14,12 +14,28 @@ private import semmle.python.dataflow.new.RemoteFlowSources
 private import semmle.python.dataflow.new.TaintTracking
 private import experimental.semmle.python.Frameworks
 
+/** Provides classes for modeling LDAP-related APIs. */
 module LDAPQuery {
+  /**
+   * A data-flow node that collects methods executing a LDAP query.
+   *
+   * Extend this class to model new APIs. If you want to refine existing API models,
+   * extend `LDAPQuery` instead.
+   */
   abstract class Range extends DataFlow::Node {
+    /**
+     * Gets the argument containing the executed expression.
+     */
     abstract DataFlow::Node getLDAPNode();
   }
 }
 
+/**
+ * A data-flow node that collect methods executing a LDAP query.
+ *
+ * Extend this class to refine existing API models. If you want to model new APIs,
+ * extend `LDAPQuery::Range` instead.
+ */
 class LDAPQuery extends DataFlow::Node {
   LDAPQuery::Range range;
 
@@ -28,12 +44,28 @@ class LDAPQuery extends DataFlow::Node {
   DataFlow::Node getLDAPNode() { result = range.getLDAPNode() }
 }
 
+/** Provides classes for modeling LDAP components escape-related APIs. */
 module LDAPEscape {
+  /**
+   * A data-flow node that collects functions escaping LDAP components.
+   *
+   * Extend this class to model new APIs. If you want to refine existing API models,
+   * extend `LDAPEscape` instead.
+   */
   abstract class Range extends DataFlow::Node {
+    /**
+     * Gets the argument containing the escaped expression.
+     */
     abstract DataFlow::Node getEscapeNode();
   }
 }
 
+/**
+ * A data-flow node that collects functions escaping LDAP components.
+ *
+ * Extend this class to refine existing API models. If you want to model new APIs,
+ * extend `RegexEscape::Range` instead.
+ */
 class LDAPEscape extends DataFlow::Node {
   LDAPEscape::Range range;
 
diff --git a/python/ql/src/experimental/semmle/python/frameworks/Stdlib.qll b/python/ql/src/experimental/semmle/python/frameworks/Stdlib.qll
@@ -10,14 +10,32 @@ private import semmle.python.dataflow.new.RemoteFlowSources
 private import experimental.semmle.python.Concepts
 private import semmle.python.ApiGraphs
 
+/**
+ * Provides models for Python's ldap-related libraries.
+ */
 private module LDAP {
+  /**
+   * Provides models for Python's `ldap` library.
+   *
+   * See https://www.python-ldap.org/en/python-ldap-3.3.0/index.html
+   */
   private module LDAP2 {
+    /**
+     * List of `ldap` methods used to execute a query.
+     *
+     * See https://www.python-ldap.org/en/python-ldap-3.3.0/reference/ldap.html#functions
+     */
     private class LDAP2QueryMethods extends string {
       LDAP2QueryMethods() {
         this in ["search", "search_s", "search_st", "search_ext", "search_ext_s"]
       }
     }
 
+    /**
+     * A class to find `ldap` methods executing a query.
+     *
+     * See `LDAP2QueryMethods`
+     */
     private class LDAP2Query extends DataFlow::CallCfgNode, LDAPQuery::Range {
       DataFlow::Node ldapNode;
 
@@ -41,6 +59,11 @@ private module LDAP {
       override DataFlow::Node getLDAPNode() { result = ldapNode }
     }
 
+    /**
+     * A class to find calls to `ldap.dn.escape_dn_chars`.
+     *
+     * See https://github.com/python-ldap/python-ldap/blob/7ce471e238cdd9a4dd8d17baccd1c9e05e6f894a/Lib/ldap/dn.py#L17
+     */
     private class LDAP2EscapeDNCall extends DataFlow::CallCfgNode, LDAPEscape::Range {
       LDAP2EscapeDNCall() {
         this = API::moduleImport("ldap").getMember("dn").getMember("escape_dn_chars").getACall()
@@ -49,6 +72,11 @@ private module LDAP {
       override DataFlow::Node getEscapeNode() { result = this.getArg(0) }
     }
 
+    /**
+     * A class to find calls to `ldap.filter.escape_filter_chars`.
+     *
+     * See https://www.python-ldap.org/en/python-ldap-3.3.0/reference/ldap-filter.html#ldap.filter.escape_filter_chars
+     */
     private class LDAP2EscapeFilterCall extends DataFlow::CallCfgNode, LDAPEscape::Range {
       LDAP2EscapeFilterCall() {
         this =
@@ -59,7 +87,15 @@ private module LDAP {
     }
   }
 
+  /**
+   * Provides models for Python's `ldap3` library.
+   *
+   * See https://pypi.org/project/ldap3/
+   */
   private module LDAP3 {
+    /**
+     * A class to find `ldap3` methods executing a query.
+     */
     private class LDAP3Query extends DataFlow::CallCfgNode, LDAPQuery::Range {
       DataFlow::Node ldapNode;
 
@@ -79,6 +115,11 @@ private module LDAP {
       override DataFlow::Node getLDAPNode() { result = ldapNode }
     }
 
+    /**
+     * A class to find calls to `ldap3.utils.dn.escape_rdn`.
+     *
+     * See https://github.com/cannatag/ldap3/blob/4d33166f0869b929f59c6e6825a1b9505eb99967/ldap3/utils/dn.py#L390
+     */
     private class LDAP3EscapeDNCall extends DataFlow::CallCfgNode, LDAPEscape::Range {
       LDAP3EscapeDNCall() {
         this =
@@ -92,6 +133,11 @@ private module LDAP {
       override DataFlow::Node getEscapeNode() { result = this.getArg(0) }
     }
 
+    /**
+     * A class to find calls to `ldap3.utils.conv.escape_filter_chars`.
+     *
+     * See https://github.com/cannatag/ldap3/blob/4d33166f0869b929f59c6e6825a1b9505eb99967/ldap3/utils/conv.py#L91
+     */
     private class LDAP3EscapeFilterCall extends DataFlow::CallCfgNode, LDAPEscape::Range {
       LDAP3EscapeFilterCall() {
         this =
diff --git a/python/ql/src/experimental/semmle/python/security/injection/LDAP.qll b/python/ql/src/experimental/semmle/python/security/injection/LDAP.qll
@@ -9,7 +9,7 @@ import semmle.python.dataflow.new.TaintTracking
 import semmle.python.dataflow.new.RemoteFlowSources
 
 /**
- * A taint-tracking configuration for detecting regular expression injections.
+ * A taint-tracking configuration for detecting LDAP injections.
  */
 class LDAPInjectionFlowConfig extends TaintTracking::Configuration {
   LDAPInjectionFlowConfig() { this = "LDAPInjectionFlowConfig" }
