# gdb-analyzer

**Repository Path**: eliasfp/gdb-analyzer

## Basic Information

- **Project Name**: gdb-analyzer
- **Description**: 全程AI生成代码并测试 ,grill-me, superpowers
- **Primary Language**: Python
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-12
- **Last Updated**: 2026-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

GDB Python 自动化调试分析工具
=================================

概述
----
gdb_analyzer.py 是一个 GDB 原生 Python 脚本，用于自动化调试分析。
在 GDB 中 source 后，提供 analyze 系列命令，一键检测：

  - 线程状态分析
  - 死锁检测（mutex / rwlock / spinlock / condvar 循环等待）
  - Crash 根因分析（SIGSEGV / SIGABRT / SIGFPE / SIGILL / SIGBUS / SIGSYS）
    · SIGSEGV 依据内存映射分类：空指针 / 写只读内存 / 未映射空洞 / 栈保护页
    · SIGFPE 依据 si_code 区分除零与溢出
    · SIGABRT 解析 glibc malloc_printerr 精确堆错误；回退识别 double free
  - C++ STL 容器/智能指针深度检查（crash 时自动扫描栈上变量）
  - 栈溢出检测（帧数 / 栈保护页 / SP 贴近栈底）
  - Use-After-Free（UAF）检测
  - 跨分析器 Top Conclusion：综合信号 + 堆区间 + STL 一致性，给出
    根因、代码位置（file:line）与置信度

零外部依赖，拷贝即用。


使用方法
--------
1. 在 GDB 中加载脚本：

    (gdb) source /path/to/gdb_analyzer.py
    gdb-analyzer loaded. Available commands: analyze, analyze-deadlock, analyze-crash, analyze-config

2. 运行分析：

    (gdb) analyze                  # 运行全部分析器，生成完整报告
    (gdb) analyze-deadlock         # 仅运行死锁检测
    (gdb) analyze-crash            # 仅运行 Crash 分析

3. （可选）指定 YAML 配置文件：

    (gdb) analyze-config /path/to/gdb_analyzer.yaml


命令详解
--------
analyze
    运行所有启用的分析器，依次执行：
      1. ThreadStateAnalyzer   — 列举所有线程及状态
      2. DeadlockDetector      — 检测 mutex 循环等待死锁
      3. CrashAnalyzer         — 信号根因分析 + STL 变量深度检查
      4. StackOverflowDetector — 检查栈帧数是否异常
      5. UafDetector           — 检查故障地址是否在堆区间
    输出格式为静态文本报告。

analyze-deadlock
    仅运行 DeadlockDetector，适用于已知死锁场景快速确认。

analyze-crash
    仅运行 CrashAnalyzer，适用于 coredump 或进程已停止于信号时。

analyze-config <path>
    指定 YAML 配置文件路径。不指定时使用全默认配置。


YAML 配置
---------
配置文件为可选项。不提供时所有分析器默认启用（stack_overflow 默认禁用）。
示例见 gdb_analyzer.yaml。


适用场景
--------
- 应用开发中遇到死锁，快速定位等待链
- 程序 coredump 后分析 SIGSEGV 根因（空指针 / 野指针）
- C++ STL 容器/智能指针使用不当导致的 crash（double free、UAF、move 后访问等）
- 多线程调试时一览所有线程状态
- CI 或开发环境中快速检查


文件结构
--------
  gdb_analyzer.py        主脚本（8 个 Section）
  stl_inspector/         C++ STL 深度检查模块
    __init__.py              统一入口 inspect_variable()
    base.py                  StlInspector 抽象基类
    registry.py              类型名 -> Inspector 自动匹配
    report.py                结构化结果模型
    inspectors/
      string.py              std::string / std::wstring
      vector.py              std::vector<T>
      unique_ptr.py          std::unique_ptr<T>
      shared_ptr.py          std::shared_ptr<T>
      weak_ptr.py            std::weak_ptr<T>
      map.py                 std::map<K,V>
      unordered_map.py       std::unordered_map<K,V>
      set.py                 std::set<T>
      deque.py               std::deque<T>
      list_.py               std::list<T> / std::forward_list<T>
      array.py               std::array<T,N>
      std_optional.py        std::optional<T>
  gdb_analyzer.yaml      YAML 配置文件示例
  test_gdb_analyzer.py   离线单元测试（103 个测试用例）
  test_target/           测试用 C++ 程序
    deadlock.cpp              双线程 mutex 死锁
    crash_null.cpp            SIGSEGV 空指针解引用
    crash_uaf.cpp             Use-After-Free
    crash_stl_shared_ptr_double_raw.cpp  双重裸指针构造 → double free
    crash_stl_unique_ptr_moved.cpp       move 后访问原对象 → SIGSEGV
    crash_stl_weak_ptr_expired.cpp       expired 后 lock 未检查 → SIGSEGV
    crash_stl_string_vector.cpp          string + vector 栈上快照
    crash_stl_map_shared.cpp             map + shared_ptr 栈上快照
    （其他信号测试 17 个）
    Makefile


