Write documentation

python/ql/src/experimental/semmle/python/Concepts.qll

@@ -14,14 +14,33 @@ 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 bind-related APIs. */
 module LDAPBind {
+  /**
+   * A data-flow node that collects methods binding a LDAP connection.
+   *
+   * Extend this class to model new APIs. If you want to refine existing API models,
+   * extend `LDAPBind` instead.
+   */
   abstract class Range extends DataFlow::Node {
+    /**
+     * Gets the argument containing the binding expression.
+     */
     abstract DataFlow::Node getPasswordNode();
 
+    /**
+     * Gets the argument containing the executed query.
+     */
     abstract DataFlow::Node getQueryNode();
   }
 }
 
+/**
+ * A data-flow node that collects methods binding a LDAP connection.
+ *
+ * Extend this class to refine existing API models. If you want to model new APIs,
+ * extend `LDAPBind::Range` instead.
+ */
 class LDAPBind extends DataFlow::Node {
   LDAPBind::Range range;
 

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 binding a connection.
+     *
+     * See `LDAP2QueryMethods`
+     */
     class LDAP2Bind extends DataFlow::CallCfgNode, LDAPBind::Range {
       DataFlow::Node queryNode;
 
@@ -46,7 +64,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 binding a connection.
+     */
     class LDAP3Bind extends DataFlow::CallCfgNode, LDAPBind::Range {
       DataFlow::Node queryNode;
 

python/ql/src/experimental/semmle/python/security/LDAPImproperAuth.qll

@@ -1,9 +1,16 @@
+/**
+ * Provides a taint-tracking configuration for detecting LDAP improper authentication vulnerabilities
+ */
+
 import python
 import experimental.semmle.python.Concepts
 import semmle.python.dataflow.new.DataFlow
 import semmle.python.dataflow.new.TaintTracking
 import semmle.python.dataflow.new.RemoteFlowSources
 
+/**
+ * A class to find `LDAPBind` methods using an empty password or set as None.
+ */
 class LDAPImproperAuthSink extends DataFlow::Node {
   LDAPImproperAuthSink() {
     exists(LDAPBind ldapBind |
@@ -23,6 +30,9 @@ class LDAPImproperAuthSink extends DataFlow::Node {
   }
 }
 
+/**
+ * A taint-tracking configuration for detecting LDAP improper authentications.
+ */
 class LDAPImproperAuthenticationConfig extends TaintTracking::Configuration {
   LDAPImproperAuthenticationConfig() { this = "LDAPImproperAuthenticationConfig" }