==========================
Taint Flow Tracker
==========================

Traces how external input flows to detected memory bugs - answers
"Can an attacker actually trigger this bug?"

Usage
-----

.. code-block:: bash

   # After scanning
   memguard taint <scan-id>
   memguard taint <scan-id> --source ./src/

   # Via GUI: click any issue → Taint Flow button

Expected Output
~~~~~~~~~~~~~~~

.. code-block:: text

   CRITICAL: 2 bugs reachable from network input.
   Remote exploitation possible.

   recv() network → 'buf'
     →param parse_request() 'raw'
     →return log_request() 'req'
     → USE_AFTER_FREE at server_sim.c:92
   Confidence: 90%

6-Phase Pipeline
----------------

1. **Parse source** - tree-sitter (regex fallback) extracts functions with params, assignments, struct writes, globals, returns, function pointer calls
2. **Find taint sources** - 30+ input functions across 6 categories (network, file, stdin, argv, env, IPC)
3. **Build data-flow graph** - 5 edge types: PARAM, RETURN, ASSIGN, GLOBAL, STRUCT
4. **Propagate taint** - iterative fixpoint at variable level through assignments, parameters, returns, struct fields, globals
5. **Trace to bugs** - BFS with data-flow awareness, prefers tainted paths
6. **Risk assessment** - edge-type weighted confidence scoring with contextual narrative