Wireshark自定义Lua插件

背景：

常见的抓包工具有tcpdump和wireshark，二者可基于网卡进行抓包：tcpdump用于Linux环境抓包，而wireshark用于windows环境。抓包后需借助包分析工具对数据进行解析，将不可读的二进制数转换为可读的数据结构。
wireshark不仅可以作为抓包工具，还可以作为包解析工具。Wireshark针对常见协议都提供了对应的解析插件，
如: TCP、UDP、HTTP、SIP等；同时提供了自定义插件机制，用户可以基于此解析自定义消息。至于插件，wireshark支持C语言插件和Lua插件，Lua作为脚本不需要编译，方便调试，速度相对C语言较慢。由于抓包时可以根据条件过滤，且一般数据包分析在本地进行，这部分性能优势相对于Lua脚本的方便性可以忽略。
因此，本文的主体内容是介绍如何在Wireshark中开发自定义插件解析消息。

1.插件配置方式

1.1 配置protobuf加载路径

根据Wireshark->Preferences->Protocols路径进入配置页面(Windows中路径为 “编辑->首选项->Protocols” ):

勾选Load .proto files on startup选项，然后点击Edit按钮开始配置。添加proto文件所在文件夹，勾选"load all files"选项。
经过上述配置，已经为wireshark指定了查找proto文件的路径，后续在lua脚本中可直接使用proto文件。

1.2 配置lua脚本路径

根据Wireshark->About Wireshark->Folders路径进入配置页面(windows下路径为: 帮助->关于->文件夹):

添加或者查看个人Lua插件的存放位置，后面开发的插件需要存放到这个路径下才会生效。添加或者修改lua插件后，需要重新加载lua插件:"分析->重新载入Lua插件"或者通过快捷键Ctrl+Shift+L.

1.3 Lua console调试工具

在"Tools->Lua console"页面可以编写和执行Lua脚本，可用于调试:

说明：调试工具是开发Lua插件的关键，结合快捷键Ctrl+Shift+L，通过打印提示信息，可以快速定位和发现问题。

2.wireshark关于Lua API介绍

Lua语法请参考: Lua使用方式介绍

Lua API参考自: https://mika-s.github.io/wireshark/lua/dissector/2017/11/04/creating-a-wireshark-dissector-in-lua-1.html

这部分介绍wireshark为Lua脚本的API，以及根据如何使用这些API实现自定义Lua插件。介绍Lua API前，有必要对Wireshark页面进行介绍:

需要关注上图红色标注的区域，包括:column区、tree区、data区，后续API会操作这些区域。

2.1 定义协议

1. seong_protocol = Proto("seong", "seong description")
3. seong_protocol.dissector = function(buffer, pinfo, tree)
4. local subtree = tree:add(seong_protocol, buffer(),"Seong Message Data");
5. end
7. DissectorTable.get("tcp.port"):add(9003, seong_protocol)

复制代码

将上述Lua插件注册到环境后，可使用自定义的seong协议过滤消息，Wireshark页面显示如下：

定义协议需要三个步骤：定义Proto协议对象，为Proto对象添加解码器方法，将Proto对象与对应的端口进行绑定。
[1] 定义协议对象

1. seong_protocol = Proto("seong", "seong description")

复制代码

Proto作为构造参数用于创建Proto对象，接收两个参数，协议名称和协议描述。

[2] 为协议对象添加解析器
解析器函数:

1. seong_protocol.dissector = function(buffer, pinfo, tree)
2. local subtree = tree:add(seong_protocol, buffer(),"Seong Message Data");
3. end

复制代码

函数包括三个入参：
(1) buffer为二进制消息数据，可以通过类似buffer(0,2)方式从消息中截取字节数组；
(2) pinfo为数据包的元数据对象，包括消息大小、源地址/目标地址、大小、时间戳等信息；
(3) tree为协议树节点对象，数据结构会被渲染在tree区。

tree.add方法：
解析器内部的tree:add(seong_protocol, buffer(),"Seong Message Data")功能是: 在tree区域添加一个子树(并返回子树的引用)。其中第一个参数是必选的，后面两个参数是可选的：
(1) 协议参数
tree区域中，每层协议对应一个子树，即每个子tree需要与指定的协议绑定，此时需要为seong协议创建一个子树:

1. local subtree = tree:add(seong_protocol, nil, nil);

复制代码

后续通过操作subtree对象，为seong协议子树添加显示数据。

(2) 数据参数
当传递为nil和buffer或者buffer(0,2) 时，鼠标选中seong协议时，关联的data区域不同:

(3) 描述信息
当描述信息为nil时，wireshark会选择使用协议的描述信息展示。

[3] 将协议与端口绑定
将协议与端口绑定后，Wireshark会自动将该端口上的消息使用绑定的协议解析:

