Update documentation for taints and global configuration (#5098)

* [DOCS] Extend documentation on global variables configuration

* [DOCS] Synchronize meaning of @psalm-taint-source input with source code

* [DOCS] Add documentation for conditional @psalm-taint-escape

* [DOCS] Add documentation for @psalm-taint-unescape

docs/running_psalm/configuration.md

@@ -416,3 +416,33 @@ Optional.  If your codebase uses global variables that are accessed with the `gl
   <var name="globalVariableName" type="type" />
 </globals>
 ```
+
+Some frameworks and libraries expose functionalities through e.g. `$GLOBALS[DB]->query($query)`.
+The  following configuration declares custom types for super-globals (`$GLOBALS`, `$_GET`, ...).
+
+```xml
+<globals>
+  <var name="$GLOBALS" type="array{DB: MyVendor\DatabaseConnection, VIEW: MyVendor\TemplateView}" />
+  <var name="$_GET" type="array{data: array<string, string>}" />     
+</globals>
+```
+
+The example above declares global variables as shown below
+
+* `$GLOBALS`
+  + `DB` of type `MyVendor\DatabaseConnection`
+  + `VIEW` of type `MyVendor\TemplateView`
+* `$_GET`
+  + `data` e.g. like `["id" => "123", "title" => "Nice"]`
+
+## Accessing Psalm configuration in plugins
+
+Plugins can access or modify the global configuration in plugins using
+[singleton Psalm\Config](https://github.com/vimeo/psalm/blob/master/src/Psalm/Config.php).
+
+```php
+$config = \Psalm\Config::getInstance();
+if (!isset($config->globals['$GLOBALS'])) {
+    $config->globals['$GLOBALS'] = 'array{data: array<string, string>}';
+}
+```

docs/security_analysis/annotations.md

@@ -1,17 +1,21 @@
 # Security analysis annotations
 
-## `@psalm-taint-source`
+## `@psalm-taint-source <taint-type>`
 
 See [Custom taint sources](custom_taint_sources.md#taint-source-annotation).
 
-## `@psalm-taint-sink`
+## `@psalm-taint-sink <taint-type> <param-name>`
 
 See [Custom taint sinks](custom_taint_sinks.md).
 
-## `@psalm-taint-escape`
+## `@psalm-taint-escape <taint-type #conditional>`
 
 See [Escaping tainted output](avoiding_false_positives.md#escaping-tainted-output).
 
+## `@psalm-taint-unescape <taint-type>`
+
+See [Unescaping statements](avoiding_false_negatives.md#unescaping-statements).
+
 ## `@psalm-taint-specialize`
 
 See [Specializing taints in functions](avoiding_false_positives.md#specializing-taints-in-functions) and [Specializing taints in classes](avoiding_false_positives.md#specializing-taints-in-classes).

docs/security_analysis/avoiding_false_negatives.md

@@ -0,0 +1,25 @@
+# Avoiding false-negatives
+
+## Unescaping statements
+
+Post-processing previously escaped/encoded statements can cause insecure scenarios.
+`@psalm-taint-unescape <taint-type>` allows to declare those components insecure explicitly.
+
+```php
+<?php
+
+/**
+ * @psalm-taint-unescape html
+ */
+function decode(string $str): string
+{
+    return str_replace(
+        ['&lt;', '&gt;', '&quot;', '&apos;'],
+        ['<', '>', '"', '"'],
+        $str
+    );
+}
+
+$safe = htmlspecialchars($_GET['text']);
+echo decode($safe);
+```

docs/security_analysis/avoiding_false_positives.md

@@ -1,6 +1,6 @@
 # Avoiding false-positives
 
-When you run Psalm’s taint analysis for the first time you may see a bunch of false-positives.
+When you run Psalm's taint analysis for the first time you may see a bunch of false-positives.
 
 Nobody likes false-positives!
 
@@ -26,6 +26,29 @@ function echoVar(string $str) : void {
 echoVar($_GET["text"]);
 ```
 
+## Conditional 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
+`@psalm-taint-escape` is applied for taint type `html` .
+
+```php
+/**
+ * @param string $str
+ * @param bool $escape
+ * @psalm-taint-escape ($escape is true ? 'html' : null)
+ */
+function processVar(string $str, bool $escape = true) : string {
+    if ($escape) {
+      $str = str_replace(['<', '>'], '', $str);
+    }
+    return $str;
+}
+
+echo processVar($_GET['text'], false); // detects tainted HTML
+echo processVar($_GET['text'], true); // considered secure
+```
+
 ## Specializing taints in functions
 
 For functions, methods and classes you can use the `@psalm-taint-specialize` annotation.

docs/security_analysis/custom_taint_sources.md

@@ -6,7 +6,7 @@ You can define your own taint sources with an annotation or a plugin.
 
 You can use the annotation `@psalm-taint-source <taint-type>` to indicate a function or method that provides user input.
 
-In the below example the `input` taint type is specified as a standin for the four input taints `text`, `html`, `sql` and `shell`.
+In the below example the `input` taint type is specified as a standin for input taints as defined in [Psalm\Type\TaintKindGroup](https://github.com/vimeo/psalm/blob/master/src/Psalm/Type/TaintKindGroup.php).
 
 ```php
 /**