From e015b7f7de315fddf5332405726d69ec4a4a72a1 Mon Sep 17 00:00:00 2001
From: Oliver Hader <oliver@typo3.org>
Date: Mon, 6 Nov 2023 21:38:49 +0100
Subject: [PATCH] Add documentation for @psalm-flow

---
 docs/security_analysis/annotations.md |  4 ++
 docs/security_analysis/taint_flow.md  | 66 +++++++++++++++++++++++++++
 2 files changed, 70 insertions(+)
 create mode 100644 docs/security_analysis/taint_flow.md

diff --git a/docs/security_analysis/annotations.md b/docs/security_analysis/annotations.md
index dd5527431..d3650922c 100644
--- a/docs/security_analysis/annotations.md
+++ b/docs/security_analysis/annotations.md
@@ -19,3 +19,7 @@ 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).
+
+## `@psalm-flow [proxy <function-like>] ( <arg>, [ <arg>, ] ) [ -> return ]`
+
+See [Taint Flow](taint_flow.md#optimized-taint-flow)
diff --git a/docs/security_analysis/taint_flow.md b/docs/security_analysis/taint_flow.md
new file mode 100644
index 000000000..2c77c0795
--- /dev/null
+++ b/docs/security_analysis/taint_flow.md
@@ -0,0 +1,66 @@
+# Taint Flow
+
+## Optimized Taint Flow
+
+When dealing with frameworks, keeping track of the data flow might involve different layers
+and even other 3rd party components. Using the `@psalm-flow` annotation allows PsalmPHP to
+take a shortcut and to make a tainted data flow more explicit.
+
+### Proxy hint
+
+```php
+<?php // --taint-analysis
+/**
+ * @psalm-flow proxy exec($value)
+ */
+function process(string $value): void {}
+
+process($_GET['malicious'] ?? '');
+```
+
+The example above states, that the function `process($value)` is a proxy of the native PHP
+function `exec($value)` - which is potentially vulnerable to code execution (`TaintedShell`).
+
+**Examples**
+
++ `@psalm-flow proxy exec($value)` referencing the global/scoped function `exec`
++ `@psalm-flow proxy MyClass::mySinkMethod($value)` referencing a function/method of the class `MyClass`
+
+### Return value hint
+
+```php
+<?php // --taint-analysis
+/**
+ * @psalm-flow ($value, $items) -> return
+ */
+function inputOutputHandler(string $value, string ...$items): string
+{
+    // lots of complicated magic
+}
+
+echo inputOutputHandler('first', 'second', $_GET['malicious'] ?? '');
+```
+
+The example above states, that the function parameters `$value` and `$items` are reflected
+again in the return value. Thus, in case any of the input parameters to the function
+`inputOutputHandler` is tainted, then the resulting return value is as well. In this
+example `TaintedHtml` would be detected due to using `echo`.
+
+### Combined proxy & return value hint
+
+```php
+<?php // --taint-analysis
+/**
+ * @psalm-flow proxy exec($value)
+ * @psalm-flow ($value, $items) -> return
+ */
+function handleInput(string $value, string ...$items): string
+{
+    // lots of complicated magic
+}
+
+echo handleInput($_GET['malicious'] ?? '');
+```
+
+The example above combines both previous examples and shows, that the `@psalm-flow` annotation
+can be used multiple times. Here, it would lead to detecting both `TaintedHtml` and `TaintedShell`.