Merge pull request #67 from max-schaefer/more-qldoc

Add missing Qldoc for modules.

ql/src/RedundantCode/Clones.qll

@@ -168,13 +168,17 @@ class HashableNAryNode extends HashableNode {
  * have identical hashes they are structurally identical.
  */
 newtype HashedNode =
+  /** A hashed representation of an AST node without any child nodes. */
   MkHashedNullaryNode(int kind, string value) { any(HashableNullaryNode nd).unpack(kind, value) } or
+  /** A hashed representation of an AST node with a single child node. */
   MkHashedUnaryNode(int kind, string value, HashedNode child) {
     any(HashableUnaryNode nd).unpack(kind, value, child)
   } or
+  /** A hashed representation of an AST node with two child nodes. */
   MkHashedBinaryNode(int kind, string value, HashedNode left, HashedNode right) {
     any(HashableBinaryNode nd).unpack(kind, value, left, right)
   } or
+  /** A hashed representation of an AST node with three or more child nodes. */
   MkHashedNAryNode(int kind, string value, HashedChildren children) {
     any(HashableNAryNode nd).unpack(kind, value, children)
   }

ql/src/semmle/go/Concepts.qll

@@ -23,6 +23,7 @@ class SystemCommandExecution extends DataFlow::Node {
   DataFlow::Node getCommandName() { result = self.getCommandName() }
 }
 
+/** Provides a class for modeling new system-command execution APIs. */
 module SystemCommandExecution {
   /**
    * A data-flow node that executes an operating system command,
@@ -61,6 +62,7 @@ class TemplateInstantiation extends DataFlow::Node {
   DataFlow::Node getADataArgument() { result = self.getADataArgument() }
 }
 
+/** Provides a class for modeling new template-instantiation APIs. */
 module TemplateInstantiation {
   /**
    * An instantiation of a template; that is, a call which fills out a template with data.
@@ -99,6 +101,7 @@ class FileSystemAccess extends DataFlow::Node {
   DataFlow::Node getAPathArgument() { result = self.getAPathArgument() }
 }
 
+/** Provides a class for modeling new file-system access APIs. */
 module FileSystemAccess {
   /**
    * A data-flow node that performs a file system access, including reading and writing data,
@@ -127,6 +130,7 @@ class EscapeFunction extends Function {
   string kind() { result = self.kind() }
 }
 
+/** Provides a class for modeling new escape-function APIs. */
 module EscapeFunction {
   /**
    * A function that escapes meta-characters to prevent injection attacks.
@@ -198,6 +202,7 @@ class RegexpPattern extends DataFlow::Node {
   DataFlow::Node getAUse() { result = self.getAUse() }
 }
 
+/** Provides a class for modeling new regular-expression APIs. */
 module RegexpPattern {
   /**
    * A node whose value is interpreted as a part of a regular expression.
@@ -259,6 +264,7 @@ class RegexpMatchFunction extends Function {
   FunctionOutput getResult() { result = self.getResult() }
 }
 
+/** Provides a class for modeling new regular-expression matcher APIs. */
 module RegexpMatchFunction {
   /**
    * A function that matches a regexp with a string or byte slice.
@@ -321,6 +327,7 @@ class RegexpReplaceFunction extends Function {
   FunctionOutput getResult() { result = self.getResult() }
 }
 
+/** Provides a class for modeling new regular-expression replacer APIs. */
 module RegexpReplaceFunction {
   /**
    * A function that uses a regexp to replace parts of a string or byte slice.
@@ -348,7 +355,9 @@ module RegexpReplaceFunction {
   }
 }
 
+/** Provides classes for modeling HTTP-related APIs. */
 module HTTP {
+  /** Provides a class for modeling new HTTP response-writer APIs. */
   module ResponseWriter {
     /**
      * A variable that is an HTTP response writer.
@@ -386,6 +395,7 @@ module HTTP {
     DataFlow::Node getANode() { result = self.getANode() }
   }
 
+  /** Provides a class for modeling new HTTP header-write APIs. */
   module HeaderWrite {
     /**
      * A data-flow node that represents a write to an HTTP header.
@@ -465,6 +475,7 @@ module HTTP {
     HeaderName() { this = hw.getName() }
   }
 
+  /** Provides a class for modeling new HTTP request-body APIs. */
   module RequestBody {
     /**
      * An expression representing a reader whose content is written to an HTTP request body.
@@ -487,6 +498,7 @@ module HTTP {
     RequestBody() { this = self }
   }
 
+  /** Provides a class for modeling new HTTP response-body APIs. */
   module ResponseBody {
     /**
      * An expression which is written to an HTTP response body.
@@ -515,6 +527,7 @@ module HTTP {
     ResponseWriter getResponseWriter() { result = self.getResponseWriter() }
   }
 
+  /** Provides a class for modeling new HTTP redirect APIs. */
   module Redirect {
     /**
      * An HTTP redirect.
@@ -577,6 +590,7 @@ class LoggerCall extends DataFlow::Node {
   DataFlow::Node getAMessageComponent() { result = self.getAMessageComponent() }
 }
 
+/** Provides a class for modeling new logging APIs. */
 module LoggerCall {
   /**
    * A call to a logging mechanism.
@@ -611,6 +625,7 @@ class MarshalingFunction extends Function {
   string getFormat() { result = self.getFormat() }
 }
 
+/** Provides a class for modeling new marshaling APIs. */
 module MarshalingFunction {
   /**
    * A function that encodes data into a binary or textual format.
@@ -651,6 +666,7 @@ class UnmarshalingFunction extends Function {
   string getFormat() { result = self.getFormat() }
 }
 
+/** Provides a class for modeling new unmarshaling APIs. */
 module UnmarshalingFunction {
   /**
    * A function that decodes data from a binary or textual format.

ql/src/semmle/go/StringOps.qll

@@ -4,6 +4,7 @@
 
 import go
 
+/** Provides predicates and classes for working with string operations. */
 module StringOps {
   /**
    * An expression that is equivalent to `strings.HasPrefix(A, B)` or `!strings.HasPrefix(A, B)`.
@@ -37,6 +38,7 @@ module StringOps {
 
   class StartsWith = HasPrefix;
 
+  /** Provides predicates and classes for working with prefix checks. */
   module HasPrefix {
     /**
      * An expression that is equivalent to `strings.HasPrefix(A, B)` or `!strings.HasPrefix(A, B)`.
@@ -170,6 +172,7 @@ module StringOps {
     int getNumOperand() { result = self.getNumOperand() }
   }
 
+  /** Provides predicates and classes for working with string concatenations. */
   module Concatenation {
     /**
      * A data-flow node that performs string concatenation.

ql/src/semmle/go/controlflow/IR.qll

@@ -13,6 +13,7 @@
 import go
 private import semmle.go.controlflow.ControlFlowGraphImpl
 
+/** Provides predicates and classes for working with IR constructs. */
 module IR {
   /**
    * An IR instruction.

ql/src/semmle/go/dataflow/DataFlow.qll

@@ -17,6 +17,10 @@
 
 import go
 
+/**
+ * Provides a library for local (intra-procedural) and global (inter-procedural)
+ * data flow analysis.
+ */
 module DataFlow {
   import semmle.go.dataflow.internal.DataFlowImpl
   import Properties

ql/src/semmle/go/dataflow/SSA.qll

@@ -181,6 +181,7 @@ class SsaExplicitDefinition extends SsaDefinition, TExplicitDef {
   }
 }
 
+/** Provides a helper predicate for working with explicit SSA definitions. */
 module SsaExplicitDefinition {
   /**
    * Gets the SSA definition corresponding to definition `def`.

ql/src/semmle/go/dataflow/TaintTracking.qll

@@ -5,6 +5,10 @@
 
 import semmle.go.dataflow.DataFlow
 
+/**
+ * Provides classes for performing local (intra-procedural) and
+ * global (inter-procedural) taint-tracking analyses.
+ */
 module TaintTracking {
   import semmle.go.dataflow.internal.tainttracking1.TaintTrackingImpl
 }

ql/src/semmle/go/frameworks/Glog.qll

@@ -2,6 +2,7 @@
 
 import go
 
+/** Provides models of commonly used functions in the `github.com/golang/glog` package. */
 module Glog {
   private class GlogCall extends LoggerCall::Range, DataFlow::CallNode {
     GlogCall() {

ql/src/semmle/go/frameworks/Logrus.qll

@@ -2,6 +2,7 @@
 
 import go
 
+/** Provides models of commonly used functions in the `github.com/sirupsen/logrus` package. */
 module Logrus {
   private string getAPkgName() {
     result = "github.com/sirupsen/logrus"

ql/src/semmle/go/frameworks/SQL.qll

@@ -4,6 +4,7 @@
 
 import go
 
+/** Provides classes for working with SQL-related APIs. */
 module SQL {
   /**
    * A data-flow node whose string value is interpreted as (part of) a SQL query.
@@ -17,6 +18,7 @@ module SQL {
     QueryString() { this = self }
   }
 
+  /** Provides classes for working with SQL query strings. */
   module QueryString {
     /**
      * A data-flow node whose string value is interpreted as (part of) a SQL query.

ql/src/semmle/go/frameworks/Stdlib.qll

@@ -447,6 +447,7 @@ module URL {
   }
 }
 
+/** Provides models of commonly used APIs in the `regexp` package. */
 module Regexp {
   private class Pattern extends RegexpPattern::Range, DataFlow::ArgumentNode {
     string fnName;

ql/src/semmle/go/security/AllocationSizeOverflow.qll

@@ -7,6 +7,9 @@
 
 import go
 
+/**
+ * Provides a taint-tracking configuration for reasoning about allocation-size overflow.
+ */
 module AllocationSizeOverflow {
   import AllocationSizeOverflowCustomizations::AllocationSizeOverflow
 

ql/src/semmle/go/security/AllocationSizeOverflowCustomizations.qll

@@ -5,6 +5,10 @@
 
 import go
 
+/**
+ * Provides extension points for customizing the taint-tracking configuration for reasoning
+ * about allocation-size overflow.
+ */
 module AllocationSizeOverflow {
   /**
    * A source of data that might cause an allocation-size overflow.

ql/src/semmle/go/security/CleartextLogging.qll

@@ -9,6 +9,10 @@
 
 import go
 
+/**
+ * Provides a data-flow tracking configuration for reasoning about
+ * clear-text logging of sensitive information.
+ */
 module CleartextLogging {
   import CleartextLoggingCustomizations::CleartextLogging
 

ql/src/semmle/go/security/CleartextLoggingCustomizations.qll

@@ -7,6 +7,10 @@
 import go
 private import semmle.go.security.SensitiveActions::HeuristicNames
 
+/**
+ * Provides extension points for customizing the data-flow tracking configuration for reasoning
+ * about clear-text logging of sensitive information.
+ */
 module CleartextLogging {
   /**
    * A data-flow source for clear-text logging of sensitive information.

ql/src/semmle/go/security/CommandInjection.qll

@@ -1,6 +1,6 @@
 /**
  * Provides a taint tracking configuration for reasoning about command
- * injection vulnerabilities
+ * injection vulnerabilities.
  *
  * Note, for performance reasons: only import this file if
  * `CommandInjection::Configuration` is needed, otherwise
@@ -9,6 +9,10 @@
 
 import go
 
+/**
+ * Provides a taint tracking configuration for reasoning about command
+ * injection vulnerabilities.
+ */
 module CommandInjection {
   import CommandInjectionCustomizations::CommandInjection
 
@@ -27,6 +31,8 @@ module CommandInjection {
       node instanceof Sanitizer
     }
 
-    override predicate isSanitizerGuard(DataFlow::BarrierGuard guard) { guard instanceof SanitizerGuard }
+    override predicate isSanitizerGuard(DataFlow::BarrierGuard guard) {
+      guard instanceof SanitizerGuard
+    }
   }
 }

ql/src/semmle/go/security/CommandInjectionCustomizations.qll

@@ -6,6 +6,10 @@
 
 import go
 
+/**
+ * Provides extension points for customizing the taint tracking configuration for reasoning about
+ * command injection vulnerabilities.
+ */
 module CommandInjection {
   /**
    * A data flow source for command-injection vulnerabilities.

ql/src/semmle/go/security/FlowSources.qll

@@ -16,6 +16,7 @@ class UntrustedFlowSource extends DataFlow::Node {
   UntrustedFlowSource() { this = self }
 }
 
+/** Provides a class for modeling new sources of untrusted data. */
 module UntrustedFlowSource {
   /**
    * A source of data that is controlled by an untrusted user.

ql/src/semmle/go/security/OpenUrlRedirect.qll

@@ -10,6 +10,10 @@
 import go
 import UrlConcatenation
 
+/**
+ * Provides a taint-tracking configuration for reasoning about
+ * unvalidated URL redirection problems on the server side.
+ */
 module OpenUrlRedirect {
   import OpenUrlRedirectCustomizations::OpenUrlRedirect
 

ql/src/semmle/go/security/OpenUrlRedirectCustomizations.qll

@@ -7,6 +7,10 @@
 import go
 import UrlConcatenation
 
+/**
+ * Provides extension points for customizing the taint-tracking configuration for reasoning about
+ * unvalidated URL redirection problems on the server side.
+ */
 module OpenUrlRedirect {
   /**
    * A data flow source for unvalidated URL redirect vulnerabilities.

ql/src/semmle/go/security/ReflectedXss.qll

@@ -1,10 +1,18 @@
 /**
  * Provides a taint-tracking configuration for reasoning about reflected
  * cross-site scripting vulnerabilities.
+ *
+ * Note, for performance reasons: only import this file if
+ * `ReflectedXss::Configuration` is needed, otherwise
+ * `ReflectedXssCustomizations` should be imported instead.
  */
 
 import go
 
+/**
+ * Provides a taint-tracking configuration for reasoning about reflected
+ * cross-site scripting vulnerabilities.
+ */
 module ReflectedXss {
   import ReflectedXssCustomizations::ReflectedXss
 
@@ -23,6 +31,8 @@ module ReflectedXss {
       node instanceof Sanitizer
     }
 
-    override predicate isSanitizerGuard(DataFlow::BarrierGuard guard) { guard instanceof SanitizerGuard }
+    override predicate isSanitizerGuard(DataFlow::BarrierGuard guard) {
+      guard instanceof SanitizerGuard
+    }
   }
 }

ql/src/semmle/go/security/ReflectedXssCustomizations.qll

@@ -4,7 +4,10 @@
 
 import go
 
-/** Provides classes and predicates for the reflected XSS query. */
+/**
+ * Provides extension points for customizing the taint-tracking configuration for reasoning about
+ * reflected cross-site scripting vulnerabilities.
+ */
 module ReflectedXss {
   /** A data flow source for reflected XSS vulnerabilities. */
   abstract class Source extends DataFlow::Node { }

ql/src/semmle/go/security/SensitiveActions.qll

@@ -27,9 +27,7 @@ module HeuristicNames {
    * Gets a regular expression that identifies strings that may indicate the presence of
    * user names or other account information.
    */
-  string maybeAccountInfo() {
-    result = "(?is).*(puid|username|userid).*"
-  }
+  string maybeAccountInfo() { result = "(?is).*(puid|username|userid).*" }
 
   /**
    * Gets a regular expression that identifies strings that may indicate the presence of
@@ -72,6 +70,7 @@ abstract class SensitiveExpr extends Expr {
   abstract SensitiveExpr::Classification getClassification();
 }
 
+/** Provides classes and predicates for classifying different kinds of sensitive data. */
 module SensitiveExpr {
   /**
    * A classification of different kinds of sensitive data:

ql/src/semmle/go/security/SqlInjection.qll

@@ -7,6 +7,9 @@
 
 import go
 
+/**
+ * Provides a taint tracking configuration for reasoning about SQL-injection vulnerabilities.
+ */
 module SqlInjection {
   import SqlInjectionCustomizations::SqlInjection
 
@@ -25,6 +28,8 @@ module SqlInjection {
       node instanceof Sanitizer
     }
 
-    override predicate isSanitizerGuard(DataFlow::BarrierGuard guard) { guard instanceof SanitizerGuard }
+    override predicate isSanitizerGuard(DataFlow::BarrierGuard guard) {
+      guard instanceof SanitizerGuard
+    }
   }
 }

ql/src/semmle/go/security/SqlInjectionCustomizations.qll

@@ -5,6 +5,10 @@
 
 import go
 
+/**
+ * Provides extension points for customizing the taint tracking configuration for reasoning about
+ * SQL-injection vulnerabilities.
+ */
 module SqlInjection {
   /**
    * A data flow source for SQL-injection vulnerabilities.

ql/src/semmle/go/security/StringBreak.qll

@@ -7,6 +7,9 @@
 
 import go
 
+/**
+ * Provides a taint tracking configuration for reasoning about unsafe-quoting vulnerabilities.
+ */
 module StringBreak {
   import StringBreakCustomizations::StringBreak
 

ql/src/semmle/go/security/StringBreakCustomizations.qll

@@ -5,6 +5,10 @@
 
 import go
 
+/**
+ * Provides extension points for customizing the taint tracking configuration for reasoning about
+ * unsafe-quoting vulnerabilities.
+ */
 module StringBreak {
   /** A (single or double) quote. */
   class Quote extends string {

ql/src/semmle/go/security/TaintedPath.qll

@@ -1,5 +1,5 @@
 /**
- * Provides a taint tracking configuration for reasoning about path-traversal vulnerabilities
+ * Provides a taint tracking configuration for reasoning about path-traversal vulnerabilities.
  *
  * Note: for performance reasons, only import this file if `TaintedPath::Configuration` is needed,
  * otherwise `TaintedPathCustomizations` should be imported instead.
@@ -7,6 +7,7 @@
 
 import go
 
+/** Provides a taint tracking configuration for reasoning about path-traversal vulnerabilities. */
 module TaintedPath {
   import TaintedPathCustomizations::TaintedPath
 
@@ -25,6 +26,8 @@ module TaintedPath {
       node instanceof Sanitizer
     }
 
-    override predicate isSanitizerGuard(DataFlow::BarrierGuard guard) { guard instanceof SanitizerGuard }
+    override predicate isSanitizerGuard(DataFlow::BarrierGuard guard) {
+      guard instanceof SanitizerGuard
+    }
   }
 }

ql/src/semmle/go/security/TaintedPathCustomizations.qll

@@ -5,6 +5,10 @@
 
 import go
 
+/**
+ * Provides extension points for customizing the taint tracking configuration for reasoning about
+ * path-traversal vulnerabilities.
+ */
 module TaintedPath {
   /**
    * A data flow source for path-traversal vulnerabilities.

ql/src/semmle/go/security/ZipSlip.qll

@@ -1,5 +1,5 @@
 /**
- * Provides a taint tracking configuration for reasoning about zip-slip vulnerabilities
+ * Provides a taint tracking configuration for reasoning about zip-slip vulnerabilities.
  *
  * Note: for performance reasons, only import this file if `ZipSlip::Configuration` is needed,
  * otherwise `ZipSlipCustomizations` should be imported instead.
@@ -7,6 +7,7 @@
 
 import go
 
+/** Provides a taint tracking configuration for reasoning about zip-slip vulnerabilities. */
 module ZipSlip {
   import ZipSlipCustomizations::ZipSlip
 
@@ -25,6 +26,8 @@ module ZipSlip {
       node instanceof Sanitizer
     }
 
-    override predicate isSanitizerGuard(DataFlow::BarrierGuard guard) { guard instanceof SanitizerGuard }
+    override predicate isSanitizerGuard(DataFlow::BarrierGuard guard) {
+      guard instanceof SanitizerGuard
+    }
   }
 }

ql/src/semmle/go/security/ZipSlipCustomizations.qll

@@ -5,6 +5,10 @@
 
 import go
 
+/**
+ * Provides extension points for customizing the taint tracking configuration for reasoning about
+ * zip-slip vulnerabilities.
+ */
 module ZipSlip {
   private import TaintedPathCustomizations