Fix #3610 - add security analysis documeentation

docs/security_analysis/annotations.md

@@ -0,0 +1,17 @@
+# Security analysis annotations
+
+## `@psalm-taint-source`
+
+See [Custom taint sources](custom_taint_sources.md#taint-source-annotation).
+
+## `@psalm-taint-sink`
+
+See [Custom taint sinks](custom_taint_sinks.md).
+
+## `@psalm-taint-escape`
+
+See [Escaping tainted output](avoiding_false_positives.md#escaping-tainted-output).
+
+## `@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_positives.md

@@ -6,7 +6,7 @@ Nobody likes false-positives!
 
 There are a number of ways you can prevent them:
 
-## Removing taints
+## Escaping tainted input
 
 Some operations remove taints from data – for example, wrapping `$_GET['name']` in an `htmlentities` call prevents cross-site-scripting attacks in that `$_GET` call.
 
@@ -19,7 +19,7 @@ function echoVar(string $str) : void {
     /**
      * @psalm-taint-escape html
      */
-    $str = preg_replace('/[^a-z]/', '', $str);
+    $str = str_replace(['<', '>'], '', $str);
     echo $str;
 }
 

docs/security_analysis/custom_taint_sources.md

@@ -2,7 +2,7 @@
 
 You can define your own taint sources with an annotation or a plugin.
 
-## Custom taint sourcce annotation
+## Taint source annotation
 
 You can use the annotation `@psalm-taint-source <taint-type>` to indicate a function or method that provides user input.