From 646bf994896d951c90a2cc09dc40ef1500625a63 Mon Sep 17 00:00:00 2001
From: Erik Krogh Kristensen <erik-krogh@github.com>
Date: Mon, 10 May 2021 10:45:33 +0200
Subject: [PATCH] rewrite the qhelp to focus more on documenting unsafe
 functions

---
 .../CWE-079/UnsafeHtmlConstruction.qhelp      | 29 +++++++++----------
 1 file changed, 13 insertions(+), 16 deletions(-)

diff --git a/javascript/ql/src/Security/CWE-079/UnsafeHtmlConstruction.qhelp b/javascript/ql/src/Security/CWE-079/UnsafeHtmlConstruction.qhelp
index 619b55e4920..0bc3bd53a0d 100644
--- a/javascript/ql/src/Security/CWE-079/UnsafeHtmlConstruction.qhelp
+++ b/javascript/ql/src/Security/CWE-079/UnsafeHtmlConstruction.qhelp
@@ -4,26 +4,22 @@
 <qhelp>
 <overview>
 	<p>
-		Dynamically constructing HTML with inputs from library functions that are 
-		available to external clients may inadvertently leave a client open to XSS attacks.
-		
-		Clients using the exported function may use inputs containing unsafe HTML,
-		and if these inputs end up in the DOM, the client may be vulnerable to
-		cross-site scripting attacks.
-	</p>
+		When a library function dynamically constructs HTML in a potentially unsafe
+		way, then it's important to document to clients of the library that the function 
+		should only be used with trusted inputs. 
 
+		If the function is not documented as being potentially unsafe, then a client
+		may inadvertently use inputs containing unsafe HTML fragments, and thereby leave
+		the client vulnerable to cross-site scripting attacks.
+	</p>
 </overview>
 <recommendation>
 
 	<p>
-		If possible, use safe APIs when inserting HTML into the DOM.  
-		Such as writing to the <code>innerText</code> property instead of <code>innerHTML</code>.
+		Document all library functions that can lead to cross-site scripting 
+		attacks, and guard against unsafe inputs where dynamic HTML
+		construction is not intended.
 	</p>
-
-	<p>
-		Alternatively, use a HTML sanitizer to escape/remove unsafe content.
-	</p>
-
 </recommendation>
 <example>
 
@@ -41,13 +37,14 @@
 	</p>
 
 	<p>
-		To avoid such attacks, a program can use safe APIs such as <code>innerText</code>.
+		The library could either document that this function should not be used
+		with unsafe inputs, or use safe APIs such as <code>innerText</code>.
 	</p>
 
 	<sample src="examples/unsafe-html-construction_safe.js" />
 	
 	<p>
-		Alternatively, use a HTML sanitizer to remove unsafe content.
+		Alternatively, a HTML sanitizer can be used to remove unsafe content.
 	</p>
 
 	<sample src="examples/unsafe-html-construction_sanitizer.js" />