技术说明
--------
- 语言：Python 3（GDB 内嵌解释器）
- 依赖：无（PyYAML 为可选，不影响核心功能）
- 架构：AnalyzerPlugin 抽象基类 + 7 个内置插件 + stl_inspector 模块
- 输出：静态文本报告（支持 JSON 格式导出）
- 兼容性：针对 GDB 12+ / glibc 2.35+ / GCC 5+ (libstdc++ 3.4.21+) 测试


原理简述
--------
死锁检测：遍历所有线程的调用栈，识别处于锁等待的帧
（pthread_mutex_lock / rwlock / spinlock / condvar），提取锁地址，
读取 pthread_mutex_t.__data.__owner 字段获取持有者 LWP ID，
构建等待图，DFS 检测环。

Crash 分析：通过 GDB $_siginfo 获取信号类型、故障地址与 si_code。
  - fault_addr == 0x0        → 空指针解引用
  - fault_addr  < 0x1000     → 成员访问空指针
  - fault_addr 依据内存映射分类：
      · 未映射空洞            → 野指针 / UAF / 未初始化指针
      · 栈保护页 / 栈底        → 栈溢出（配合 StackOverflowDetector）
      · 只读区域被写(r--p)     → 写只读内存（.rodata const/字符串字面量）
  - si_code 区分 SEGV_MAPERR(映射故障) 与 SEGV_ACCERR(保护故障)
  - SIGFPE 按 FPE_INTDIV/FPE_INTOVF 区分除零与溢出
  - SIGABRT 解析 malloc_printerr 精确堆错误，失败时按分配器帧回退归类；
    识别 std::terminate/未捕获异常

Top Conclusion（跨分析器综合）：
把 Crash 信号 + UAF 堆区间 + STL 一致性警告 交叉关联，输出一条
根因 + 代码位置(file:line) + 置信度 的结论（如 shared_ptr use_count==0
且 SIGSEGV 位于堆 → Use-after-free, high）。

STL 深度检查（CrashAnalyzer 集成）：
崩溃时自动扫描崩溃线程栈帧中的 STL 类型变量，读取内部字段：

  L1 — 基本信息：
    std::string       length, SSO 状态, 内容摘要
    std::vector<T>    size, capacity
    std::unique_ptr<T> 是否 nullptr, 指向地址
    std::shared_ptr<T> 是否 nullptr, 指向地址, use_count
    std::weak_ptr<T>   是否 expired, use_count, weak_count
    std::map<K,V>     size
    std::unordered_map<K,V> size

  L2 — 内部一致性检查（检测并发竞争/内存损坏）：
    vector            _M_start <= _M_finish <= _M_end_of_storage 指针顺序
    shared_ptr        use_count == 0 但 ptr 非空 → double free / UAF
                      负数 use_count → 控制块损坏
    weak_ptr          expired 但 ptr 非空 → managed object 已删除
    string            SSO 时 _M_string_length 超出 local capacity
    map               size 为负 / 根节点指针为空
    unordered_map     size 为负 / buckets 指针为空 / 负载因子异常

  SIGABRT 增强：读取 malloc_printerr 参数获取精确的 glibc 堆错误信息
  （如 "free(): double free detected in tcache 2"）。

  实现：每个 STL 类型对应一个 Inspector 类，直接通过 GDB Python API
  解析内存布局，离线可测（MockGdbValue）。