JS: review fixups in documentation and comments

Author: Esben Sparre Andreasen

change-notes/1.18/analysis-javascript.md

@@ -28,7 +28,7 @@
 
 | **Query**                   | **Tags**  | **Purpose**                                                        |
 |-----------------------------|-----------|--------------------------------------------------------------------|
-| Clear text logging of sensitive information (`js/cleartext-logging`) | security, external/cwe/cwe-312, external/cwe/cwe-315, external/cwe/cwe-359 | Highlights logging of sensitive information, indicating a violation of [CWE-312](https://cwe.mitre.org/data/definitions/312.html). Results shown on lgtm by default. |
+| Clear-text logging of sensitive information (`js/clear-text-logging`) | security, external/cwe/cwe-312, external/cwe/cwe-315, external/cwe/cwe-359 | Highlights logging of sensitive information, indicating a violation of [CWE-312](https://cwe.mitre.org/data/definitions/312.html). Results shown on LGTM by default. |
 | Disabling Electron webSecurity (`js/disabling-electron-websecurity`) | security, frameworks/electron | Highlights Electron browser objects that are created with the `webSecurity` property set to false. Results shown on LGTM by default. |
 | Enabling Electron allowRunningInsecureContent (`js/enabling-electron-insecure-content`) | security, frameworks/electron | Highlights Electron browser objects that are created with the `allowRunningInsecureContent` property set to true. Results shown on LGTM by default. |
 | Use of externally-controlled format string (`js/tainted-format-string`) | security, external/cwe/cwe-134 | Highlights format strings containing user-provided data, indicating a violation of [CWE-134](https://cwe.mitre.org/data/definitions/134.html). Results shown on LGTM by default. |

javascript/ql/src/Security/CWE-312/CleartextLogging.ql

@@ -1,11 +1,11 @@
 /**
- * @name Clear text logging of sensitive information
- * @description Sensitive information logged without encryption or hashing can expose it to an
- *              attacker.
+ * @name Clear-text logging of sensitive information
+ * @description Logging sensitive information without encryption or hashing can
+ *              expose it to an attacker.
  * @kind problem
  * @problem.severity error
  * @precision high
- * @id js/cleartext-logging
+ * @id js/clear-text-logging
  * @tags security
  *       external/cwe/cwe-312
  *       external/cwe/cwe-315

javascript/ql/src/Security/CWE-312/CleartextStorage.qhelp

@@ -15,7 +15,7 @@ which are stored on the machine of the end-user.
 <p>
 Ensure that sensitive information is always encrypted before being stored.
 If possible, avoid placing sensitive information in cookies altogether.
-Instead, prefer storing, in the cookie, a key that can be used to lookup the
+Instead, prefer storing, in the cookie, a key that can be used to look up the
 sensitive information.
 </p>
 <p>

javascript/ql/src/semmle/javascript/frameworks/Logging.qll

@@ -16,8 +16,10 @@ abstract class LoggerCall extends DataFlow::CallNode {
 
 }
 
+/**
+ * Gets a log level name that is used in RFC5424, `npm`, `console`.
+ */
 private string getAStandardLoggerMethodName() {
-  // log level names used in RFC5424, `npm`, `console`
   result = "crit" or
   result = "debug" or
   result = "error" or
@@ -32,7 +34,7 @@ private string getAStandardLoggerMethodName() {
 }
 
 /**
- * Provides classes for working the builtin NodeJS/Browser `console`.
+ * Provides classes for working the builtin Node.js/Browser `console`.
  */
 private module Console {
 

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

@@ -22,6 +22,7 @@ module HeuristicNames {
   string suspiciousNonPassword() {
     result = "(?is).*(secret|account|accnt|(?<!un)trusted).*"
   }
+
   /** A regular expression that identifies strings that look like they represent secret data that are passwords. */
   string suspiciousPassword() {
     result = "(?is).*(password|passwd).*"

javascript/ql/src/semmle/javascript/security/dataflow/CleartextLogging.qll

@@ -1,35 +1,35 @@
 /**
- * Provides a dataflow tracking configuration for reasoning about cleartext logging of sensitive information.
+ * Provides a dataflow tracking configuration for reasoning about clear-text logging of sensitive information.
  */
 import javascript
 private import semmle.javascript.dataflow.InferredTypes
 private import semmle.javascript.security.SensitiveActions::HeuristicNames
 
 module CleartextLogging {
   /**
-   * A data flow source for cleartext logging of sensitive information.
+   * A data flow source for clear-text logging of sensitive information.
    */
   abstract class Source extends DataFlow::Node {
     /** Gets a string that describes the type of this data flow source. */
     abstract string describe();
   }
 
   /**
-   * A data flow sink for cleartext logging of sensitive information.
+   * A data flow sink for clear-text logging of sensitive information.
    */
   abstract class Sink extends DataFlow::Node { }
 
   /**
-   * A barrier for cleartext logging of sensitive information.
+   * A barrier for clear-text logging of sensitive information.
    */
   abstract class Barrier extends DataFlow::Node { }
 
   /**
-   * A dataflow tracking configuration for cleartext logging of sensitive information.
+   * A dataflow tracking configuration for clear-text logging of sensitive information.
    *
    * This configuration identifies flows from `Source`s, which are sources of
    * sensitive data, to `Sink`s, which is an abstract class representing all
-   * the places sensitive data may be stored in cleartext. Additional sources or sinks can be
+   * the places sensitive data may be stored in clear-text. Additional sources or sinks can be
    * added either by extending the relevant class, or by subclassing this configuration itself,
    * and amending the sources and sinks.
    */
@@ -95,7 +95,7 @@ module CleartextLogging {
   }
 
   /**
-   * A data flow node that does not contain a clear text password, according to its syntactic name.
+   * A data flow node that does not contain a clear-text password, according to its syntactic name.
    */
   private class NameGuidedNonCleartextPassword extends NonCleartextPassword {
 
@@ -129,7 +129,7 @@ module CleartextLogging {
   }
 
   /**
-   * A data flow node that receives flow that is not a clear text password.
+   * A data flow node that receives flow that is not a clear-text password.
    */
   private class NonCleartextPasswordFlow extends NonCleartextPassword {
 
@@ -151,14 +151,14 @@ module CleartextLogging {
   }
 
   /**
-   * A data flow node that does not contain a clear text password.
+   * A data flow node that does not contain a clear-text password.
    */
   private abstract class NonCleartextPassword extends DataFlow::Node { }
 
   /**
    * An object with a property that may contain password information
    *
-   * This is a source since `toString()` on this object will show the property value.
+   * This is a source since `console.log(obj)` will show the properties of `obj`.
    */
   private class ObjectPasswordPropertySource extends DataFlow::ValueNode, Source {
     string name;