From f1f0f50c92febed552af8de40da61f6e0c16562d Mon Sep 17 00:00:00 2001
From: Ed Minnix <egregius313@github.com>
Date: Tue, 14 Nov 2023 13:11:43 -0500
Subject: [PATCH] TaintedEnvironmentVariableQuery docs

---
 .../code/java/security/TaintedEnvironmentVariableQuery.qll | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/java/ql/lib/semmle/code/java/security/TaintedEnvironmentVariableQuery.qll b/java/ql/lib/semmle/code/java/security/TaintedEnvironmentVariableQuery.qll
index b6291bfe6f9..30a47c73596 100644
--- a/java/ql/lib/semmle/code/java/security/TaintedEnvironmentVariableQuery.qll
+++ b/java/ql/lib/semmle/code/java/security/TaintedEnvironmentVariableQuery.qll
@@ -18,16 +18,23 @@ private module ProcessBuilderEnvironmentConfig implements DataFlow::ConfigSig {
 
 private module ProcessBuilderEnvironmentFlow = DataFlow::Global<ProcessBuilderEnvironmentConfig>;
 
+/**
+ * A taint-tracking configuration that tracks flow from unvalidated data to an environment variable for a subprocess.
+ */
 module ExecTaintedEnvironmentConfig implements DataFlow::ConfigSig {
   predicate isSource(DataFlow::Node source) { source instanceof ThreatModelFlowSource }
 
   predicate isSink(DataFlow::Node sink) {
     sinkNode(sink, "environment-injection")
     or
+    // sink is an added to a `ProcessBuilder::environment` map.
     exists(MapPutCall mpc | mpc.getAnArgument() = sink.asExpr() |
       ProcessBuilderEnvironmentFlow::flowToExpr(mpc.getQualifier())
     )
   }
 }
 
+/**
+ * Taint-tracking flow for unvalidated data to an environment variable for a subprocess.
+ */
 module ExecTaintedEnvironmentFlow = TaintTracking::Global<ExecTaintedEnvironmentConfig>;