1. DissectorTable.get("tcp.port"):add(9003, seong_protocol)

复制代码

此时，TCP协议的9003端口的消息使用seong插件解析。

2.2 修改Column区

在过滤窗口，通过seong过滤后，可以得到TCP-9003端口的消息，显示的Protocol协议仍未TCP，应该修改为seong. 在解析器内部添加语句pinfo.columns.protocol:set(seong_protocol.name),得到:

1. seong_protocol = Proto("seong", "seong description")
3. seong_protocol.dissector = function(buffer, pinfo, tree)
4. local subtree = tree:add(seong_protocol, buffer(),"Seong Message Data");
5. pinfo.columns.protocol:set(seong_protocol.name);
6. end
8. DissectorTable.get("tcp.port"):add(9003, seong_protocol)

复制代码

Wireshark显示为:

消息的协议名称修改为了seong.
除了protocol外，还可以通过pinfo.columns对象修改columns区域的其他字段的内容, 如修改info消息:
pinfo.columns.info:set("此时充值VIP可观看");

2.3 修改Tree区

Tree区为重点区域，自定义插件的核心功能是为了在这个区域直观地展示消息的内容。解析器的重点职责是从二进制数据中解析消息，并将消息作为字段添加到tree上，从而在Tree区域展示。
以下结合两种方式，其中通过Proto对象的fields属性方式是官方文档的推荐方式；直接操作tree对象方式是个人探索所得，相对比较简单(可能有坑)。

2.3.1 Proto对象的fields属性方式

先给出案例:

1. seong_protocol = Proto("seong", "seong description")
3. message_length = ProtoField.int32("message_length", "Message-Length", base.DEC)
4. seong_protocol.fields = {message_length}
6. seong_protocol.dissector = function(buffer, pinfo, tree)
7. local subtree = tree:add(seong_protocol, buffer(),"Seong Message Data");
8. pinfo.columns.protocol:set(seong_protocol.name);
10. subtree:add(message_length, 123456)
11. end
13. DissectorTable.get("tcp.port"):add(9003, seong_protocol)

复制代码

与之前的lua脚本区域在于新增了Proto.fields相关的逻辑:
[1] 声明字段类型
message_length = ProtoField.int32(“message_length”, “Message-Length”, base.DEC)
创建一个属性，属性名称为message_length，描述为Message-Length(显示使用)， 为十进制的整数。
[2] 字段添加到协议对象中

1. seong_protocol.fields = {message_length}

复制代码

[3] 为message_length赋值，并添加到tree中

1. subtree:add(message_length, 123456)

复制代码

此时, wireshark显示如下:

2.3.2 直接操作tree对象

通过subtree:add(字符串)方法直接将字符串设置到tree对象上:

1. seong_protocol = Proto("seong", "seong description")
3. seong_protocol.dissector = function(buffer, pinfo, tree)
4. local subtree = tree:add(seong_protocol, buffer(),"Seong Message Data");
5. pinfo.columns.protocol:set(seong_protocol.name);
7. subtree:add("Message-Length: " .. 11223344)
8. end
10. DissectorTable.get("tcp.port"):add(9003, seong_protocol)

复制代码

2.3.3 简单案例

假设消息中前两个字节表示有效的数据长度：

1. seong_protocol = Proto("seong", "seong description")
3. seong_protocol.dissector = function(buffer, pinfo, tree)
4. local subtree = tree:add(seong_protocol, buffer(),"Seong Message Data");
5. pinfo.columns.protocol:set(seong_protocol.name);
7. subtree:add("Message-Length: " .. buffer(0,2))
8. end
10. DissectorTable.get("tcp.port"):add(9003, seong_protocol)

复制代码

其中，buffer(0,2)从二进制消息中提取前两个字节; subtree:add方法调用时，可以关联data区域：
subtree:add("Message-Length: " .. buffer(0,2)) 修改为
subtree:add(buffer(0,2), "Message-Length: " .. buffer(0,2)):
显示如下:

3.案例

3.1 protobuf文件准备

Person.proto文件:

1. syntax = "proto2";
3. option java_package = "com.seong";
5. option java_outer_classname = "TestProtoMsg";
7. message Person {
8. required int32 id = 1;
9. required string name = 2;
10. required bool isMale = 3;
11. repeated Address address = 4;
12. };
14. message Address {
15. required string country = 1;
16. optional string location = 2;
17. };

复制代码

编译后，生成com.seong.TestProtoMsg类，内部有Person和Address两个内部类，生成的Java类将在服务端和客户端程序中使用。然后将Person.proto文件放到1.1章节中配置的protobuf加载路径下。

3.2 Java服务端和客户端单例

使用Netty构建一个服务端(监听端口为9999)与客户端, 二者之间通过TCP-Protobuf通信，消息格式如下:

