Wireshark Lua插件自定义

       近期工作中刚好有实现自定义的UDP相关协议，用Wireshark时只能给出原始的字节流，观察起来确实十分不便，为此研究了一下Wireshark的Lua插件实现，在此记录一下。

---

一、配置执行Lua脚本

       首先通过菜单中的"About Wireshark"查看一下Wireshark对应Lua引擎的支持情况，如下图所示：

        默认安装路径下会有一个init.lua(Mac环境下的路径在/Applications/Wireshark.app/Contents/Resources/share/wireshark)，它是Wireshark启动过程中执行的第一个lua脚本，一般来说我们可以在此文件中添加dofile函数调用其它lua脚本，从而实现lua扩展插件，dofile是lua基础库提供函数，用于调用执行其它lua脚本，例如init.lua默认最后一句是：

dofile(DATA_DIR.."console.lua")

        该console.lua的功能是在主菜单中Tool下创建一个Lua子菜单，提供一些Lua Console等功能。

二、解析前的准备

       在解析开始前，要先理清一下要解析的协议编码方式。以UDP承载的TLV消息为例，消息格式如下所示：

      而TLV字段顾名思义包含Tag、Length和Value三个部分：

       我们定一个Tag为1的TLV代表一个value参数，其值为4字节整数， Tag为2的TLV代表一个content参数，其值为UTF字符串。使用UDP消息固定向2555端口发送，抓包的示例如下所示：

三、Wireshak Lua API

         Wireshark的Lua API可以参考其用户手册的第10章和第11章，在写具体脚本时需要不时地进行查询。

         主要需要了解的基本对象和方法包括：

         1. Proto表示协议

         2. ProtoField表示协议对应字段

         3. Proto的dissector方法用于实际的解析工作，包含三个入参buffer（Tvb）、pinfo（Pinfo）和tree（TreeItem），其中buffer表示原始的数据字节缓存、pinfo和tree代表的显示区域如下：

         4. DissectorTable协议解析表

         5. Dissector协议解析器

         了解上述概念后可以查一下对应用户手册详细了解一下，后续就可以开始实际的Lua脚本编写。

四、Lua脚本

-- 协议声明
local dream_proto = Proto("Dream-Proto","UDP Protocol for Test","Dream UDP Protocol")
-- 协议字段定义
local f_msg_type = ProtoField.uint16("dream.msg_type","MsgType",base.DEC, {[1] = "DemoMessage"})
local f_msg_len = ProtoField.uint16("dream.msg_length", "MsgLength", base.DEC)
local f_msg_id = ProtoField.uint32("dream.msg_id","MsgId", base.DEC)
local f_value = ProtoField.uint32("dream.value", "TLVValue", base.DEC)
local f_content = ProtoField.string("dream.content", "TLVContent")
-- 协议字段注册
dream_proto.fields = {f_msg_type,f_msg_len,f_msg_id,f_value,f_content}

local arr_msg_type = {
    [1] = "DemoMessage"
}

-- 协议解析逻辑
function dream_proto.dissector(buffer,pinfo,tree)
    -- 设置Wireshark包列表中Protocol列所对应的该协议名称
    pinfo.cols.protocol:set("Dream-UDP")

    local buffer_len = buffer:len()
    -- 在具体包信息创建下新建Dream UDP Message协议项根节点
    local proto_tree = tree:add(dream_proto, buffer(0, buffer_len), "Dream UDP Message")

    local offset = 0

    local msg_type = buffer(offset, 2):uint()
    -- 在协议项根节点中增加解析后的MsgType字段
    proto_tree:add(f_msg_type, buffer(offset, 2))
    offset = offset + 2

    -- 在协议项根节点中增加解析后的MsgLength字段
    proto_tree:add(f_msg_len, buffer(offset,2))
    offset = offset + 2

    local msg_id = buffer(offset, 4):uint()
    -- 在协议项根节点中增加解析后的MsgId字段
    proto_tree:add(f_msg_id, buffer(offset,4))
    offset = offset + 4

    -- 设置Wireshark包列表中Info列所对应的该协议包的描述信息
    pinfo.cols.info:set(arr_msg_type[msg_type].." with id="..msg_id)

    while(offset < buffer_len)
    do
        local tag = buffer(offset, 2):uint()
        offset = offset + 2

        local len = buffer(offset, 1):uint()
        offset = offset + 1

        if tag == 1 then
           -- 在协议项根节点中增加解析后的Value字段
           proto_tree:add(f_value, buffer(offset, len))
        elseif tag == 2 then
           -- 在协议项根节点中增加解析后的Content字段
           proto_tree:add(f_content, buffer(offset, len))
        end
        offset = offset + len
    end
end

-- 将协议分析脚本注册至UDP 2555端口
DissectorTable.get("udp.port"):add(2555,dream_proto)

有了之前的基础和上面注释，相信上面的代码不难理解，在init.lua中dofile调用该脚本，重启wireshark后，解析结果如下所示：

除了内容展示外，根据字段过滤的功能实际也已经加上，如下图所示：

例如根据dream.msg_id过滤如下所示：

五、端口复用

        在实际的过程中，我们很有可能希望通过消息的某些特征进行协议的解析，例如UDP消息以某固定字节数组开始，而不是通过上述的绑定2555端口的方式。对于这种需求的实现，很遗憾没有目前我暂时没有找到合适的方式，有线索说可以通过heuristic dissector来实现，但是试验了一下似乎没有什么效果，具体可以参照一下stackoverflow中的问题how-to-get-wireshark-heuristic-dissector-work。

        除了上述这种需求外，还可能遇到端口复用的情况，比如在实际过程中，2555端口除了接收上述定义的这种TLV包之外，还接收了其它协议的包，我们以SIP协议为例子，如何处理这种状况呢？可以在dissector函数中调用其它dissector来进行，示例如下：

local sip_dissector = Dissector.get("sip")
......
if .....
else
   sip_dissector:call(buffer,pinfo,tree)
end
.......

         具体可以参照How wireshark dissect correctly with two lua dissectors on the same port。

六、其它技巧

        在Wireshark Tools菜单的Lua子菜单中打开Console和Evaluate，可以在Evaluate中输入lua进行一定的试验和打印（使用debug函数），示例如下所示：