Allow to implement custom taint type classes

docs/security_analysis/custom_taint_kinds.md

@@ -0,0 +1,100 @@
+# Custom Taint Kinds
+
+[Psalm\Type\TaintKindRegistry](https://github.com/vimeo/psalm/blob/master/src/Psalm/Type/TaintKindRegistry.php)
+allows plugins to define their own taint kinds and groups. The registry can be accessed via the `Psalm\Config`
+singleton.
+
+
+## Define Kinds
+
+```php
+$registry = \Psalm\Config::getInstance()->taint_kind_registry;
+$registry->defineKinds([
+    'custom-first' => \Example\Package\TaintedCustomA::class,
+    'custom-second' => \Example\Package\TaintedCustomB::class,
+], 'custom');
+```
+
+The example above defines the custom taints `custom-first` and `custom-second`,
+maps them to corresponding individual issue classes and organizes them
+in a new custom group `custom`.
+
+```php
+/**
+ * @psalm-taint-source custom-first
+ */
+function fetchFirst(): string {}
+/**
+ * Stub for the `custom` group - which includes both defined kinds.
+ *
+ * @psalm-taint-source custom
+ */
+function fetchData(): array {}
+```
+
+## Define Groups
+
+```php
+$registry = \Psalm\Config::getInstance()->taint_kind_registry;
+$registry->defineGroup('specific-input', 'html', 'sql');
+```
+
+The exmaple above defines a new group `specific-input`, which only holds
+a reduced subset (`html` and `sql`) of the default built-in group `input`.
+
+```php
+/**
+ * @psalm-taint-source specific-input
+ */
+function fetchData(): array {}
+```
+
+## Extend Groups
+
+```php
+$registry = \Psalm\Config::getInstance()->taint_kind_registry;
+$registry->extendGroup('input', 'custom-first');
+```
+
+The example above adds the custom kind `custom-first` to an existing group `input`.
+
+## Define Group Proxies
+
+```php
+$registry = \Psalm\Config::getInstance()->taint_kind_registry;
+$registry->defineGroupProxy('input-sql', 'input', [
+    'sql' => \Example\Package\TaintedSqlSecondOrder::class,
+]);
+```
+
+The example above is special as it defines `input-sql` to be a proxy for
+the existing group `input-sql` and keeps track of that usage. In addition,
+the build-in kind `sql` is overloaded with a custom issue class.
+
+This example is known as "Second Order SQL Injection", where data that was
+retrieved from a database is reused for new SQL queries. The assumption is,
+that the persisted data was not sanitized and might contain user submitted
+malicious snippets.
+
+```php
+/**
+ * @psalm-taint-source input-sql
+ */
+function fetchAliasFromDatabase(): string {}
+
+/**
+ * @psalm-taint-sink sql $query
+ * @psalm-taint-specialize
+ */
+function executeDatabaseQuery($query): array {}
+
+// this would still issue the default `TaintedSql`
+$alias = $_GET['alias'];
+$query = sprintf('SELECT * FROM comments WHERE alias="%s";', $alias); 
+$rows = executeDatabaseQuery($query);
+
+// this would issue the custom `TaintedSqlSecondOrder`
+$alias = fetchAliasFromDatabase();
+$query = sprintf('SELECT * FROM comments WHERE alias="%s";', $alias); 
+$rows = executeDatabaseQuery($query);
+```

docs/security_analysis/custom_taint_sources.md

@@ -48,6 +48,7 @@ class BadSqlTainter implements AfterExpressionAnalysisInterface
         $expr = $event->getExpr();
         $statements_source = $event->getStatementsSource();
         $codebase = $event->getCodebase();
+        $taint_type_registry = $codebase->config->taint_kind_registry;
         if ($expr instanceof PhpParser\Node\Expr\Variable
             && $expr->name === 'bad_data'
         ) {
@@ -63,7 +64,7 @@ class BadSqlTainter implements AfterExpressionAnalysisInterface
                 $codebase->addTaintSource(
                     $expr_type,
                     $expr_identifier,
-                    TaintKindGroup::ALL_INPUT,
+                    [TaintKindGroup::GROUP_INPUT],
                     new CodeLocation($statements_source, $expr)
                 );
             }

docs/security_analysis/index.md

@@ -39,7 +39,14 @@ Psalm recognises a number of taint types by default, defined in the [Psalm\Type\
 - `user_secret` - used for strings that could contain user-supplied secrets
 - `system_secret` - used for strings that could contain system secrets
 
+Each of these default kind types will be mapped to a corresponding class which inherits from abstract class
+`TaintedInput` - for instance `TaintedHtml`, `TaintedShell`, `TaintedHeader`, etc.
+
 You're also free to define your own taint types when defining custom taint sources – they're just strings.
+Per default those custom types are mapped to the generic class `TaintedCustom`.
+
+However, plugins can utilize [custom taint kinds](custom_taint_kinds.md) to define more specific classes
+for improved semantics and enhanced issue handling in general.
 
 ## Taint Sources
 

src/Psalm/Codebase.php

@@ -2420,10 +2420,10 @@
      * @param array<string> $taints
      * @psalm-suppress PossiblyUnusedMethod
      */
     public function addTaintSource(
         Union $expr_type,
         string $taint_id,
-        array $taints = TaintKindGroup::ALL_INPUT,
+        array $taints = [TaintKindGroup::GROUP_INPUT],
         ?CodeLocation $code_location = null
     ): Union {
         if (!$this->taint_flow_graph) {
@@ -2447,9 +2447,9 @@
      * @param array<string> $taints
      * @psalm-suppress PossiblyUnusedMethod
      */
     public function addTaintSink(
         string $taint_id,
-        array $taints = TaintKindGroup::ALL_INPUT,
+        array $taints = [TaintKindGroup::GROUP_INPUT],
         ?CodeLocation $code_location = null
     ): void {
         if (!$this->taint_flow_graph) {

src/Psalm/Config.php

@@ -41,6 +41,7 @@
 use Psalm\Plugin\PluginInterface;
 use Psalm\Progress\Progress;
 use Psalm\Progress\VoidProgress;
+use Psalm\Type\TaintKindRegistry;
 use RuntimeException;
 use SimpleXMLElement;
 use Symfony\Component\Filesystem\Path;
@@ -727,6 +728,11 @@ class Config
     /** @var list<string> */
     public array $config_warnings = [];
 
+    /**
+     * @readonly
+     */
+    public TaintKindRegistry $taint_kind_registry;
+
     /** @internal */
     protected function __construct()
     {
@@ -735,6 +741,7 @@ protected function __construct()
         $this->universal_object_crates = [
             strtolower(stdClass::class),
         ];
+        $this->taint_kind_registry = new TaintKindRegistry();
     }
 
     /**

src/Psalm/Config/IssueHandler.php

@@ -175,7 +175,8 @@ public static function getAllIssueTypes(): array
                 && $issue_name !== 'ParseError'
                 && $issue_name !== 'PluginIssue'
                 && $issue_name !== 'MixedIssue'
-                && $issue_name !== 'MixedIssueTrait',
+                && $issue_name !== 'MixedIssueTrait'
+                && $issue_name !== 'TaintKindFactory',
         );
     }
 }

src/Psalm/Internal/Analyzer/Statements/Expression/Fetch/VariableFetchAnalyzer.php

@@ -522,7 +522,7 @@ private static function taintVariable(
                     $var_name,
                     null,
                     null,
-                    TaintKindGroup::ALL_INPUT,
+                    [TaintKindGroup::GROUP_INPUT],
                 );
 
                 $statements_analyzer->data_flow_graph->addSource($server_taint_source);