简介一份用于在 Lua 脚本中调用 nDPI 深度包检测库的概念验证程序面向熟悉 C 语言并希望扩展脚本化协议识别能力的开发者。程序通过自行封装的 libndpilua 库将 nDPI 的检查能力暴露给 Lua 环境能够读取 pcap 抓包文件对每个数据包进行协议识别并在成功匹配时触发由用户定义的 Lua 回调函数回调函数以协议标识符和数据包指针为参数方便针对不同协议编写处理逻辑。整个压缩包共包含十九个文件以十个头文件为主另有 C 源码、Lua 脚本、Makefile 编译脚本、动态库文件以及一个 pcap 示例文件包体仅约 951KB非常适合快速理解 DPI 工作流程。资源目前已有三百二十人学习使用适合作为学习 nDPI 与 Lua 绑定技术的入门资料。读者可以从中借鉴将 C 库封装为 Lua 模块的通用做法并自由修改回调与入口脚本用于自定义协议检测实验或教学演示。1. ndpi-lua 这类的需求来源很实际拿到一个 pcap 包想在 Lua 里验证 nDPI 深度包检测库对某个协议的识别结果。nDPI 本身是 C 语言写的库自带命令行测试工具但每改一次检测参数都要重新编译 C 源码验证一个样本往往要折腾十几分钟。于是有人写了个几百行的 Lua 脚本把初始化、喂包、取结果全部封装成函数验证样本从编译一次跑一次变成改配置直接看输出。这个玩具程序干的就是这件事不追求性能和覆盖率只求用最小代价把 nDPI 的检测能力暴露给 Lua 调用方。适合做协议识别二次开发、需要快速验证特征库效果的人也适合刚接触 nDPI 想搞清楚检测流程的人。2. 绑定层在干什么nDPI 的流式检测流程与 Lua 接入方式要在 Lua 里用 nDPI先要理解它的接口是给 C 语言用的流式处理模型。它不是调用一次就返回结果的函数库而是要求调用方自己管理流的状态、包的方向和特征库的配置。不先搞清楚这些脚本里每个 ffi 调用都是黑匣子出错时根本不知道往哪查。2.1 检测单元是「流」flow 表与状态机的运转方式nDPI 不会对单个包独立给出结果它把五元组相同的包归到一条流里用内部状态机逐包推进。调用方只需要按顺序把包喂进去检测器内部会完成端口启发、内容匹配、状态机确认这三级判断。三级判断的顺序很关键。端口启发最快比如看到 443 先猜 TLS内容匹配会读报文 payload找特征串状态机确认一般要看到握手过程比如 TLS 的 ClientHello 和 ServerHello 都出现后才确认。所以同一个样本只喂一个包和喂完整交互过程结果可能是 guessed 和 confirmed 的差别。2.2 检测器与流对象生命周期管理是绑定层最容易出错的地方nDPI 的 C API 里有两条生命线检测器模块和流对象。检测器用 ndpi_init_detection_module() 创建用 ndpi_exit_detection_module() 销毁每条流用专门的结构体表示处理完必须释放。把这两个对象的生命周期封装好Lua 侧才不容易泄漏。在 Lua 里最直接的方式是用 ffi.gc 给指针挂上析构函数这样 GC 回收指针时自动调用释放函数。但要注意 ffi.gc 只对 cdata 对象生效如果你把指针转成了 lightuserdatagc 就不会触发泄漏就会悄悄发生。另一个容易忽略的点是不同连接必须使用不同的流对象如果把多条连接全塞进同一个 flow状态机会乱套识别结果互相污染。玩具程序最省事的做法是每个包临时创建一个 flow测完就释放反正是验证特征库而不是做在线检测。2.3 Lua 绑定的两条路线FFI 与 C 扩展的取舍把 C 库接进 Lua 有两种常见路线。一条是 LuaJIT FFI在 Lua 里用 cdef 声明 C 函数原型和结构体直接调用不需要编译额外的模块另一条是写 C 扩展用 Lua C API 封装 nDPI 的调用细节编译成 so 后 require。FFI 路线的优势是开发快、部署简单改完声明马上能跑特别适合玩具程序这种快速验证场景缺点是自定义回调函数很难注册结构体布局必须和库逐字节一致。C 扩展路线的优势是控制力强能塞进自定义 C 逻辑结构体转换可控缺点是每次 nDPI 升级都要重新编译一套 so验证成本高。玩具程序选 FFI 更合理等验证出哪个协议识别不稳再针对性地写 C 扩展也不迟。2.4 最小绑定声明初始化、喂包、释放的一块骨架下面的声明是玩具程序的基础模块不展开完整结构体用不透明指针方式暴露 C 对象-- ndpi_bind.lua绑定层最小声明 local ffi require(ffi) ffi.cdef[[ typedef struct ndpi_detection_module_struct ndpi_detection_module_struct; typedef ndpi_detection_module_struct* ndpi_detection_module; ndpi_detection_module ndpi_init_detection_module(void); void ndpi_exit_detection_module(ndpi_detection_module mod); typedef struct ndpi_flow_struct ndpi_flow_struct; typedef ndpi_flow_struct* ndpi_flow; ]] local M {} function M.init() local mod ffi.C.ndpi_init_detection_module() if mod nil then error(ndpi init failed) end return ffi.gc(mod, ffi.C.ndpi_exit_detection_module) end return M逻辑说明ndpi_init_detection_module 返回不透明指针用 ffi.gc 挂上销毁函数Lua 变量失去引用时自动回收检测器避免手动调用 exit 造成遗漏。这个写法减少了 Lua 侧的清理代码也让初始化与销毁必然配对。参数说明这里没有展开 ndpi_detection_module_struct 的内部字段因为该结构体在不同版本里差异很大展开后必须逐字节对齐一旦错了会出现很难查的段错误。用不透明指针后Lua 侧只能通过 nDPI 提供的函数操作它版本升级时绑定代码基本不用改。这段代码可以直接存成 ndpi_bind.lua 作为基础模块后面所有测试脚本只依赖这个模块暴露的函数。3. 跑通第一个 ndpi-lua 脚本环境准备、pcap 读取与最小实现3.1 环境准备三个组件和版本对齐需要 LuaJIT 2.1 和一份能用的 nDPI 库。nDPI 的库版本决定了 cdef 声明怎么写所以先锁定版本再去配环境。验证加载是否成功是第一步用下面两条命令# 确认 LuaJIT 可用 luajit -v # 确认 libndpi.so 在链接路径里 ldconfig -p | grep ndpi如果没有输出用 export LD_LIBRARY_PATH/path/to/ndpi/lib:$LD_LIBRARY_PATH 指过去再试。逻辑说明nDPI 库如果在默认路径FFI 的 ffi.load(ndpi) 可以直接找到如果不在需要先设置 LD_LIBRARY_PATH这个环境变量对 LuaJIT 的 ffi 库同样生效。参数说明把库放进 /usr/local/lib 后要执行 ldconfig 刷新缓存否则即使文件存在也可能报找不到。用 ldconfig -p | grep ndpi 确认缓存里真的有这条才是真的加载到了这一步很多人跳过后面就莫名报错。3.2 纯 Lua 读 pcap解析文件头与包记录玩具程序最常见的数据来源是 pcap 文件。纯 Lua 解析 pcap 不依赖额外库只需要处理全局头和包记录头两个结构。下面是个按小端解析的版本-- read_pcap.lua返回包列表每个包是从链路层开始的原始字节 local function read_pcap(path) local f io.open(path, rb) if not f then return nil, cannot open .. path end local gh f:read(24) if not gh or #gh 24 then f:close(); return nil, bad global header end -- 标准 pcap 的 magic 是 0xa1b2c3d4按小端拆解 local magic string.byte(gh, 1) string.byte(gh, 2) * 256 string.byte(gh, 3) * 65536 string.byte(gh, 4) * 16777216 if magic ~ 0xa1b2c3d4 then f:close() return nil, only little-endian pcap supported end local link_type string.byte(gh, 21) string.byte(gh, 22) * 256 local packets {} while true do local rh f:read(16) if not rh or #rh 16 then break end local caplen string.byte(rh, 9) string.byte(rh, 10) * 256 string.byte(rh, 11) * 65536 string.byte(rh, 12) * 16777216 local data f:read(caplen) if not data then break end packets[#packets 1] data -- pcap 每条记录按 4 字节对齐跳过填充字节 local pad (4 - (caplen % 4)) % 4 if pad 0 then f:seek(cur, pad) end end f:close() return packets, link_type end逻辑说明pcap 全局头 24 字节重要的只有 magic判断字节序和 link_type判断链路层类型链路类型 1 表示 Ethernet。包记录头 16 字节caplen 在偏移 8 处表示这段记录里实际存的包字节数。读完后按 4 字节对齐跳过填充不然下一个包记录头会读错位置。参数说明这段代码只支持小端 pcap也就是绝大多数抓包工具默认的格式。如果遇到大端 pcapmagic 会被读成 0xd4c3b2a1此时需要把整个文件按字节反转处理。另外这个解析器没处理 pcapng现在有不少抓包工具默认输出 pcapng扩展名是 pcap 但内容是 pcapng如果读出来第一个包的 caplen 是怪异值基本就是 pcapng 混进来了需要先用工具转成标准 pcap。3.3 把第一个包喂进 nDPI简化版调用链有了包列表接下来就是初始化检测器、创建流、喂包、读结果四步。下面是一段极简的调用脚本-- demo.lua读取 pcap 后逐包调用 nDPI打印协议 ID local bind require(ndpi_bind) local read_pcap require(read_pcap).read_pcap local packets, link_type read_pcap(arg[1]) if not packets then io.stderr:write(tostring(link_type) .. \n) os.exit(1) end local mod bind.init() for i, raw in ipairs(packets) do -- 略过链路头只把 IP 部分喂给 nDPI -- 简化场景链路类型 1Ethernet、不含 VLAN local ip_pkt raw:sub(15, -1) -- 这里调用 process_packet完整参数以实际版本的 nDPI 头文件为准 -- bind.process_packet(mod, flow, ip_pkt, #ip_pkt, 0) end逻辑说明process_packet 的参数里时间戳相关的 tick 值回放 pcap 时如果全部填 0nDPI 内部的时间推进逻辑会失真对依赖时序的协议识别有影响。遇到识别结果异常时优先检查是不是 tick 传错了。参数说明nDPI 的 process_packet 参数在不同版本里有差异写玩具程序时先只传最基本的包指针、包长度和 tick其他高级参数一律填 0 或 nil跑通后再对照头文件补全不要一上来就照抄旧项目的调用。3.4 链路类型不是 Ethernet 时跳过头部长度的处理pcap 的 link_type 有几十种。最常见的 1 是 Ethernet14 字节头101 是 raw IP没有链路头113 是 Linux cooked capture16 字节头。读取包的时候要根据 link_type 计算偏移不能写死 14。local function ip_offset(link_type) if link_type 1 then return 14 end if link_type 101 then return 0 end if link_type 113 then return 16 end return 14 -- 默认按 Ethernet 处理 end逻辑说明把链路头直接截掉再把 IP 包喂给 nDPI是因为 nDPI 本身处理的是 IP 层及以上的特征。链路层类型错误时IP 包起始位置错一个字节特征匹配全乱识别结果会变成 Unknown。参数说明VLAN 场景下 Ethernet 头是 18 字节多了 4 字节的 802.1Q 标签。如果样本带 VLAN要在 ip_offset 里额外判断 EtherType 字段碰到 0x8100 就多跳 4 字节。这个细节在真实流量里很常见抓包工具默认可能保留 VLAN 标签。4. 把协议 ID 变成人话检测结果的解析、参数调节与二次处理第一次跑通喂包只是开始真正花时间的是读懂 nDPI 返回的结果。协议 ID 是一个整数直接打印出来看不出含义需要映射成名字还要分清确认结果和猜测结果。4.1 协议 ID 映射nDPI 内部协议表与 Lua 侧查询nDPI 的协议 ID 是一个整数从 0 到几百对应一张内置协议表。查名字的典型代码是ffi.cdef[[ const char* ndpi_get_protocol_name(uint32_t id); ]] local name ffi.string(ffi.C.ndpi_get_protocol_name(id))逻辑说明ffi.string 把 C 字符串转成 Lua 字符串。如果不转print 出来是 cdata 地址不是文字。很多人第一次跑就卡在这里以为自己拿到了错误数据其实只是没做转换。参数说明如果 nDPI 版本里这个函数带长度参数比如 ndpi_get_protocol_name(id, buf, len)要按实际原型调整。用 ffi.string 时记得处理 nilID 非法时有的版本返回 NULL直接 ffi.string(NULL) 会让进程崩溃。4.2 confirmed 与 guessed两个协议 ID 字段怎么配合nDPI 的 flow 结构里检测结果分为确认协议和猜测协议两部分。喂单个包时经常只有猜测值。玩具程序要把两个都打出来local confirmed bind.get_confirmed(flow) local guessed bind.get_guessed(flow) local name_c confirmed 0 and ffi.string(bind.get_proto_name(confirmed)) or ? local name_g guessed 0 and ffi.string(bind.get_proto_name(guessed)) or ? print(confirmed:, confirmed, name_c, guessed:, guessed, name_g)逻辑说明常见的错误是只读 confirmed把 guessed 忽略。nDPI 在包不完整时经常只填 guessed比如看到 443 端口但还没看到握手包这时 guessed 是 TLS 而 confirmed 是 Unknown。打印两个字段能让你知道是特征没命中还是包不完整。参数说明两个 ID 用的是同一个协议表只是结果可信度不同。当确认值是 Unknown 时参考猜测值能省很多排查时间。4.3 端口启发式、子串匹配与检测开关三个调参位置nDPI 初始化的配置对象可以开关多个检测项。调试时建议全开验证生产配置时再逐步关闭。下表总结了各开关对识别结果的影响| 配置项 | 开启时的影响 | 关闭时的典型表现 | | 端口启发式 | 看到 443 先猜 TLS后续可被覆盖 | 未握手流量直接 Unknown | | 子串匹配 | 在 payload 里找特征串识别通用协议 | 依赖报文内容的协议识别率大降 | | 状态机确认 | 需要完整握手才会 confirmed | 单包结果长期停在 guessed |这些开关通常在初始化时通过配置值控制具体字段名以你锁定的 nDPI 版本头文件为准。调试协议识别问题时先把三个都打开如果还是 Unknown再逐个关闭对比能快速定位是哪个检测器在起作用。4.4 分片与重传玩具程序容易忽略的两个干扰项IP 分片会让 nDPI 特征匹配失败因为特征串被拆到两个包里。重传会导致同一段内容处理两次。测试时如果 pcap 里有分片喂包顺序和偏移不对结果会偏差很大。处理分片不能靠玩具程序本身一般有两种方式一是测试前用工具把分片包重组二是只选取完整会话里的非分片包做验证。我一般会写个小过滤器判断 IP 头的 fragment offset偏移非 0 的包直接跳过。参数说明IP 头偏移字段在 IP 头第 6、7 字节Lua 侧用 string.byte(ip_pkt, 7) 取低位非 0 就说明是分片包跳过即可。4.5 二次处理把结果存成可读文件玩具程序跑完一批 pcap最好把结果落到文件里不然每次都在终端里翻。写法很简单local out io.open(result.txt, w) for i, raw in ipairs(packets) do -- 伪代码这里替换成真实调用 local id bind.get_guessed(flow) local name ffi.string(bind.get_proto_name(id)) out:write(string.format(%d\t%d\t%s\n, i, id, name)) end out:close()逻辑说明每行输出包序号、协议 ID 和协议名方便后续用脚本统计。参数说明如果样本里混杂多条流建议在输出里加上五元组信息否则无法区分同一序号对应的是哪条连接。只输出协议名不加上下文排查问题时要来回翻文件效率很低。5. 踩坑记录Lua 调 nDPI 的 5 个典型事故与修复这一个章节写给真正动手跑的人。以下问题是我在测试 Lua 绑定 nDPI 时真实遇到过的每条都按现象、原因、解决三个部分展开。5.1 加载不到 libndpi.so符号表与路径问题现象ffi.load(ndpi) 报 libndpi.so: cannot open shared object file或者明明安装了库还是加载失败。原因库不在搜索路径或者搜索路径里有另一个架构的版本。偶尔是头文件和库版本不同步头文件里有的函数在 so 里没有导出。解决先跑 ldconfig -p | grep ndpi 确认缓存里有没有。没有就用绝对路径加载ffi.load(/absolute/path/libndpi.so)。注意绝对路径版本要先确认架构一致32 位库配 64 位 LuaJIT 会直接加载失败。加载成功后用 nm -D 查看导出符号确认要用的函数确实存在。5.2 识别结果全是 Unknown特征库和版本错位现象喂了明显的 HTTP 包结果永远是 Unknown没有任何 guessed 值。原因加载的库不是自己编译的那份特征表版本错乱或者编译时关闭了子串匹配开关导致大部分应用层协议检测失效。解决确认库来源最好自己从源码编一份放在独立目录。子串匹配被关闭时很多依赖 payload 特征的协议全部失效只剩端口启发式还在工作表现就是 Unknown 大量出现。用 nm 导出符号和头文件对比一下版本号或者直接在初始化时打印版本字符串能快速定位错位。5.3 段错误结构体声明与库布局不一致现象脚本跑起来偶尔段错误或者某个字段读出来是很大的随机整数。原因ffi.cdef 里声明的结构体和库实际编译时的布局不一致。nDPI 结构体版本之间会增删字段少声明一个字段后面所有字段偏移全错。解决最稳妥的办法是全部改成不透明指针不要直接访问结构体内部字段。实在要访问用 valgrind 跑一次崩溃点会直接指出是哪一行读越界了。另外不要拿旧博客里的 cdef 声明直接套新版本的库声明可以精简但字段顺序必须和头文件一致。5.4 单包测试永远拿到 guessed 协议现象只喂一个包时结果总是 guessed 或者 Unknown换成完整会话就正常。原因nDPI 的状态机需要看到完整握手流程才能确认协议。单包只能触发端口启发式拿到的自然是猜解结果而不是确认结果。另外如果时间戳 tick 一直传 0状态机的时间推进逻辑会失真。解决测试脚本要回放整个 TCP 会话至少覆盖握手阶段的前几个包。process_packet 的时间戳参数从 pcap 记录头里读出来传进去不要填 0。如果想快速验证特征库直接挑一个完整会话的 pcap而不是单独一个包。5.5 识别结果和其他工具对不上现象同一个 pcap别的工具能识别出 TLS这个玩具程序识别不出或者识别成 Unknown。原因特征库版本不同、配置开关不同或者对方读取了解密密钥。TLS 识别依赖握手包里的 SNI 和证书字段如果 pcap 只有加密报文没有握手过程任何深度包检测工具都识别不了具体服务。解决确认 pcap 里是明文还是加密流量。测试 TLS 识别时抓包要包含 ClientHello 和 ServerHello 全过程。如果只想验证协议检测器本身用明文协议比如 HTTP 和 DNS 做基准测试先确认绑定层没写错再测加密流量。6. 从玩具到工具把脚本改造成批量回归与性能观测玩具程序跑通单文件之后再往前走一步就是批量回归。把多个 pcap 样本放进一个目录每个样本标注期望的识别结果脚本自动跑完并统计通过率这是验证特征库改动最有效的方式。-- regression.lua批量校验协议识别结果 local cases { {http_sample.pcap, HTTP}, {dns_sample.pcap, DNS}, {tls_sample.pcap, TLS}, } local pass, fail 0, 0 for _, c in ipairs(cases) do local got detect(c[1]) -- detect 是玩具程序封装的主函数 local ok got c[2] print(c[1], got, ok) if ok then pass pass 1 else fail fail 1 end end print(string.format(pass%d fail%d, pass, fail))逻辑说明detect 函数把初始化、读包、喂包、取结果全部包起来每个用例独立调用互不影响。参数说明样本文件要选完整会话单个包样本会大量出现 guessed导致误判为失败。断言建议只比较协议名不要比较 ID因为 ID 在不同版本里可能变化。性能观测方面用 os.clock() 测每包处理耗时。注意单包耗时通常在微秒级循环次数太少时测不出来要多次运行取平均。我一般让同一批样本循环跑几遍用总耗时除以包总数得到单包平均处理时间。这个数字虽然不代表生产性能但能快速感知特征库改动是否拖慢了匹配速度。我现在的习惯是每次改 nDPI 特征库或绑定层之前先把现有样本的回归结果存一份基线改动后再跑一遍对比。玩具程序看似简陋却是这套工作流里最快能落地的一环。它不承担在线检测任务但能帮你把「识别得对不对」这个问题在半小时内给出答案。希望帮到你。本文还有配套的精品资源点击获取