首部固定为AAAA(2字节)，消息大类为BB(1字节), 消息子类为CC(1字节)，消息长度表示PB消息体的长度(2字节)，PB消息内容为5.1中Person.proto文件的protobuf消息。

关于Netty相关代码这里不进行介绍，请参考IO系列-netty相关的文章。

客户端:

(1) 客户端Netty模板代码:

1. public class Application {
2. public static void main(String[] args) throws Exception {
3. new Application().start();
4. }
6. public void start() throws Exception {
7. EventLoopGroup group = new NioEventLoopGroup();
8. try {
9. Bootstrap b = new Bootstrap();
10. b.group(group).channel(NioSocketChannel.class).handler(new ChannelInitializer<SocketChannel>() {
11. @Override
12. protected void initChannel(SocketChannel ch) {
13. ch.pipeline().addLast(new PersonProtoBufEncoder());
14. }
15. });
17. ChannelFuture f = b.connect("localhost", 9999).sync();
18. f.channel().writeAndFlush(buildPersonMsg());
19. f.channel().closeFuture().sync();
20. } finally {
21. group.shutdownGracefully();
22. }
23. }
24. }

复制代码

(2) 构造消息: 根据PB定义构造案例消息

1. private TestProtoMsg.Person buildPersonMsg() {
2. TestProtoMsg.Person.Builder personBuilder = TestProtoMsg.Person.newBuilder();
3. personBuilder.setId(1960001001);
4. personBuilder.setName("ue001");
5. personBuilder.setIsMale(false);
6. TestProtoMsg.Address.Builder addressBuilder = TestProtoMsg.Address.newBuilder();
7. addressBuilder.setCountry("zh-CN");
8. addressBuilder.setLocation("NanJing");
9. personBuilder.addAddress(addressBuilder.build());
10. return personBuilder.setId(1).build();
11. }

复制代码

(3) Protobuf编码器:将TestProtoMsg.Person对象编码为二进制数据，然后发送给服务端

1. public class PersonProtoBufEncoder extends MessageToByteEncoder<TestProtoMsg.Person> {
2. private static final int TYPE = 4;
4. private static final int LENGTH = 4;
6. @Override
7. protected void encode(ChannelHandlerContext ctx, TestProtoMsg.Person person, ByteBuf byteBuf) {
8. byte[] playLoadBytes = person.toByteArray();
9. int playLoadLen = playLoadBytes.length;
10. ByteBuf msgBuffer = Unpooled.buffer(TYPE + LENGTH + playLoadLen);
11. msgBuffer.writeBytes(new byte[] {(byte)0xAA, (byte)0xAA});
12. msgBuffer.writeBytes(new byte[] {(byte)0xBB, (byte)0xCC});
13. msgBuffer.writeInt(playLoadLen);
14. msgBuffer.writeBytes(playLoadBytes);
15. byteBuf.writeBytes(msgBuffer);
16. }
17. }

复制代码

服务端:

(1) 服务端Netty模板代码:

1. public class Application {
2. public static void main(String[] args) throws Exception {
3. new Application().start(9999);
4. }
6. public void start(int port) throws Exception {
7. EventLoopGroup bossGroup = new NioEventLoopGroup();
8. EventLoopGroup workerGroup = new NioEventLoopGroup();
9. try {
10. ServerBootstrap b = new ServerBootstrap();
11. b.group(bossGroup, workerGroup)
12. .channel(NioServerSocketChannel.class)
13. .handler(new LoggingHandler(LogLevel.INFO))
14. .childHandler(new ChannelInitializer<SocketChannel>() {
15. @Override
16. public void initChannel(SocketChannel ch) {
17. ch.pipeline().addLast(new PersonProtoBufDecoder());
18. ch.pipeline().addLast(new PersonProtoServerHandler());
19. }
20. })
21. .option(ChannelOption.SO_BACKLOG, 128)
22. .childOption(ChannelOption.SO_KEEPALIVE, true);
24. ChannelFuture f = b.bind(port).sync();
26. f.channel().closeFuture().sync();
27. } finally {
28. workerGroup.shutdownGracefully();
29. bossGroup.shutdownGracefully();
30. }
31. }
32. }

复制代码

(2) 解码器: 将来自客户端的二进制数据解码为TestProtoMsg.Person对象

1. public class PersonProtoBufDecoder extends ByteToMessageDecoder {
2. private static final int TYPE_HEAD = 4;
4. private static final int LENGTH_HEAD = 4;
6. private static final int HEAD_LEN = TYPE_HEAD + LENGTH_HEAD;
8. @Override
9. protected void decode(ChannelHandlerContext channelHandlerContext, ByteBuf byteBuf, List<Object> list) throws Exception {
10. byte[] msgBytes = new byte[byteBuf.readableBytes()];
11. byteBuf.readBytes(msgBytes);
13. int msgLen = msgBytes.length;
14. if (msgLen <= HEAD_LEN) {
15. return;
16. }
17. byte[] bodyMsg = new byte[msgLen - HEAD_LEN];
18. System.arraycopy(msgBytes, HEAD_LEN, bodyMsg, 0, msgLen - HEAD_LEN);
19. TestProtoMsg.Person person = TestProtoMsg.Person.parseFrom(bodyMsg);
20. list.add(person);
21. }
22. }

