Update qldoc

Author: luchua-bc

java/ql/src/experimental/Security/CWE/CWE-598/SensitiveGetQuery.ql

@@ -13,12 +13,12 @@ import semmle.code.java.dataflow.TaintTracking
 import semmle.code.java.security.SensitiveActions
 import DataFlow::PathGraph
 
-/** Finds variables that hold sensitive information judging by their names. */
+/** A variable that holds sensitive information judging by its name. */
 class SensitiveInfoExpr extends Expr {
   SensitiveInfoExpr() {
     exists(Variable v | this = v.getAnAccess() |
       v.getName().regexpMatch(getCommonSensitiveInfoRegex()) and
-      not v.getName().regexpMatch("token.*") // exclude ^token$ and ^token.* since sensitive tokens are in the form of accessToken, authToken, ...
+      not v.getName().regexpMatch("token.*") // exclude ^token.* since sensitive tokens are usually in the form of accessToken, authToken, ...
     )
   }
 }
@@ -31,14 +31,14 @@ class DoGetServletMethod extends Method {
   DoGetServletMethod() { isGetServletMethod(this) }
 }
 
-/** Holds if `ma` is called from the `doGet` method of `HttpServlet`. */
-predicate isServletGetCall(MethodAccess ma) {
+/** Holds if `ma` is (perhaps indirectly) called from the `doGet` method of `HttpServlet`. */
+predicate isReachableFromServletDoGet(MethodAccess ma) {
   ma.getEnclosingCallable() instanceof DoGetServletMethod
   or
   exists(Method pm, MethodAccess pma |
     ma.getEnclosingCallable() = pm and
     pma.getMethod() = pm and
-    isServletGetCall(pma)
+    isReachableFromServletDoGet(pma)
   )
 }
 
@@ -48,12 +48,12 @@ class RequestGetParamSource extends DataFlow::ExprNode {
     exists(MethodAccess ma |
       isRequestGetParamMethod(ma) and
       ma = this.asExpr() and
-      isServletGetCall(ma)
+      isReachableFromServletDoGet(ma)
     )
   }
 }
 
-/** Taint configuration tracking flow from the `ServletRequest` of a GET request handler to an expression whose name suggests it holds security-sensitive data. */
+/** A taint configuration tracking flow from the `ServletRequest` of a GET request handler to an expression whose name suggests it holds security-sensitive data. */
 class SensitiveGetQueryConfiguration extends TaintTracking::Configuration {
   SensitiveGetQueryConfiguration() { this = "SensitiveGetQueryConfiguration" }
 

java/ql/test/experimental/query-tests/security/CWE-598/SensitiveGetQuery.java

@@ -6,7 +6,7 @@
 import javax.servlet.ServletException;
 
 public class SensitiveGetQuery extends HttpServlet {
-	// BAD - Tests sending sensitive information in a GET request.
+	// BAD - Tests retrieving sensitive information through `request.getParameter()` in a GET request.
 	public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException {
 		String username = request.getParameter("username");
 		String password = request.getParameter("password");
@@ -18,7 +18,7 @@ void processUserInfo(String username, String password) {
 		System.out.println("username = " + username+"; password "+password);
 	}
 
-	// GOOD - Tests sending sensitive information in a POST request.
+	// GOOD - Tests retrieving sensitive information through `request.getParameter()` in a POST request.
 	public void doPost(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException {
 		String password = request.getParameter("password");
 		System.out.println("password = " + password);

java/ql/test/experimental/query-tests/security/CWE-598/SensitiveGetQuery2.java

@@ -7,7 +7,7 @@
 import javax.servlet.ServletException;
 
 public class SensitiveGetQuery2 extends HttpServlet {
-	// BAD - Tests sending sensitive information in a GET request.
+	// BAD - Tests retrieving sensitive information through `request.getParameterMap()` in a GET request.
 	public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException {
 		Map map = request.getParameterMap();
 		String username = (String) map.get("username");
@@ -19,7 +19,7 @@ void processUserInfo(String username, String password) {
 		System.out.println("username = " + username+"; password "+password);
 	}
 
-	// GOOD - Tests sending sensitive information in a POST request.
+	// GOOD - Tests retrieving sensitive information through `request.getParameterMap()` in a POST request.
 	public void doPost(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException {
 		Map map = request.getParameterMap();
 		String username = (String) map.get("username");

java/ql/test/experimental/query-tests/security/CWE-598/SensitiveGetQuery3.java

@@ -6,7 +6,7 @@
 import javax.servlet.ServletException;
 
 public class SensitiveGetQuery3 extends HttpServlet {
-	// BAD - Tests sending sensitive information in a GET request.
+	// BAD - Tests retrieving sensitive information through a wrapper call in a GET request.
 	public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException {
 		String username = getRequestParameter(request, "username");
 		String password = getRequestParameter(request, "password");
@@ -17,7 +17,7 @@ String getRequestParameter(HttpServletRequest request, String paramName) {
 		return request.getParameter(paramName);
 	}
 
-	// GOOD - Tests sending sensitive information in a POST request.
+	// GOOD - Tests retrieving sensitive information through a wrapper call in a POST request.
 	public void doPost(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException {
 		String username = getRequestParameter(request, "username");
 		String password = getRequestParameter(request, "password");

java/ql/test/experimental/query-tests/security/CWE-598/SensitiveGetQuery4.java

@@ -6,7 +6,7 @@
 import javax.servlet.ServletException;
 
 public class SensitiveGetQuery4 extends HttpServlet {
-	// BAD - Tests sending sensitive information in a GET request.
+	// BAD - Tests retrieving non-sensitive tokens and sensitive tokens in a GET request.
 	public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException {
 		String username = getRequestParameter(request, "username");
 		String token = getRequestParameter(request, "token");
@@ -20,7 +20,7 @@ String getRequestParameter(HttpServletRequest request, String paramName) {
 		return request.getParameter(paramName);
 	}
 
-	// GOOD - Tests sending sensitive information in a POST request.
+	// GOOD - Tests retrieving non-sensitive tokens and sensitive tokens in a POST request.
 	public void doPost(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException {
 		String username = getRequestParameter(request, "username");
 		String token = getRequestParameter(request, "token");