eBPF 程序为什么过不了验证器：从状态空间理解限制

eBPF 程序过不了验证器，往往不是因为源码“太长”，而是验证器无法在有限分析预算内证明所有可能路径都安全。它会模拟指令执行，跟踪寄存器类型、标量范围、栈槽、空值状态和分支条件；循环范围越宽、路径越多、各路径状态越难合并，需要探索的状态空间就越大。

排查时不要只删几行代码。先从日志里找到第一个“证明信息丢失”的位置：指针是否仍有合法类型，范围是否被约束，空值是否已排除，栈槽是否初始化；若安全性都能证明但复杂度仍高，再缩小循环上界、合并分支或拆分程序边界。

Linux 内核验证器文档：https://docs.kernel.org/bpf/verifier.html

我第一次卡住的地方：源码短不等于状态少

我最早排查这类问题时，直觉是看 C 文件有多少行、编译后有多少条 BPF 指令。后来才意识到，验证器面对的规模更像“同一指令位置可能出现多少种状态”。一个二选一分支不一定麻烦，但它放进循环后，又叠加标量范围、指针边界和栈值差异，就可能产生大量组合。

Linux 内核文档描述了两层核心工作：先检查控制流和不可达代码，再沿可能路径模拟每条指令对寄存器与栈的影响。内核需要证明程序会终止、不会读未初始化值、不会越界访问，也不会把普通标量当成可信指针使用。验证器拒绝的是“无法证明安全”的程序，而不一定是开发者主观上认为危险的程序。

因此我会先分开三个概念：

验证器真正跟踪的是状态，不只是指令

在某个指令位置，验证器记录的不只是“走到了这里”。寄存器可能是 NOT_INIT、标量或某类指针；标量还带有有符号和无符号最小/最大范围，以及按位未知信息。map 查询返回值可能处于“map value 指针或 NULL”状态，只有经过显式空值判断后，非空分支中的类型才会收窄为可解引用的 map value 指针。

栈也属于状态的一部分。某个路径写过的栈槽，在另一条路径上可能仍未初始化；溢出到栈的寄存器还携带原来的类型与范围。只要后续读取依赖这些差异，验证器就不能轻易把两条路径当成同一状态。

状态缓存和剪枝是控制复杂度的关键。验证器到达某个检查点时，会比较过去在同一位置出现过的状态；如果先前已经接受的状态足以覆盖当前更受约束的状态，当前分支就可以剪掉。这个比较同时考虑寄存器和栈，因此“看起来相同”的两条源码路径，也可能因为一个未使用寄存器或栈槽仍然活跃而无法合并。

哪些结构最容易让状态空间膨胀

我通常先找四类结构：输入范围过宽的循环、循环体内多层分支、不同路径上类型不同的指针，以及只有部分路径初始化的栈变量。它们单独出现未必失败，叠在一起才是最常见的复杂度来源。

static __always_inline int scan_bytes(
    const unsigned char *data,
    const unsigned char *data_end,
    unsigned int requested)
{
    unsigned int hits = 0;

    // requested 若来自外部数据且范围很宽，循环会带来大量候选状态
    for (unsigned int i = 0; i  data_end)
            break;
        if (data[i] == 0xff)
            hits++;
    }

    return hits;
}

这个片段不应被简单解读成“一定被拒绝”。实际结果取决于目标内核、编译结果、调用点传入的范围以及验证器能否收窄变量。但它展示了典型压力：requested 的可能值越多，循环体又含越界分支和内容分支，验证器需要考虑的状态组合就越多。

有界循环只证明循环最终会停止，不代表验证成本固定。内核相关文档提醒，循环体指令、分支和上界共同计入复杂度；一个宽范围整数即使语义上是合法上界，也可能让探索量迅速扩大。相反，早期的空值和边界检查通常会收窄类型或范围，为后续访问提供更强证明。

我更常用的修复：先缩范围，再减少路径差异

相比盲目加 #pragma unroll，我更愿意先把业务允许的最大扫描量写成验证器能看见的常量约束。展开循环会增加静态指令，未必适合本来就较大的程序；显式钳制范围则直接减少验证器需要考虑的迭代状态。

#define MAX_SCAN_BYTES 32

