Doc improvements

Author: atorralba

java/ql/src/Security/CWE/CWE-917/OgnlInjection.java

@@ -14,4 +14,9 @@ public void evaluate(HttpServletRequest request, Object root) throws OgnlExcepti
   } else {
     // Reject the request
   }
-} 
+}
+
+public void isValid(Strig expression) {
+  // Custom method to validate the expression.
+  // For instance, make sure it doesn't include unexpected code.
+}

java/ql/src/Security/CWE/CWE-917/OgnlInjection.qhelp

@@ -3,31 +3,33 @@
   "qhelp.dtd">
 <qhelp>
 <overview>
-<p>Object-Graph Navigation Language (OGNL) is an open-source Expression Language (EL) for Java. Due
-to its ability to create or change executable code, OGNL is capable of introducing critical
-security flaws to any application that uses it. Evaluation of unvalidated expressions can let
-attacker to modify Java objects' properties or execute arbitrary code.</p>
+<p>Object-Graph Navigation Language (OGNL) is an open-source Expression Language (EL) for Java.
+OGNL can create or change executable code, consequently it can introduce critical
+security flaws to any application that uses it. Evaluation of unvalidated expressions is a common
+flaw in OGNL. This exposes the properties of Java objects to modification by an attacker and
+may allow them to execute arbitrary code.</p>
 </overview>
 
 <recommendation>
-<p>The general recommendation is to not evaluate untrusted ONGL expressions. If user provided OGNL
-expressions must be evaluated, do this in sandbox (add <code>-Dognl.security.manager</code> to JVM arguments)
-and validate the expressions before evaluation.</p>
+<p>The general recommendation is to avoid evaluating untrusted ONGL expressions. If user-provided OGNL
+expressions must be evaluated, do this in a sandbox and validate the expressions before evaluation.</p>
 </recommendation>
 
 <example>
 <p>In the following examples, the code accepts an OGNL expression from the user and evaluates it.
 </p>
 
-<p>In the first example, the user provided OGNL expression is parsed and evaluated.</p>
+<p>In the first example, the user-provided OGNL expression is parsed and evaluated.</p>
 
-<p>The second example validates the expression and evaluates it inside the sandbox.</p>
+<p>The second example validates the expression and evaluates it inside a sandbox.
+You can add a sandbox by setting a system property, as shown in the example, or by adding
+<code>-Dognl.security.manager</code> to JVM arguments.</p>
 
 <sample src="OgnlInjection.java" />
 </example>
 
 <references>
-<li><a href="https://github.com/jkuhnert/ognl/">OGNL library</a>.</li>
+<li>Apache Commons: <a href="https://commons.apache.org/proper/commons-ognl/">Apache Commons OGNL</a>.</li>
 <li>Struts security: <a href="https://struts.apache.org/security/#proactively-protect-from-ognl-expression-injections-attacks-if-easily-applicable">Proactively protect from OGNL Expression Injections attacks</a>.</li>
 </references>
-</qhelp>
+</qhelp>

java/ql/src/Security/CWE/CWE-917/OgnlInjection.ql

@@ -16,5 +16,5 @@ import DataFlow::PathGraph
 
 from DataFlow::PathNode source, DataFlow::PathNode sink, OgnlInjectionFlowConfig conf
 where conf.hasFlowPath(source, sink)
-select sink.getNode(), source, sink, "OGNL expression might include input from $@.",
+select sink.getNode(), source, sink, "OGNL expression might include data from $@.",
   source.getNode(), "this user input"