apply changes based on docs review

Author: erik-krogh

java/ql/src/Security/CWE/CWE-020/OverlyLargeRange.qhelp

@@ -5,34 +5,32 @@
 
     <overview>
         <p>
-            A regexp range can by accident match more than was intended.
-            For example, the regular expression <code>/[a-zA-z]/</code> will 
-            match every lowercase and uppercase letters, but the same regular 
-            expression will also match the chars: <code>[\]^_`</code>.  
+            It's easy to write a regular expression range that matches a wider range of characters than you intended.
+            For example, <code>/[a-zA-z]/</code> matches all lowercase and all uppercase letters,
+            as you would expect, but it also matches the characters: <code>[ \ ] ^ _ `</code>.  
         </p>
         <p>
-            On other occasions it can happen that the dash in a regular 
-            expression is not escaped, which will cause it to be interpreted 
-            as part of a range. For example in the character class <code>[a-zA-Z0-9%=.,-_]</code> 
+            Another common problem is failing to escape the dash character in a regular 
+            expression. An unescaped dash is interpreted 
+            as part of a range. For example, in the character class <code>[a-zA-Z0-9%=.,-_]</code> 
             the last character range matches the 55 characters between 
             <code>,</code> and <code>_</code> (both included), which overlaps with the 
-            range <code>[0-9]</code> and is thus clearly not intended.
+            range <code>[0-9]</code> and is clearly not intended by the writer.
         </p>
     </overview>
 
     <recommendation>
         <p>
-
-            Don't write character ranges were there might be confusion as to
-            which characters are included in the range.
-
+            Avoid any confusion about which characters are included in the range by 
+            writing unambiguous regular expressions.
+            Always check that character ranges match only the expected characters.
         </p>
     </recommendation>
 
     <example>
 
         <p>
-            The following example code checks whether a string is a valid 6 digit hex color. 
+            The following example code is intended to check whether a string is a valid 6 digit hex color. 
         </p>
 
 <sample language="java">