static __always_inline int scan_bytes_bounded(
    const unsigned char *data,
    const unsigned char *data_end,
    unsigned int requested)
{
    unsigned int hits = 0;
    unsigned int limit = requested;

    // 把外部宽范围输入钳制到业务真正需要的最大值
    if (limit > MAX_SCAN_BYTES)
        limit = MAX_SCAN_BYTES;

    for (unsigned int i = 0; i  data_end)
            break;
        if (*cursor == 0xff)
            hits++;
    }

    return hits;
}

同样的原则也适用于 map 返回值：先判空，再在非空分支内访问；适用于 packet 指针：先做 data_end 检查，再解引用；适用于栈：在所有能到达读取点的路径上初始化。修复目标不是讨好某条错误字符串，而是让类型和范围证明在控制流中保持清晰。

struct counter *value = bpf_map_lookup_elem(&counters, &key);

// 空值检查把“指针或 NULL”收窄为可访问的 map value 指针
if (!value)
    return XDP_PASS;

// 只有在非空分支里才读写 map value，验证器可保留正确指针类型
__sync_fetch_and_add(&value->packets, 1);

如果多个分支最终执行同一段安全检查，可以把检查提到公共位置，减少每条路径携带不同状态进入后续代码的机会。对我来说，这是状态空间视角最实用的收获：代码重构的目标从“少几行”变成“让更多路径在关键位置等价”。

程序仍然很大时，拆分边界而不是隐藏复杂度

当单个程序同时负责解析、过滤、统计和策略匹配，分支组合自然会增加。可以把可独立证明的逻辑整理为子程序；在支持函数级验证的内核上，某些全局 BPF 函数能被独立验证，但参数信息会更保守，因此函数内部往往需要补充自己的检查。

更彻底的边界是 tail call：目标是另一个独立加载、独立验证的 BPF 程序，各自拥有自己的复杂度预算。它适合天然分阶段的协议或策略处理，但不是绕过安全检查的捷径；每个目标程序仍必须单独通过验证，跨边界的数据也要通过明确的 map 或上下文元数据传递。

循环本身也有多种表达方式。较新的内核可能提供 bpf_loop、迭代器或特定 helper，用受控回调或状态封装避免对巨大迭代范围逐轮展开分析。是否可用取决于目标内核、程序类型和 helper 支持，部署前应以目标环境的 BTF、feature probe 和官方文档为准。

读取日志：围绕第一个失去证明的位置修复

验证器日志的格式会随内核演进，不能把某一版的行号和字段名写死。bpf() 的 BPF_PROG_LOAD 接口可通过 log_level、log_buf 和 log_size 取得多行日志；使用 bpftool 时，可以在隔离的调试环境中打开 debug 输出并保存完整信息。

# 在有相应权限的调试环境中加载并把诊断信息保存到文件
sudo bpftool -d prog load ./filter.bpf.o /sys/fs/bpf/filter 2>verifier.log

# 从日志开头检查首个类型、范围、空值或复杂度异常位置
sed -n '1,220p' verifier.log

我的阅读顺序是：先看第一处拒绝对应的指令和源码行，再向上追寄存器类型与范围，确认每条可达路径都做了同样的检查；只有安全证明完整后，才观察处理指令数、状态数和剪枝效果。日志缓冲区过小还可能导致信息不完整，直接使用 libbpf 或自定义加载器时应为日志预留足够空间。

验收不以“这次恰好加载成功”结束。还要在目标内核版本和实际程序类型上复查：输入上界是否符合业务、边界检查是否覆盖所有解引用、map 指针是否判空、栈变量是否全路径初始化，以及拆分后的程序是否保持原有策略语义。

相关问题

验证器复杂度限制等于源程序指令上限吗？ 不等于。内核文档还描述了探索指令数、每指令状态数、分支和调用等内部限制；同一条静态指令可能在不同状态下被多次分析。

有界循环为什么仍可能失败？ 有界只证明会终止。上界范围、循环体分支、指针与栈状态会共同决定需要探索的状态数量。

把函数全部标成 always_inline 能解决吗？ 不一定。内联可能让调用点信息更具体，也可能增加静态指令和重复逻辑。应根据日志和目标内核的函数验证能力选择，而不是机械内联。

tail call 是不是可以绕过验证器限制？ 不是。它把逻辑分成独立程序，每个程序分别验证；安全规则并没有消失，只是程序边界和复杂度预算变得独立。