Document Taint Flow Graph

[ohader]

\Psalm\Internal\Codebase\TaintFlowGraph is somehow a mystery, however the central place for handling the taint-analysis mode. This issue collections the requirements/ideas for a potential documentation section on the taint graph:

All bellow is in the scope of Taint Graph - related documentation aspects can point to this reference.

Basics

• sources & sinks - and how to connect them
• nodes & forward-edges - in which direction to traverse the graph
• specialization

Examples

• simple examples of code-to-be-scanned (plain sources) & specialization (with and without)
• examples of adding taint models (sinks, sources, nodes, paths) in custom plugin implementation

Outline (current) Limitations

• e.g. tainting only works on function arguments (the flow of data), but not on invoking a function in general
• e.g. taint-sink, taint-escape, taint-unescape at the same time - and implications
• ... probably more ...

[orklah]

Feel free to ping me if you have questions. I'm certainly not an expert, but I had to bang my head against this once or twice already 😄

[ohader]

Feel free to ping me if you have questions. I'm certainly not an expert, but I had to bang my head against this once or twice already 😄

I tried to work around things with https://github.com/vimeo/psalm/pull/7468/commits/d48e58b061350878d9e3f8b77017dd1e88c080aa#diff-b59f43c20840fd89dc15850c51111379c9ce4aec5cdaff391c68c6ea0972ffabR45-R63 - however I'm not sure whether that's the correct way.

So that's why I'd like to

• start with documenting the behavior first
• then add (much more) test cases
• and finally try to extend it (refactor & conquer it by more explicit domain logic)

[AndrolGenhald]

It'll be great to have this better documented and tested, I'm always worried I'll break something and not notice when I touch anything taint related since it's not thoroughly tested.