====================
Multi-Tool Scanning
====================

MemGuard orchestrates 15 detection tools in parallel with unified output and AI analysis.

Usage
-----

.. code-block:: bash

   # Scan with specific tools
   memguard scan /tmp/binary --tools valgrind,helgrind,infer

   # Scan with all available tools
   memguard scan /tmp/binary

   # Fast scan without AI
   memguard scan /tmp/binary --no-ai

   # Scan from source
   memguard scan ./src/main.c --compile "gcc -g -O0 -o /tmp/out main.c"

   # With binary arguments
   memguard scan /tmp/server --args "--port 8080"

   # Verbose (shows MemHint injection)
   memguard scan /tmp/binary -v

   # Export to JSON
   memguard scan /tmp/binary --output report.json

   # View past scans
   memguard history
   memguard report <scan-id>

How It Works
------------

1. **DWARF Source Discovery** - reads binary debug info to find source files
2. **MemHint Loading** - injects custom allocator patterns into Infer
3. **Parallel Execution** - all tools run concurrently via asyncio
4. **Unified Parsing** - Valgrind XML, Infer JSON, cppcheck XML → MemoryError objects
5. **Deduplication** - merges same-location errors across tools
6. **AI 4-Pass Analysis** - triage, root cause, fix generation, step decomposition
7. **Fix Validation** - pattern validator + CWE validator + Z3 verifier

Detection Tools
---------------

.. list-table::
   :header-rows: 1
   :widths: 20 10 70

   * - Tool
     - Type
     - What It Detects
   * - **Valgrind memcheck**
     - Dynamic
     - Leaks, use-after-free, uninit reads, invalid free
   * - **Helgrind**
     - Dynamic
     - Data races, lock order violations, pthread misuse
   * - **Facebook Infer**
     - Static
     - Null deref, leaks, uninit reads (+ custom MM via MemHint)
   * - **cppcheck**
     - Static
     - Buffer overflows, null deref, style issues
   * - **clang-tidy**
     - Static
     - C++ modernization, bug-prone patterns
   * - **ASan/LSan/MSan/UBSan/TSan**
     - Dynamic
     - Address errors, leaks, uninit memory, UB, data races
   * - **heaptrack**
     - Dynamic
     - Every malloc/free with full call stacks
   * - **rr**
     - Dynamic
     - Deterministic recording for reverse debugging
   * - **tracemalloc / memray**
     - Python
     - Python memory allocation tracking
   * - **Miri**
     - Rust
     - Rust undefined behavior in unsafe code

Bug Types
---------

.. list-table::
   :header-rows: 1
   :widths: 22 12 12 54

   * - Bug Type
     - Severity
     - CWE
     - Description
   * - ``use_after_free``
     - CRITICAL
     - CWE-416
     - Accessing memory after deallocation
   * - ``double_free``
     - CRITICAL
     - CWE-415
     - Calling free() twice on same pointer
   * - ``buffer_overflow``
     - CRITICAL
     - CWE-122
     - Writing past allocated buffer boundaries
   * - ``null_deref``
     - CRITICAL
     - CWE-476
     - Dereferencing a NULL pointer
   * - ``race_condition``
     - CRITICAL
     - CWE-362
     - Unsynchronized concurrent memory access
   * - ``memory_leak``
     - INFO
     - CWE-401
     - Allocated memory never freed