1. 项目概述为什么我们需要一个Portal协议的Wireshark Lua插件如果你经常和网络认证打交道尤其是那种在酒店、机场、校园里常见的“网页弹窗认证”也就是Portal认证那你肯定对抓包分析不陌生。Wireshark是咱们这行的“瑞士军刀”但面对Portal协议这种非标准或私有协议它默认的解析能力就有点捉襟见肘了。一堆HTTP报文里关键的认证交互信息比如Challenge、Response、心跳包混杂其中手动过滤和解读效率极低还容易看走眼。这个项目的核心就是打造一个Wireshark的Lua插件专门用来深度解析Portal协议。它不是一个简单的过滤器而是一个完整的协议解析器Dissector。它能自动识别Portal认证流程中的特定报文把十六进制的原始载荷Payload转换成人类可读的字段比如“用户MAC地址”、“挑战随机数”、“认证结果状态码”并直接在Wireshark的Packet Details面板里以树状结构展示出来。这样一来无论是排查认证失败、分析交互流程还是做安全审计效率都能提升好几个数量级。为什么选择Lua因为Wireshark原生支持Lua作为扩展脚本语言无需编译跨平台这正是我们同时需要Mac和Win版的原因修改和部署极其灵活。对于网络协议分析这种需要快速适配不同变种和私有字段的场景Lua脚本是再合适不过的工具了。这个插件将直接解决Portal协议分析中的“盲点”问题让不可见的认证逻辑变得一目了然。2. 核心需求与协议逻辑拆解在动手写代码之前我们必须彻底搞清楚我们要解析的对象——Portal协议。这里说的Portal协议通常不是指标准的RFC协议而是一种在宽带接入场景中广泛使用的、基于HTTP/HTTPS的客户端与认证服务器之间的交互规范。它的核心逻辑是“重定向认证”。2.1 Portal认证流程的四个关键阶段一个典型的Portal认证流程可以分解为四个阶段我们的插件需要精准识别并解析每个阶段的报文。第一阶段强制重定向与发现用户设备连接网络后发起任意HTTP请求比如访问一个网站。接入设备如交换机或AC会拦截这个请求并返回一个302重定向响应将用户浏览器导向认证服务器的Portal页面。这个阶段的关键是识别那个特殊的重定向响应其中包含了认证服务器的地址和初始参数。我们的插件需要能解析这个响应头里的Location字段并可能从中提取出后续交互所需的服务器IP和端口。第二阶段身份信息获取与挑战用户在弹出的Portal页面上输入账号密码并提交。此时浏览器会向认证服务器发送一个POST请求。这个请求的Body里通常包含了用户名、密码可能是明文也可能是经过一次MD5之类的哈希、用户设备的MAC地址、IP地址等信息。更重要的是服务器端为了防重放攻击通常会引入一个“挑战随机数”Challenge。这个Challenge可能在之前的页面加载时通过隐藏表单域或JavaScript变量下发也可能由服务器在本次请求中动态生成并期待客户端回应。解析这个POST请求的Body提取出用户名、经过处理的密码字段以及客户端对Challenge的响应如果有是插件的核心任务之一。第三阶段认证决策与结果通知认证服务器验证凭据后会返回一个结果页面。这个结果通常通过一个HTTP响应来实现响应体内包含一个简单的成功/失败标志或者是一段用于触发客户端如专用客户端软件进行下一步操作的JavaScript代码。对于后台的认证系统交互可能会有一个更轻量的API调用例如一个返回JSON的请求其中包含了明确的result_code如0表示成功1表示密码错误、session_id等信息。插件需要能解析这些结构化的响应数据。第四阶段心跳与保活认证成功后为了维持在线状态客户端可能是网页中的JavaScript也可能是专用客户端会定期向服务器发送“心跳”报文。这些报文通常是简短的HTTP GET或POST请求包含session_id和actionkeepalive之类的参数。服务器则回应一个存活确认。解析这些心跳报文对于分析用户异常下线、会话超时等问题至关重要。2.2 协议字段的“指纹”识别不同厂商的Portal协议实现虽有差异但万变不离其宗。我们的插件需要通过以下“指纹”来识别Portal协议报文特定URL路径请求的URL路径常包含/portal、/auth、/login、/portalAuth等关键字。特定的HTTP头可能包含自定义头如X-Client-Type: Portal或者User-Agent字段里带有特定客户端标识。报文载荷格式POST数据可能是application/x-www-form-urlencoded格式如usernametestpasswordmd5hashchallengeabc123也可能是application/json格式如{action: login, data: {...}}。响应内容特征成功响应可能包含“success”: true、“result”: 0或HTML页面中存在“认证成功”等字样。插件的首要智能就在于能基于这些特征从海量HTTP流量中自动筛选出Portal协议相关的报文并将其交给后续的解析逻辑处理。3. Wireshark Lua插件开发环境搭建工欲善其事必先利其器。开发一个跨Mac和Windows的Wireshark Lua插件第一步就是配置好两边的开发与调试环境。3.1 基础环境准备Windows平台安装Wireshark从官网下载并安装最新稳定版。安装时务必勾选“Install WinPcap/Npcap”和“Install USBPcap”如果需要抓USB包的话最重要的是确保勾选了“Install Lua”组件。默认安装路径通常是C:\Program Files\Wireshark。确认Lua支持安装后打开Wireshark点击“帮助” - “关于Wireshark” - “文件夹”。查看“个人Lua插件”和“全局Lua插件”的路径。通常个人插件路径是%APPDATA%\Wireshark\plugins全局插件路径是Wireshark安装目录下的plugins子文件夹如C:\Program Files\Wireshark\plugins。将插件.lua文件放在个人插件路径下重启Wireshark即可生效无需管理员权限更为推荐。编辑器选择任何文本编辑器均可如VS Code、Notepad。建议使用VS Code并安装Lua语言扩展以获得语法高亮和基础提示。macOS平台安装Wireshark可以通过Homebrew (brew install --cask wireshark) 或从官网下载DMG包安装。通过Homebrew安装通常更便捷且易于管理。权限配置关键步骤在macOS上Wireshark需要特殊权限才能抓包。安装后你需要运行/Applications/Wireshark.app/Contents/Resources/macosx-setup.sh这个脚本可能需要通过终端sudo执行或者使用sudo chmod 644 /dev/bpf*命令不推荐重启可能失效。更现代的方式是安装时根据提示授予Wireshark和dumpcap二进制文件CAP_NET_RAW和CAP_NET_ADMIN能力。Lua插件路径macOS上个人Lua插件路径通常是~/.config/wireshark/plugins/。如果该目录不存在可以手动创建。全局插件路径在Wireshark应用包内/Applications/Wireshark.app/Contents/PlugIns/wireshark/不建议直接修改。编辑器同样推荐VS Code。注意在两大平台上调试Lua插件最直接的方式就是使用print()或debug()函数将信息输出到Wireshark的“输出窗口”在“分析”菜单下可以找到。确保在Wireshark的“编辑” - “首选项” - “高级”中搜索“lua”将console.open设置为true这样print语句的内容才会显示出来。3.2 插件结构与加载机制一个完整的Wireshark Lua协议解析器Dissector通常包含以下几个部分我们将其写在一个.lua文件中-- 定义协议对象 local portal_proto Proto(Portal, Portal Authentication Protocol) -- 定义协议字段将在后续章节详述 local fields { username ProtoField.string(portal.username, Username), password_md5 ProtoField.string(portal.password_md5, Password(MD5)), challenge ProtoField.string(portal.challenge, Challenge), client_mac ProtoField.ether(portal.client_mac, Client MAC), result_code ProtoField.uint8(portal.result_code, Result Code, base.DEC), session_id ProtoField.string(portal.session_id, Session ID), action ProtoField.string(portal.action, Action), } -- 将字段注册到协议对象 portal_proto.fields fields -- 核心解析函数 function portal_proto.dissector(buffer, pinfo, tree) -- 1. 设置Wireshark信息列显示 pinfo.cols.protocol:set(Portal) -- 2. 在Packet Details面板创建子树 local subtree tree:add(portal_proto, buffer(), Portal Protocol Data) -- 3. 解析逻辑后续填充 -- ... end -- 将解析器注册到TCP端口例如常见的8080、80、443 local tcp_port_table DissectorTable.get(tcp.port) tcp_port_table:add(80, portal_proto) -- 注意这可能会与HTTP解析器冲突 tcp_port_table:add(8080, portal_proto) -- 更推荐的方式是“启发式”或基于内容识别见下文。关键点解析Proto类用于创建一种新协议。ProtoField用于定义协议中的各个字段并指定其类型字符串、整数、以太网地址等和显示名称。dissector函数是核心参数buffer是报文数据pinfo包含报文信息如源目的IPtree是用于构建解析树的对象。直接注册到端口如80是一种简单方法但会与标准的HTTP解析器冲突导致HTTP报文被我们的插件“劫持”而无法正常解析。这不是最佳实践。3.3 更优雅的集成方式基于内容的启发式解析为了避免与HTTP解析器冲突我们采用更智能的“启发式”解析器Heuristic Dissector。它不直接霸占某个端口而是先检查报文内容只有“看起来像”Portal协议时才进行解析。-- 定义一个启发式检测函数 function portal_proto.dissector_heuristic(buffer, pinfo, tree) -- 获取TCP载荷长度 local len buffer:len() if len 10 then return false end -- 太短不是完整HTTP请求 -- 将缓冲区数据转换为字符串方便匹配 local data buffer(0, math.min(200, len)):string() -- 检查前200字节 -- 关键特征匹配检查是否包含Portal相关路径或关键字 if (data:find(POST /portal/login) or data:find(GET /portal/keepalive) or data:find(portalAuth)) then -- 调用真正的解析函数 portal_proto.dissector(buffer, pinfo, tree) return true -- 告诉Wireshark这个报文被我处理了 end return false -- 不是Portal协议交给其他解析器如HTTP end -- 将启发式函数注册给协议 portal_proto:register_heuristic(tcp, portal_proto.dissector_heuristic)使用register_heuristic后插件会检查所有TCP流只有匹配特征的流量才会被解析为Portal协议其他HTTP流量依然由标准的HTTP解析器处理两者互不干扰。这是开发健壮插件的关键技巧。4. Portal协议字段的深度解析与Lua实现现在进入最核心的部分如何从HTTP报文的载荷中把那些我们关心的字段“挖”出来并以结构化的方式展示在Wireshark中。这要求我们对常见的数据提交格式有清晰的了解。4.1 处理application/x-www-form-urlencoded格式这是Web表单提交最常用的格式。请求体看起来像usernameadminpassworde10adc3949ba59abbe56e057f20f883echallenge7a3b8cclient_mac00-11-22-33-44-55。我们的任务是在dissector函数中解析这个字符串。function portal_proto.dissector(buffer, pinfo, tree) pinfo.cols.protocol:set(Portal) local subtree tree:add(portal_proto, buffer(), Portal Protocol Data) -- 获取TCP载荷假设整个载荷就是我们的数据 local payload buffer:raw() local payload_str ByteArray.new(payload):raw() -- 尝试查找HTTP报文头和体之间的空行分隔符 local header_end payload_str:find(\r\n\r\n) if not header_end then -- 如果没有找到标准HTTP头可能不是完整报文直接返回 subtree:add_expert_info(PI_MALFORMED, PI_ERROR, Invalid HTTP packet) return end -- 提取HTTP Body部分空行之后的内容 local body_start header_end 4 -- \r\n\r\n 长度是4 local body_str payload_str:sub(body_start) -- 判断Content-Type这里简化处理假设是urlencoded -- 在实际中应从HTTP头中解析Content-Type -- 解析键值对 for key, value in body_str:gmatch(([^])([^]*)) do key Url.decode(key) value Url.decode(value) -- 根据键名添加到对应的协议字段 if key:lower() username then subtree:add(fields.username, buffer(body_start-1 body_str:find(key..), #value), value) elseif key:lower():find(password) then -- 注意密码字段可能是明文也可能是MD5哈希32位十六进制字符串 subtree:add(fields.password_md5, buffer(body_start-1 body_str:find(key..), #value), value) -- 可以添加判断如果是32位十六进制则注释为“MD5 Hash” elseif key:lower() challenge then subtree:add(fields.challenge, buffer(body_start-1 body_str:find(key..), #value), value) elseif key:lower():find(mac) then -- 尝试标准化MAC地址格式 local std_mac value:gsub([-:], ):lower() if #std_mac 12 then -- 标准MAC长度 std_mac std_mac:gsub((%x%x)(%x%x)(%x%x)(%x%x)(%x%x)(%x%x), %1:%2:%3:%4:%5:%6) end subtree:add(fields.client_mac, buffer(body_start-1 body_str:find(key..), #value), std_mac) elseif key:lower() action then subtree:add(fields.action, buffer(body_start-1 body_str:find(key..), #value), value) else -- 其他未知字段也显示出来便于调试 subtree:add(buffer(body_start-1 body_str:find(key..), #value), key .. : .. value) end end end实操心得body_str:gmatch(([^])([^]*))这个模式匹配是解析urlencoded格式的关键。Url.decode函数用于解码被转义的特殊字符如空格被编码为%20。注意buffer()函数的索引操作需要小心计算偏移量这里为了清晰展示了逻辑实际编写时计算偏移量更复杂可能需要用到TvbRange。一个更稳健的做法是直接操作字符串然后用tree:add()的字符串参数形式添加字段。4.2 处理application/json格式越来越多的Portal系统使用JSON API。请求体可能是{action: login, data: {username: user1, password_md5: c4ca4238a0b923820dcc509a6f75849b, mac: 00:11:22:33:44:55}}解析JSON需要Lua的JSON库。幸运的是Wireshark内嵌了json模块。-- 在文件开头附近声明确保能访问到json模块 local json require(json) function portal_proto.dissector(buffer, pinfo, tree) -- ... 前面部分相同获取body_str ... -- 判断是否为JSON简单通过首字符判断 if body_str:sub(1,1) { then local ok, json_data pcall(json.decode, body_str) if not ok then subtree:add_expert_info(PI_PROTOCOL, PI_WARN, Failed to decode JSON) return end -- 递归解析JSON对象 local function add_json_to_tree(prefix, data, subtree_root) for k, v in pairs(data) do local display_name prefix .. . .. k if type(v) table then -- 如果是嵌套对象创建新的子树 local new_subtree subtree_root:add(portal_proto, buffer(), display_name) add_json_to_tree(display_name, v, new_subtree) else -- 如果是值根据键名映射到预定义字段或直接显示 local field_to_add nil if k username then field_to_add fields.username elseif k password_md5 or k password then field_to_add fields.password_md5 -- ... 其他字段映射 ... end local value_str tostring(v) if field_to_add then subtree_root:add(field_to_add, buffer(), value_str) else subtree_root:add(buffer(), display_name .. : .. value_str) end end end end add_json_to_tree(portal, json_data, subtree) else -- 按urlencoded格式处理 -- ... end end注意事项pcall(json.decode, ...)是关键。它保护性地调用JSON解码避免因为畸形JSON数据导致整个插件崩溃影响Wireshark主程序。将解码错误以专家信息Expert Info的形式显示出来是专业的做法。4.3 解析响应报文与状态码对于服务器响应我们主要关注HTTP状态码和响应体中的业务状态。function portal_proto.dissector(buffer, pinfo, tree) -- ... 获取payload_str ... -- 解析第一行状态行例如 HTTP/1.1 200 OK local first_line_end payload_str:find(\r\n) if first_line_end then local status_line payload_str:sub(1, first_line_end-1) local http_version, status_code, status_msg status_line:match(^(HTTP/%d%.%d)%s(%d%d%d)%s(.)$) if status_code then subtree:add(buffer(0, first_line_end-1), Status: .. status_code .. .. status_msg) pinfo.cols.info:prepend([Portal] ) -- 在信息列添加前缀 -- 如果是200 OK尝试解析响应体中的业务信息 if status_code 200 then -- 查找响应体同样找空行分隔 local body_start payload_str:find(\r\n\r\n, first_line_end) if body_start then body_start body_start 4 local body_str payload_str:sub(body_start) -- 尝试从响应体中提取JSON格式的业务结果 if body_str:sub(1,1) { then local ok, resp_data pcall(json.decode, body_str) if ok and resp_data.result_code ~ nil then local result_field subtree:add(fields.result_code, tonumber(resp_data.result_code)) -- 可以根据result_code的值添加说明 local result_map {[0] Success, [1] Password Error, [2] User Not Found} local desc result_map[tonumber(resp_data.result_code)] or Unknown result_field:append_text( ( .. desc .. )) end if ok and resp_data.session_id then subtree:add(fields.session_id, resp_data.session_id) end -- 或者从HTML页面中提取文本提示简单正则匹配 elseif body_str:find(认证成功) then subtree:add_expert_info(PI_CHAT, PI_NOTE, Authentication Succeeded (from HTML)) elseif body_str:find(密码错误) then subtree:add_expert_info(PI_CHAT, PI_WARN, Authentication Failed: Wrong Password) end end end end end end通过解析响应我们不仅能看到HTTP层的成功200更能透视业务层的成功与否result_code: 0这对于故障定位至关重要。5. 跨平台兼容性处理与高级功能要让插件在macOS和Windows上都能稳定运行需要特别注意一些细节。5.1 路径与模块加载差异文件路径分隔符Lua中Windows用反斜杠\macOS/Linux用正斜杠/。在插件中如果需要加载外部数据文件如厂商OUI列表用于MAC地址厂商解析应使用package.config:sub(1,1)获取路径分隔符或直接使用/因为Lua在Windows上也通常能正确处理/。local sep package.config:sub(1,1) -- 获取分隔符 local data_file_path “my_data” .. sep .. “oui.txt” -- 或者更简单始终使用 / local data_file_path “my_data/oui.txt”依赖库避免使用平台特定的外部Lua库如通过luarocks安装的。尽量使用Wireshark内置的库json、bit32等或纯Lua实现的代码。如果必须使用需要提供检测和回退机制。local has_my_lib, my_lib pcall(require, “external_lib”) if not has_my_lib then -- 使用内置的替代方案或简化功能 debug(“Warning: external_lib not found, some features disabled.”) end5.2 增强插件实用性信息列与着色规则一个专业的插件不应该只藏在Packet Details里还应该提升在Packet List信息列中的可读性。自定义信息列 我们可以修改pinfo.cols.info来显示更简洁的Portal协议摘要。function portal_proto.dissector(buffer, pinfo, tree) -- ... 解析得到用户名、动作、结果码等 ... local info_str if action then info_str info_str .. “Action: “ .. action .. “ “ end if username then info_str info_str .. “User: “ .. username .. “ “ end if result_code then info_str info_str .. “Result: “ .. result_code if result_code “0” then info_str info_str .. “(OK)” else info_str info_str .. “(Fail)” end end if info_str ~ “” then pinfo.cols.info:set(info_str) -- 或者追加到原有信息后面 -- pinfo.cols.info:append(“ [Portal: “ .. info_str .. “]“) end end创建着色规则 我们可以让Wireshark自动为Portal协议报文着色比如成功报文绿色失败报文红色心跳报文蓝色。-- 这不是在dissector函数里而是在脚本加载时执行 local success_filter “portal.result_code 0” local failure_filter “portal.result_code 0” local heartbeat_filter “portal.action \“keepalive\”” -- 获取着色规则列表并添加新规则注意此操作在Wireshark GUI中更常见用Lua添加可能因版本而异 -- 更常见的做法是引导用户手动导入配色方案文件.csv或者在插件文档中提供过滤表达式。 -- 以下代码演示了一种可能的方法并非所有版本都支持 if ColorFilter then local color_table ColorFilter.new(“Portal Protocol”) color_table:add(success_filter, “green”, “Portal Success”) color_table:add(failure_filter, “red”, “Portal Failure”) color_table:add(heartbeat_filter, “light blue”, “Portal Heartbeat”) -- 注册这个颜色表 -- 具体API请参考对应Wireshark版本的Lua API文档 end更实际的做法是在插件注释或文档中提供这些过滤表达式让用户自行在Wireshark的“视图” - “着色规则”中创建。5.3 插件配置与参数化不同的Portal系统可能使用不同的字段名。为了让插件更具适应性可以引入配置参数。-- 定义可配置的字段名映射 local config_field_username Pref.string(“Username field name”, “username”, “The parameter name for username in POST data”) local config_field_password Pref.string(“Password field name”, “password_md5”, “The parameter name for password”) local config_field_challenge Pref.string(“Challenge field name”, “challenge”, “The parameter name for challenge”) -- 将配置项注册到协议 portal_proto.prefs.field_username config_field_username portal_proto.prefs.field_password config_field_password portal_proto.prefs.field_challenge config_field_challenge -- 在dissector函数中使用配置 function portal_proto.dissector(buffer, pinfo, tree) -- ... local username_key portal_proto.prefs.field_username local password_key portal_proto.prefs.field_password -- 在解析键值对时使用这些动态的key名进行比较 if key:lower() username_key:lower() then -- ... end -- ... end这样用户可以在Wireshark的“编辑” - “首选项” - “Protocols” - 找到“Portal”协议并修改这些字段名无需修改Lua代码即可适配不同系统。6. 调试、打包与部署实战开发完成后如何测试并交付一个可靠的插件6.1 调试技巧与常见问题使用print()和debug()这是最直接的调试方式。将变量值、执行路径打印到Wireshark的输出窗口。print(“[Portal] Body string: “ .. body_str:sub(1, 50) .. “...”) -- 打印前50字符确保在首选项中启用了Lua控制台输出。处理nil错误Lua中最常见的错误是尝试访问nil值。在访问可能不存在的字段或表键前务必进行检查。local value data_table[key] if value then -- 安全地使用value else print(“[WARN] Key ‘“ .. key .. “‘ not found in data_table”) end处理内存与性能解析大包或复杂JSON时注意性能。避免在循环中创建大量临时字符串或表。如果遇到“not enough memory”错误检查是否有内存泄漏如全局表不断增长。尽量使用局部变量。协议冲突排查如果发现插件没有生效首先检查Wireshark的“分析” - “启用的协议”中你的协议如“Portal”是否被勾选。然后检查输出窗口是否有Lua错误信息。最可能的原因是启发式函数没有正确匹配到报文可以临时放宽匹配条件如匹配所有包含“portal”字样的TCP流进行测试。6.2 插件打包与分发一个完整的插件包应该包含主脚本文件portal_dissector.lua配置文件可选如厂商特定的字段映射JSON文件。说明文档README.txt简要说明功能、配置方法、已知限制。示例抓包文件example_portal_capture.pcapng包含几个典型的Portal认证报文供用户测试和参考。部署步骤将上述文件打包成一个ZIP文件例如wireshark_portal_plugin_v1.0.zip。对于最终用户只需解压将.lua文件复制到其Wireshark的个人插件目录Windows:%APPDATA%\Wireshark\plugins macOS:~/.config/wireshark/plugins/ Linux:~/.local/lib/wireshark/plugins/。重启Wireshark。打开提供的示例抓包文件在Packet Details面板中应能看到“Portal Protocol”的子树。6.3 版本兼容性与维护Wireshark版本在脚本开头注明测试通过的Wireshark版本如-- Tested on Wireshark 4.0.x。不同版本的Lua API可能有细微差别。错误处理使用pcall或xpcall包裹可能出错的代码块如文件IO、网络调用、复杂解析防止单个报文解析失败导致整个插件被Wireshark禁用。社区反馈提供一个方式如GitHub仓库的Issues页面让用户提交不同厂商的协议变种以便持续更新字段映射和解析逻辑。开发这样一个插件最深的体会是“细节决定成败”。一个字符的编码错误、一个偏移量的计算失误都可能导致解析失败。但一旦成功看着杂乱无章的TCP流在Wireshark中自动被识别、解析成清晰的认证流程那种成就感是对开发者最好的回报。这个插件不仅是一个工具更是你对Portal协议理解的一种直观表达。