documentation for handlebars.js flow step

Author: Stephan Brandauer

javascript/ql/lib/semmle/javascript/frameworks/Handlebars.qll

@@ -52,6 +52,23 @@ module TaintStep {
   /**
    * Holds if there's a step from `pred` to `succ` due to templating data being
    * passed from a templating call to a registered helper via a parameter.
+   *
+   * To establish the step, we look at the template passed to `compile`, and will
+   * only track steps from templates to helpers they actually reference.
+   *
+   * ```javascript
+   * function loudHelper(text) {
+   *   //                ^^^^ succ
+   *   return text.toUpperCase();
+   * }
+   *
+   * hb.registerHelper("loud", loudHelper);
+   *
+   * const template = hb.compile("Hello, {{loud name}}!");
+   *
+   * template({name: "user"});
+   * //              ^^^^^^ pred
+   * ```
    */
   private predicate isHandlebarsArgStep(DataFlow::Node pred, DataFlow::Node succ) {
     exists(string helperName |

javascript/ql/test/query-tests/Security/CWE-022/TaintedPath/handlebars.js

@@ -7,10 +7,10 @@ const app = express();
 const data = {};
 
 function init() {
+    hb.registerHelper("catFile", catFile);
     data.compiledFileAccess = hb.compile("contents of file {{path}} are: {{catFile path}}")
     data.compiledBenign = hb.compile("hello, {{name}}");
     data.compiledUnknown = hb.compile(fs.readFileSync("greeting.template"));
-    hb.registerHelper("catFile", catFile);
 }
 
 init();