@@ -45,8 +43,8 @@ public class Tester {
 </sample>
 
         <p>
-            However, the <code>A-f</code> range matches every uppercase character, and
-            thus a "color" like <code>#XYZ</code> is considered valid.
+            However, the <code>A-f</code> range is overly large and matches every uppercase character. 
+            It would parse a "color" like <code>#XXYYZZ</code> as valid.
         </p>
 
         <p>
@@ -65,10 +63,9 @@ public class Tester {
     </example>
 
     <references>
-        <li>Mitre.org: <a href="https://cwe.mitre.org/data/definitions/20.html">CWE-020</a></li>
-        <li>github.com: <a href="https://github.com/advisories/GHSA-g4rg-993r-mgx7">CVE-2021-42740</a></li>
+        <li>GitHub Advisory Database: <a href="https://github.com/advisories/GHSA-g4rg-993r-mgx7">CVE-2021-42740: Improper Neutralization of Special Elements used in a Command in Shell-quote</a></li>
         <li>wh0.github.io: <a href="https://wh0.github.io/2021/10/28/shell-quote-rce-exploiting.html">Exploiting CVE-2021-42740</a></li>
-        <li>ota-meshi.github.io: <a href="https://ota-meshi.github.io/eslint-plugin-regexp/rules/no-obscure-range.html">no-obscure-range</a></li>
-        <li>pboyd.io: <a href="https://pboyd.io/posts/comma-dash-dot/">The regex [,-.]</a></li>
+        <li>Yosuke Ota: <a href="https://ota-meshi.github.io/eslint-plugin-regexp/rules/no-obscure-range.html">no-obscure-range</a></li>
+        <li>Paul Boyd: <a href="https://pboyd.io/posts/comma-dash-dot/">The regex [,-.]</a></li>
     </references>
 </qhelp>

java/ql/src/Security/CWE/CWE-020/OverlyLargeRange.ql

@@ -1,6 +1,6 @@
 /**
- * @name Overly large regular expression range
- * @description Overly permissive regular expression ranges may cause regular expressions to match more than anticipated.
+ * @name Overly permissive regular expression range
+ * @description Overly permissive regular expression ranges match a wider range of characters than intended.
  *              This may allow an attacker to bypass a filter or sanitizer.
  * @kind problem
  * @problem.severity warning

javascript/ql/src/Security/CWE-020/OverlyLargeRange.qhelp

@@ -5,34 +5,32 @@
 
     <overview>
         <p>
-            A regexp range can by accident match more than was intended.
-            For example, the regular expression <code>/[a-zA-z]/</code> will 
-            match every lowercase and uppercase letters, but the same regular 
-            expression will also match the chars: <code>[\]^_`</code>.  
+            It's easy to write a regular expression range that matches a wider range of characters than you intended.
+            For example, <code>/[a-zA-z]/</code> matches all lowercase and all uppercase letters,
+            as you would expect, but it also matches the characters: <code>[ \ ] ^ _ `</code>.  
         </p>
         <p>
-            On other occasions it can happen that the dash in a regular 
-            expression is not escaped, which will cause it to be interpreted 
-            as part of a range. For example in the character class <code>[a-zA-Z0-9%=.,-_]</code> 
+            Another common problem is failing to escape the dash character in a regular 
+            expression. An unescaped dash is interpreted 
+            as part of a range. For example, in the character class <code>[a-zA-Z0-9%=.,-_]</code> 
             the last character range matches the 55 characters between 
             <code>,</code> and <code>_</code> (both included), which overlaps with the 
-            range <code>[0-9]</code> and is thus clearly not intended.
+            range <code>[0-9]</code> and is clearly not intended by the writer.
         </p>
     </overview>
 
     <recommendation>
         <p>
-
-            Don't write character ranges were there might be confusion as to
-            which characters are included in the range.
-
+            Avoid any confusion about which characters are included in the range by 
+            writing unambiguous regular expressions.
+            Always check that character ranges match only the expected characters.
         </p>
     </recommendation>
 
     <example>
 
         <p>
-            The following example code checks whether a string is a valid 6 digit hex color. 
+            The following example code is intended to check whether a string is a valid 6 digit hex color. 
         </p>
 
 <sample language="javascript">
@@ -42,8 +40,8 @@ function isValidHexColor(color) {
 </sample>
 
         <p>
-            However, the <code>A-f</code> range matches every uppercase character, and
-            thus a "color" like <code>#XYZ</code> is considered valid.
+            However, the <code>A-f</code> range is overly large and matches every uppercase character. 
+            It would parse a "color" like <code>#XXYYZZ</code> as valid.
         </p>
 
         <p>
@@ -59,10 +57,9 @@ function isValidHexColor(color) {
     </example>
 
     <references>
-        <li>Mitre.org: <a href="https://cwe.mitre.org/data/definitions/20.html">CWE-020</a></li>
-        <li>github.com: <a href="https://github.com/advisories/GHSA-g4rg-993r-mgx7">CVE-2021-42740</a></li>
+        <li>GitHub Advisory Database: <a href="https://github.com/advisories/GHSA-g4rg-993r-mgx7">CVE-2021-42740: Improper Neutralization of Special Elements used in a Command in Shell-quote</a></li>
         <li>wh0.github.io: <a href="https://wh0.github.io/2021/10/28/shell-quote-rce-exploiting.html">Exploiting CVE-2021-42740</a></li>
-        <li>ota-meshi.github.io: <a href="https://ota-meshi.github.io/eslint-plugin-regexp/rules/no-obscure-range.html">no-obscure-range</a></li>
-        <li>pboyd.io: <a href="https://pboyd.io/posts/comma-dash-dot/">The regex [,-.]</a></li>
+        <li>Yosuke Ota: <a href="https://ota-meshi.github.io/eslint-plugin-regexp/rules/no-obscure-range.html">no-obscure-range</a></li>
+        <li>Paul Boyd: <a href="https://pboyd.io/posts/comma-dash-dot/">The regex [,-.]</a></li>
     </references>
 </qhelp>

javascript/ql/src/Security/CWE-020/OverlyLargeRange.ql

@@ -1,6 +1,6 @@
 /**
- * @name Overly large regular expression range
- * @description Overly permissive regular expression ranges may cause regular expressions to match more than anticipated.
+ * @name Overly permissive regular expression range
+ * @description Overly permissive regular expression ranges match a wider range of characters than intended.
  *              This may allow an attacker to bypass a filter or sanitizer.
  * @kind problem
  * @problem.severity warning

python/ql/src/Security/CWE-020/OverlyLargeRange.qhelp

@@ -5,34 +5,32 @@
 
     <overview>
         <p>
-            A regexp range can by accident match more than was intended.
-            For example, the regular expression <code>/[a-zA-z]/</code> will 
-            match every lowercase and uppercase letters, but the same regular 
-            expression will also match the chars: <code>[\]^_`</code>.  
+            It's easy to write a regular expression range that matches a wider range of characters than you intended.
+            For example, <code>/[a-zA-z]/</code> matches all lowercase and all uppercase letters,
+            as you would expect, but it also matches the characters: <code>[ \ ] ^ _ `</code>.  
         </p>
         <p>
-            On other occasions it can happen that the dash in a regular 
-            expression is not escaped, which will cause it to be interpreted 
-            as part of a range. For example in the character class <code>[a-zA-Z0-9%=.,-_]</code> 
+            Another common problem is failing to escape the dash character in a regular 
+            expression. An unescaped dash is interpreted 
+            as part of a range. For example, in the character class <code>[a-zA-Z0-9%=.,-_]</code> 
             the last character range matches the 55 characters between 
             <code>,</code> and <code>_</code> (both included), which overlaps with the 
-            range <code>[0-9]</code> and is thus clearly not intended.
+            range <code>[0-9]</code> and is clearly not intended by the writer.
         </p>
     </overview>
 
     <recommendation>
         <p>
-
-            Don't write character ranges were there might be confusion as to
-            which characters are included in the range.
-
+            Avoid any confusion about which characters are included in the range by 
+            writing unambiguous regular expressions.
+            Always check that character ranges match only the expected characters.
         </p>
     </recommendation>
 
     <example>
 
         <p>
-            The following example code checks whether a string is a valid 6 digit hex color. 
+            The following example code is intended to check whether a string is a valid 6 digit hex color. 
         </p>
 
 <sample language="python">
@@ -42,8 +40,8 @@ def is_valid_hex_color(color):
 </sample>
 
         <p>
-            However, the <code>A-f</code> range matches every uppercase character, and
-            thus a "color" like <code>#XYZ</code> is considered valid.
+            However, the <code>A-f</code> range is overly large and matches every uppercase character. 
+            It would parse a "color" like <code>#XXYYZZ</code> as valid.
         </p>
 
         <p>
@@ -59,10 +57,9 @@ def is_valid_hex_color(color):
     </example>
 
     <references>
-        <li>Mitre.org: <a href="https://cwe.mitre.org/data/definitions/20.html">CWE-020</a></li>
-        <li>github.com: <a href="https://github.com/advisories/GHSA-g4rg-993r-mgx7">CVE-2021-42740</a></li>
+        <li>GitHub Advisory Database: <a href="https://github.com/advisories/GHSA-g4rg-993r-mgx7">CVE-2021-42740: Improper Neutralization of Special Elements used in a Command in Shell-quote</a></li>
         <li>wh0.github.io: <a href="https://wh0.github.io/2021/10/28/shell-quote-rce-exploiting.html">Exploiting CVE-2021-42740</a></li>
-        <li>ota-meshi.github.io: <a href="https://ota-meshi.github.io/eslint-plugin-regexp/rules/no-obscure-range.html">no-obscure-range</a></li>
-        <li>pboyd.io: <a href="https://pboyd.io/posts/comma-dash-dot/">The regex [,-.]</a></li>
+        <li>Yosuke Ota: <a href="https://ota-meshi.github.io/eslint-plugin-regexp/rules/no-obscure-range.html">no-obscure-range</a></li>
+        <li>Paul Boyd: <a href="https://pboyd.io/posts/comma-dash-dot/">The regex [,-.]</a></li>
     </references>
 </qhelp>

python/ql/src/Security/CWE-020/OverlyLargeRange.ql

@@ -1,6 +1,6 @@
 /**
- * @name Overly large regular expression range
- * @description Overly permissive regular expression ranges may cause regular expressions to match more than anticipated.
+ * @name Overly permissive regular expression range
+ * @description Overly permissive regular expression ranges match a wider range of characters than intended.
  *              This may allow an attacker to bypass a filter or sanitizer.
  * @kind problem
  * @problem.severity warning

ruby/ql/src/queries/security/cwe-020/OverlyLargeRange.qhelp

@@ -5,34 +5,32 @@
 
     <overview>
         <p>
-            A regexp range can by accident match more than was intended.
-            For example, the regular expression <code>/[a-zA-z]/</code> will 
-            match every lowercase and uppercase letters, but the same regular 
-            expression will also match the chars: <code>[\]^_`</code>.  
+            It's easy to write a regular expression range that matches a wider range of characters than you intended.
+            For example, <code>/[a-zA-z]/</code> matches all lowercase and all uppercase letters,
+            as you would expect, but it also matches the characters: <code>[ \ ] ^ _ `</code>.  
         </p>
         <p>
-            On other occasions it can happen that the dash in a regular 
-            expression is not escaped, which will cause it to be interpreted 
-            as part of a range. For example in the character class <code>[a-zA-Z0-9%=.,-_]</code> 
+            Another common problem is failing to escape the dash character in a regular 
+            expression. An unescaped dash is interpreted 
+            as part of a range. For example, in the character class <code>[a-zA-Z0-9%=.,-_]</code> 
             the last character range matches the 55 characters between 
             <code>,</code> and <code>_</code> (both included), which overlaps with the 
-            range <code>[0-9]</code> and is thus clearly not intended.
+            range <code>[0-9]</code> and is clearly not intended by the writer.
         </p>
     </overview>
 
     <recommendation>
         <p>
-
-            Don't write character ranges were there might be confusion as to
-            which characters are included in the range.
-
+            Avoid any confusion about which characters are included in the range by 
+            writing unambiguous regular expressions.
+            Always check that character ranges match only the expected characters.
         </p>
     </recommendation>
 
     <example>
 
         <p>
-            The following example code checks whether a string is a valid 6 digit hex color. 
+            The following example code is intended to check whether a string is a valid 6 digit hex color. 
         </p>
 
 <sample language="ruby">
@@ -42,8 +40,8 @@ end
 </sample>
 
         <p>
-            However, the <code>A-f</code> range matches every uppercase character, and
-            thus a "color" like <code>#XYZ</code> is considered valid.
+            However, the <code>A-f</code> range is overly large and matches every uppercase character. 
+            It would parse a "color" like <code>#XXYYZZ</code> as valid.
         </p>
 
         <p>
@@ -59,10 +57,9 @@ end
     </example>
 
     <references>
-        <li>Mitre.org: <a href="https://cwe.mitre.org/data/definitions/20.html">CWE-020</a></li>
-        <li>github.com: <a href="https://github.com/advisories/GHSA-g4rg-993r-mgx7">CVE-2021-42740</a></li>
+        <li>GitHub Advisory Database: <a href="https://github.com/advisories/GHSA-g4rg-993r-mgx7">CVE-2021-42740: Improper Neutralization of Special Elements used in a Command in Shell-quote</a></li>
         <li>wh0.github.io: <a href="https://wh0.github.io/2021/10/28/shell-quote-rce-exploiting.html">Exploiting CVE-2021-42740</a></li>
-        <li>ota-meshi.github.io: <a href="https://ota-meshi.github.io/eslint-plugin-regexp/rules/no-obscure-range.html">no-obscure-range</a></li>
-        <li>pboyd.io: <a href="https://pboyd.io/posts/comma-dash-dot/">The regex [,-.]</a></li>
+        <li>Yosuke Ota: <a href="https://ota-meshi.github.io/eslint-plugin-regexp/rules/no-obscure-range.html">no-obscure-range</a></li>
+        <li>Paul Boyd: <a href="https://pboyd.io/posts/comma-dash-dot/">The regex [,-.]</a></li>
     </references>
 </qhelp>

ruby/ql/src/queries/security/cwe-020/OverlyLargeRange.ql

@@ -1,6 +1,6 @@
 /**
- * @name Overly large regular expression range
- * @description Overly permissive regular expression ranges may cause regular expressions to match more than anticipated.
+ * @name Overly permissive regular expression range
+ * @description Overly permissive regular expression ranges match a wider range of characters than intended.
  *              This may allow an attacker to bypass a filter or sanitizer.
  * @kind problem
  * @problem.severity warning