复制代码

(3) 解码后的消息处理: 打印TestProtoMsg.Person对象

1. @Slf4j
2. public class PersonProtoServerHandler extends ChannelInboundHandlerAdapter {
3. @Override
4. public void channelRead(ChannelHandlerContext ctx, Object msg) {
5. if (!(msg instanceof TestProtoMsg.Person)) {
6. ctx.fireChannelRead(msg);
7. return;
8. }
9. LOGGER.info("Receive from client, msg is {}.", msg);
10. }
11. }

复制代码

运行结果如下所示:

1. 17:17:42.874 [nioEventLoopGroup-3-1] INFO com.seong.PersonProtoServerHandler - Receive from client, msg is id: 1
2. name: "ue001"
3. isMale: false
4. address {
5. country: "zh-CN"
6. location: "NanJing"
7. }
8. .

复制代码

3.3 抓包分析

通过wireshark或者tcpdump可进行抓包，这里对端口进行过滤(9999):

可以看到客户端与服务端的通信数据包已被获取，为二进制数据，没有可读性。

3.4 Lua脚本定义协议

1. -- 自定义协议：Proto构造函数有两个参数：名称和描述
2. seong_protocol = Proto("seong", "seong Message")
3. -- 添加一个字段，用于在数据树中显示
4. message_length = ProtoField.int32("seong.message_length", "PB-Message-Length", base.DEC)
5. seong_protocol.fields = {message_length}
7. -- 自定义协议的解析器
8. seong_protocol.dissector = function(buffer, pinfo, tree)
9. -- 消息长度为0，直接返回
10. local length = buffer:len();
11. if length == 0 then return end;
13. -- 添加子树，显示为Seong Message Data
14. local subtree = tree:add(seong_protocol, buffer(),"Seong Message Data");
16. -- 消息树中添加PB-Message-Length信息
17. local msgLen = buffer(4,4):uint()
18. subtree:add(message_length, msgLen)
20. -- 消息树中添加HEAD，Main-Type，Sub-Type数据
21. local headFlag = "" .. buffer(0,2)
22. local mainType = "" .. buffer(2,1)
23. local subType = "" .. buffer(3,1)
24. subtree:add(buffer(0,2),"HEAD: " .. headFlag)
25. subtree:add(buffer(2,1),"Main-Type: " .. mainType)
26. subtree:add(buffer(3,1),"Sub-Type: " .. subType)
28. -- 调用wireshark内置的protobuf解析器
29. sipProtoType = "Person";
30. pinfo.private["pb_msg_type"] = "message," .. sipProtoType
31. local protobuf_dissector = Dissector.get("protobuf");
32. local result = pcall(Dissector.call, protobuf_dissector, buffer(8, msgLen):tvb(), pinfo, subtree)
33. pinfo.columns.protocol:set(seong_protocol.name)
34. end
36. --注册协议到指定的端口
37. local tcp_port = DissectorTable.get("tcp.port"):add(9999, seong_protocol)

复制代码

3.5 查看协议

此时二进制数据已经通过树区域进行了展示, 与服务端解码后的消息保持一致。

3.6 扩展

本文中涉及的protobuf文件只有一个，实际上系统间的消息类型数以百计，因此需要对上述Lua脚本进行扩展以具备更好的通用性。
注意到定义消息时，添加了消息大类和消息子类两个冗余字段，可通过这两个字段与protobuf之间建立映射关系，即这两个消息确定了消息类型和解码方式。

1. local function matchedProtoType(mainType, subType)
2. print("mainType:" .. mainType .. "subType:" .. subType)
3. if mainType == "bb" then
4. if subType == "cc" then
5. return "Person";
6. end
8. else
9. return nil
10. end
12. return nil
13. end

复制代码

定义一个函数，根据mainType和subType返回protobuf消息类型，相应地，Lua脚本中解析器的定义进行如下修改(将硬编码的Person类型改为通过matchedProtoType获取):

1. idslds_protocol.dissector = function(buffer, pinfo, tree)
2. -- ...
4. --sipProtoType = "Person";
5. sipProtoType = matchedProtoType(mainType,subType)
6. -- ...
7. end

复制代码

本文主要介绍如何在wireshark中介绍自定义Lua插件，因此扩展这一部分不进行详细描述。后续在IO系列-Netty应用相关的文章中将介绍一个通过Netty实现子网穿越的案例；之后结合该案例对Lua插件的应用进行完整的阐述。