Clang Static Analyzer

基于符号执行的源代码级静态分析工具

1. 概述

Clang Static Analyzer（CSA）是 LLVM 项目中的一个源代码分析工具，能够在不运行程序的情况下，通过对源代码的深度语义分析找出 Bug。它实现了路径敏感（path-sensitive）的、过程间（inter-procedural）的符号执行（symbolic execution）。

2. 架构总览

分析流程的核心步骤：

1. Clang 前端解析源码，生成 AST（抽象语法树）和 CFG（控制流图）。
2. CoreEngine 沿 CFG 边进行符号执行，维护 ProgramState（包含符号存储、环境映射和检查器通用数据）。
3. 每个程序点产生一个 ExplodedNode，全部节点构成 ExplodedGraph——即符号执行的状态空间。
4. Checker 通过访问者模式注册回调（如 checkPreCall、checkBind、checkDeadSymbols），在符号执行的关键节点被唤醒。
5. Checker 发现问题后调用 BugReporter，生成包含完整执行路径的 Bug 报告。

3. 检查器（Checkers）

检查器是 CSA 真正「找 Bug」的模块。它们被组织为多个包（package），每个包各有侧重。

3.1 默认检查器（Default Checkers）

3.2 实验性检查器（Alpha Checkers）

3.3 检查器选择指南

# 仅使用默认检查器（安全、适合CI）
scan-build make

# 启用所有核心检查器
scan-build --enable-checker core,deadcode,nullability make

# 启用所有检查器（含alpha）
scan-build --enable-all-checkers make

# 精细控制：启用安全包，禁用特定检查器
scan-build -enable-checker security -disable-checker security.insecureAPI.gets make

4. 使用方法

4.1 scan-build —— 最简入门

# 安装 clang 和 scan-build
sudo apt install clang clang-tools   # Debian/Ubuntu
brew install llvm                     # macOS

# 分析一个项目
scan-build cmake -B build .
scan-build cmake --build build

# 查看 HTML 报告
scan-view /tmp/scan-build-2026-07-06-*/

4.2 直接调用 clang --analyze

# 单文件分析
clang --analyze -Xanalyzer -analyzer-checker=core file.c

# 启用多检查器
clang --analyze -Xanalyzer -analyzer-checker=core,security,deadcode file.c

# 输出为 plist 格式（供 Xcode 使用）
clang --analyze -Xanalyzer -analyzer-output=plist file.c

4.3 CodeChecker —— 大规模分析

# CodeChecker 提供 Web UI、增量分析、结果存储
pip install codechecker

# 创建编译数据库
CodeChecker log -b "make" -o compilation_database.json

# 运行分析
CodeChecker analyze compilation_database.json -o reports

# 启动 Web 查看器
CodeChecker server &
CodeChecker store reports --name my_project
# 打开 http://localhost:8001

4.4 抑制误报

// 方法1: 源码注解 —— 抑制特定检查器的警告
#ifdef __clang_analyzer__
#define SUPPRESS __attribute__((suppress))
#else
#define SUPPRESS
#endif

void example() {
  int *p SUPPRESS = NULL;  // 此处不报告 core.NullDereference
}

// 方法2: 断言引导分析器
#include <assert.h>
void safe_use(int *p) {
  assert(p != NULL);  // 分析器利用此断言，不再报告空指针
  *p = 42;
}

5. 内部原理

5.1 符号执行引擎

Clang Static Analyzer 的核心是一种路径敏感、流敏感的符号执行。关键组件：

5.2 路径爆炸与缓解策略

符号执行面临的核心挑战是路径爆炸——随着分支和循环，执行路径指数增长。CSA 通过以下策略缓解：

• 函数摘要（Function Summary）：为函数生成摘要，避免在调用点反复展开。
• 循环展开限制：循环体默认最多展开4次，之后宽化（widen）为未知状态。
• 路径合并（Path Merging）：在控制流汇聚点合并相似状态。
• 节点缓存：对 (CFG位置, ProgramState) 对去重，避免重复分析。
• 分析器配置调优：-analyzer-config max-nodes=150000 控制每个函数的探索上限。

5.3 跨翻译单元分析（CTU）

默认情况下，CSA 对每个翻译单元（.c 文件）独立分析。对于跨文件 Bug（如在一个文件中分配、在另一个文件中释放），这有局限。CTU 分析在调用外部函数时加载其函数摘要进行分析，极大地扩展了分析范围。

# 分两步启用 CTU
# 步骤1: 生成 AST 并收集外部定义
clang --analyze -Xanalyzer -analyzer-config experimental-enable-naive-ctu-analysis=true \
      -Xanalyzer -analyzer-config ctu-dir=ctu-dir file.c

# 步骤2 (CodeChecker): 自动处理
CodeChecker analyze compile_commands.json --ctu

6. 编写自定义检查器

Clang Static Analyzer 的一个核心优势是其可扩展性。编写一个新检查器只需继承 Checker 基类并注册回调。

6.1 最小检查器示例

// 检查所有超过 64 个字符的函数名
#include "clang/StaticAnalyzer/Core/Checker.h"
#include "clang/StaticAnalyzer/Core/PathSensitive/CheckerContext.h"
#include "clang/StaticAnalyzer/Core/BugReporter/BugType.h"

using namespace clang;
using namespace ento;

namespace {
class LongFunctionNameChecker : public Checker<check::ASTDecl<FunctionDecl>> {
  std::unique_ptr<BugType> BT;
public:
  LongFunctionNameChecker()
    : BT(std::make_unique<BugType>(this, "过长函数名", "代码风格")) {}

  void checkASTDecl(const FunctionDecl *FD, AnalysisManager &Mgr,
                    BugReporter &BR) const {
    if (FD->getName().size() <= 64) return;
    PathDiagnosticLocation Loc =
        PathDiagnosticLocation::create(FD, Mgr.getSourceManager());
    BR.EmitBasicReport(FD, this, "过长函数名",
                       "代码风格",
                       "函数名超过64字符，建议缩短。",
                       Loc);
  }
};
}

// 注册检查器
void ento::registerLongFunctionNameChecker(CheckerManager &Mgr) {
  Mgr.registerChecker<LongFunctionNameChecker>();
}

6.2 常用的 Checker 回调

7. 与其他工具对比

与 LLVM 体系内其他工具的关系

8. 污点分析（Taint Analysis）

CSA 内置污点分析框架，可用于追踪来自不可信源（用户输入、网络数据等）的数据流，检测注入类漏洞。

// 需要启用实验性检查器
clang --analyze -Xanalyzer \
  -analyzer-checker=optin.taint.TaintedAlloc,\
alpha.security.ArrayBoundV2 file.c

污点传播路径示例：

// CSA 能追踪以下完整路径并报告 Bug
int size = atoi(argv[1]);        // 污点源：外部输入
int *buf = malloc(size * 4);     // TaintedAlloc：污点数据控制分配大小
buf[size] = 0;                   // ArrayBoundV2：可能的越界写入

9. 最佳实践

参考资源

• Clang Static Analyzer 官方文档
• 项目主页（含 scan-build 使用指南）
• 完整检查器列表
• LLVM 源码 — StaticAnalyzer
• CodeChecker 文档
• 开发者文档（编写自定义检查器）