Phan Taint Check Plugin Laravel Package

Getting Started

1. Install: Run composer require --dev mediawiki/phan-taint-check-plugin to add the plugin.
2. Configure: In your Phan config (.phan/config.php), add the plugin to the plugins list:
   • For generic PHP: 'vendor/mediawiki/phan-taint-check-plugin/GenericSecurityCheckPlugin.php'
   • For MediaWiki: 'vendor/mediawiki/phan-taint-check-plugin/MediaWikiSecurityCheckPlugin.php'
3. Disable quick mode: Set 'quick_mode' => false — critical for the plugin to work.
4. Suppress known false positives: Add SecurityCheck-LikelyFalsePositive and SecurityCheck-PHPSerializeInjection to suppress_issue_types.
5. Run: vendor/bin/phan -d . --long-progress-bar. Add --analyze-twice for deeper checks.

First use case: Scan your app for XSS or SQLi entry points — e.g., tainted $_GET used in echo, require, or SQL queries.

Implementation Patterns

• Incremental adoption: Start with high-severity issues (-y 10), then expand coverage. Use @suppress selectively (see Gotchas).
• Custom escaping functions: Document escaping behavior with @param-taint $param escapes_html so Phan knows escapeHtml() clears HTML taint.
• Taint propagation control:
  • Use @param-taint $input exec_html to flag functions that output unsanitized user input (triggers warnings if HTML-tainted values are passed).
  • Use @return-taint htmlnoent to mark return values as safe HTML (e.g., for pre-escaped content).
• MediaWiki-specific patterns:
  • Annotate hook subscribers: Use @param-taint $param escapes_sql on custom DB abstraction methods.
  • For select() options, ensure $options/$join_cond are arrays literals — the plugin detects taint only in these cases.
• Debugging: Insert '@phan-debug-var-taintedness $variableName'; as a string literal in code to see taint state at runtime.

Gotchas and Tips

• False positives: Expect noise. Use @phan-suppress-next-line SecurityCheck-XSS or @suppress in docblocks for known-safe cases (e.g., CLI scripts outputting non-HTML).
• Subclass limitations: Phan can’t track taint through subclasses reliably. Override return values in subclasses with @return-taint html when safe.
• Pass-by-reference hooks: In MediaWiki, line numbers may point to core hooks instead of the extension subscriber — inspect actual usage sites.
• Escape detection is strict: Custom escaping won’t be recognized without @param-taint. E.g., @param-taint $str escapes_html tells Phan your escapeMyHtml() is safe.
• Config quirk: --analyze-twice catches more issues but may duplicate reports — filter with grep -v "SecurityCheck" if debugging.
• CLI Gotcha: Disable XSS warnings globally for CLI scripts using @phan-file-suppress SecurityCheck-XSS at top of entry scripts.
• Extension points: Subclass SecurityCheckPlugin to add custom taint types (e.g., custom1 for config injection) via getCustomFuncTaints(). See MediaWikiSecurityCheckPlugin for real-world examples.