Apply suggestions from code review

Co-authored-by: Felicity Chapman <[email protected]>

Author: lcartey

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

@@ -5,7 +5,7 @@
 <overview>
 <p>Using unsanitized untrusted data in an external API can cause a variety of security issues. This query reports 
 all external APIs that are used with untrusted data, along with how frequently the API is used, and how many 
-unique sources of untrusted data flow this API. This query is designed primarily to help identify which APIs 
+unique sources of untrusted data flow to this API. This query is designed primarily to help identify which APIs 
 may be relevant for security analysis of this application.</p>
 
 <p>An external API is defined as a method call to a method that is not defined in the source code, not overridden 
@@ -40,7 +40,7 @@ consider whether this is an XSS sink. If it is, we should confirm that it is han
 <p>If the query were to return the API <code>java.lang.StringBuilder.append(java.lang.String) [param 0]</code>, then this should be
 reviewed as a possible taint step, because tainted data would flow from the 0th argument to the qualifier of the call.</p>
 
-<p>Note that both examples are correctly handled with the standard taint tracking library and XSS query.</p>
+<p>Note that both examples are correctly handled by the standard taint tracking library and XSS query.</p>
 </example>
 <references>
 

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

@@ -5,6 +5,7 @@
  *              to it.
  * @id java/count-untrusted-data-external-api
  * @kind table
+ * @tags security external/cwe/cwe-20
  */
 
 import java

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

@@ -4,13 +4,11 @@
 <qhelp>
 <overview>
 <p>Using unsanitized untrusted data in an external API can cause a variety of security issues. This query reports 
-all uses of external APIs with untrusted data for review. This query has a deliberately low true positive rate, 
-and is designed to help security reviews for the application, as well as helping identify external APIs that 
-should be modeled as either taint steps, or sinks for specific problems.</p>
+external APIs that use untrusted data. The results are not filtered so that you can audit all examples. The query provides data for security reviews of the application and you can also use it to identify external APIs that should be modeled as either taint steps, or sinks for specific problems.</p>
 
 <p>An external API is defined as a method call to a method that is not defined in the source code, not overridden 
 in the source code, and is not modeled as a taint step in the default taint library. External APIs may be from the
-Java standard library, third party dependencies or from internal dependencies. The query will report uses of 
+Java standard library, third-party dependencies or from internal dependencies. The query reports uses of 
 untrusted data in either the qualifier or as one of the arguments of external APIs.</p>
 
 </overview>
@@ -20,10 +18,10 @@ untrusted data in either the qualifier or as one of the arguments of external AP
 
 <ul>
   <li>If the result highlights a known sink, confirm that the result is reported by the relevant query, or 
-  that the result is a false positive due to sanitization.</li>
+  that the result is a false positive because this data is sanitized.</li>
   <li>If the result highlights an unknown sink for a problem, then add modeling for the sink to the relevant query, 
   and confirm that the result is either found, or is safe due to appropriate sanitization.</li>
-  <li>If the result represents a call to an external API which transfers taint, add the appropriate modeling, and 
+  <li>If the result represents a call to an external API that transfers taint, add the appropriate modeling, and 
   re-run the query to determine what new results have appeared due to this additional modeling.</li>
 </ul>
 
@@ -39,19 +37,19 @@ class to exclude known safe external APIs from future analysis.</p>
 <sample src="ExternalAPISinkExample.java" />
 
 <p>This is an XSS sink. The XSS query should therefore be reviewed to confirm that this sink is appropriately modeled, 
-and if it is, to confirm that the query reports this particular result, or that the result is false positive due to 
+and if it is, to confirm that the query reports this particular result, or that the result is a false positive due to 
 some existing sanitization.</p>
 
 <p>In this second example, again a request parameter is read from <code>HttpServletRequest</code>.</p>
 
 <sample src="ExternalAPITaintStepExample.java" />
 
 <p>If the query reported the call to <code>StringBuilder.append</code> on line 7, this would suggest that this external API is 
-not currently modeled as a taint step in the taint tracking library. The next step would be to model this as taint step, then
+not currently modeled as a taint step in the taint tracking library. The next step would be to model this as a taint step, then
 re-run the query to determine what additional results might be found. In this example, it seems likely that the result of the
 <code>StringBuilder</code> will be executed as an SQL query, potentially leading to an SQL injection vulnerability.</p>
 
-<p>Note that both examples are correctly handled with the standard taint tracking library and XSS query.</p>
+<p>Note that both examples are correctly handled by the standard taint tracking library and XSS query.</p>
 </example>
 <references>
 

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

@@ -1,6 +1,6 @@
 /**
  * @name Untrusted data passed to external API
- * @description Data provided remotely is used in this external API.
+ * @description Data provided remotely is used in this external API without sanitization, which could be a security risk.
  * @id java/untrusted-data-to-external-api
  * @kind path-problem
  * @precision very-low