JS: Documentation fixes

javascript/ql/src/Security/CWE-022/ZipSlip.qhelp

@@ -36,19 +36,32 @@ to prevent writing files to unexpected locations.</p>
 
 <example>
 <p>
-Here is an example of extracting an archive without validating
-filenames. If <code>archive.zip</code> contained relative paths (for
+In this example an archive is extracted without validating file paths.
+If <code>archive.zip</code> contained relative paths (for
 instance, if it were created by something like <code>zip archive.zip
-../file.txt</code>) then executing this code would write to those paths.
+../file.txt</code>) then executing this code could write to locations
+outside the destination directory.
 </p>
 
 <sample src="ZipSlipBad.js" />
 
-<p>To fix this vulnerability, we can to check that the path does not
+<p>To fix this vulnerability, we need to check that the path does not
 contain any <code>".."</code> elements in it.
 </p>
 
 <sample src="ZipSlipGood.js" />
 
 </example>
+<references>
+
+<li>
+Snyk:
+<a href="https://snyk.io/research/zip-slip-vulnerability">Zip Slip Vulnerability</a>.
+</li>
+<li>
+OWASP:
+<a href="https://www.owasp.org/index.php/Path_traversal">Path Traversal</a>.
+</li>
+
+</references>
 </qhelp>

javascript/ql/src/Security/CWE-022/ZipSlipBad.js

@@ -5,5 +5,6 @@ fs.createReadStream('archive.zip')
   .pipe(unzip.Parse())
   .on('entry', entry => {
     const fileName = entry.path;
+    // BAD: This could write any file on the filesystem.
     entry.pipe(fs.createWriteStream(fileName));
   });

javascript/ql/src/Security/CWE-022/ZipSlipGood.js

@@ -5,6 +5,7 @@ fs.createReadStream('archive.zip')
   .pipe(unzip.Parse())
   .on('entry', entry => {
     const fileName = entry.path;
+    // GOOD: ensures the path is safe to write to.
     if (fileName.indexOf('..') == -1) {
       entry.pipe(fs.createWriteStream(fileName));
     }

javascript/ql/src/semmle/javascript/security/dataflow/ZipSlip.qll

@@ -78,7 +78,7 @@ module ZipSlip {
     CreateWriteStreamSink() {
       // This is not covered by `FileSystemWriteSink`, because it is
       // required that a write actually takes place to the stream.
-      // However, we want to consider even the bare createWriteStream
+      // However, we want to consider even the bare `createWriteStream`
       // to be a zipslip vulnerability since it may truncate an
       // existing file.
       this = DataFlow::moduleImport("fs").getAMemberCall("createWriteStream").getArgument(0)
@@ -91,8 +91,8 @@ module ZipSlip {
   }
 
   /**
-   * Gets a string which suffices to search for to ensure that a
-   * filepath will not refer to parent directories.
+   * Gets a string which is sufficient to exclude to make
+   * a filepath definitely not refer to parent directories.
    */
   private string getAParentDirName() { result = ".." or result = "../" }