Documented suggestions for HTML user input

docs/running_psalm/issues/TaintedHtml.md

@@ -35,6 +35,7 @@ function printName(string $name) {
 - Sanitize user-input by using functions such as `htmlentities` or use an allowlist.
 - Set all cookies to `HTTPOnly`.
 - Consider using Content Security Policy (CSP), to limit the risk of XSS vulnerabilities.
+- If user input itself is HTML, see [Sanitizing HTML User Input](../../security_analysis/avoiding_false_positives.md#sanitizing-html-user-input)
 
 ## Further resources
 

docs/running_psalm/issues/TaintedTextWithQuotes.md

@@ -35,6 +35,7 @@ Passing `');alert('injection');//` as a `GET` param here would cause the `alert`
 - Sanitize user input by using functions such as `htmlentities` with the `ENT_QUOTES` flag or use an allowlist.
 - Set all cookies to `HTTPOnly`.
 - Consider using Content Security Policy (CSP), to limit the risk of XSS vulnerabilities.
+- If user input itself is HTML, see [Sanitizing HTML User Input](../../security_analysis/avoiding_false_positives.md#sanitizing-html-user-input)
 
 ## Further resources
 

docs/security_analysis/avoiding_false_positives.md

@@ -26,7 +26,7 @@ function echoVar(string $str) : void {
 echoVar($_GET["text"]);
 ```
 
-## Conditional escaping tainted input
+## Conditionally escaping tainted input
 
 A slightly modified version of the previous example is using a condition to determine whether the return value
 is considered secure. Only in case function argument `$escape` is true, the corresponding annotation
@@ -50,6 +50,23 @@ echo processVar($_GET['text'], false); // detects tainted HTML
 echo processVar($_GET['text'], true); // considered secure
 ```
 
+## Sanitizing HTML user input
+
+Whenever possible, applications should be designed to accept & store user input as discrete text fields, rather than blocks of HTML.  This allows user input to be fully escaped via `htmlspecialchars` or `htmlentities`.  In cases where HTML user input is required (e.g. rich text editors like [TinyMCE](https://www.tiny.cloud/)), a library designed specifically to filter out risky HTML is highly recommended.  For example, [HTML Purifier](http://htmlpurifier.org/docs) could be used as follows:
+
+```php
+<?php
+
+/**
+ * @psalm-taint-escape html
+ * @psalm-taint-escape has_quotes
+ */
+function sanitizeHTML($html){
+    $purifier = new HTMLPurifier();
+    return $purifier->purify($html);
+}
+```
+
 ## Specializing taints in functions
 
 For functions, methods and classes you can use the `@psalm-taint-specialize` annotation.