Development/sharkd ​

简介 ​

sharkd 是一个程序，它通过程序化接口提供 Wireshark 强大的解析和分析能力。程序可以向 sharkd 发送简单的 JSON 格式请求，以加载、分析和操作网络数据包文件。

我们在标准 Wireshark 用户界面中看到的许多功能都可以通过 sharkd 使用，包括数据包协议树、数据包字节和显示过滤器。

• 简介

• 安装

• 运行 sharkd

• Classic

• Gold

• sharkd 请求

• 请求语法

• 请求类型

• Bug

• 未加载文件时的异常

• 反斜杠未转义时的异常

• 意外结果

• 研究和调试 sharkd

• 使用 Putty 测试

• 简单 Python 代码示例

• 致谢

wiki 页面 sharkd Request Syntax 提供了请求类型及其参数的完整详细信息。

安装 ​

标准 Wireshark 二进制包（Windows MSI 等）中不包含 sharkd 可执行文件，因此必须从源代码构建。在 Windows 下构建 sharkd 会生成 sharkd.exe 可执行文件。

sharkd 不能只靠 sharkd.exe 文件工作；它使用 Wireshark DLL 和偏好设置文件。因此，我们需要安装 sharkd 构建所产生的一切内容。

运行 sharkd ​

我们可以用两种模式运行 sharkd：

• Console Mode：可以通过 stdin 发送 JSON 请求，并从 stdout 接收 JSON 响应
• Daemon Mode：sharkd 作为运行在 socket 上的服务启动，允许我们通过该 socket 发送 JSON 请求并接收 JSON 响应

多个会话可以连接到以 Daemon Mode 运行的 sharkd。每个连接都会启动一个专用的 sharkd.exe 进程。因此，当没有连接时，有一个 sharkd 进程；当有一个活动会话时，有两个 sharkd 进程；当建立第二个连接时，将有三个 sharkd 进程，依此类推。

有两种命令行选项格式：Classic（原始格式）和 POSIX。POSIX 格式尝试遵循 POSIX 命令行标准，并提供更多选项。我们将 POSIX 扩展范围的选项称为 Gold 选项。

Classic ​

要以 Console Mode 启动 sharkd，请使用命令：

 sharkd -

注意：默认编译在 Windows 上仅支持 tcp 端口。 请参见 Which package contains sharkd? 和 Add sharkd - daemon variant

Peter Wu | Jan 24, 2017 | Patch Set 8: Code-Review+1Should be a good start. (Disabling the TCP socket also removes my concern about remote attacks.)

要以 Daemon Mode 在 TCP 端口上运行 sharkd，请使用命令：

 sharkd tcp:127.0.0.1:4446

这会使 sharkd 监听到 localhost TCP 端口 4446 的 TCP 连接。必要时可以更改 TCP 端口号。

UNIX sockets 也受支持：

 sharkd unix:/tmp/sharkd.sock

在这种情况下，sharkd 始终使用 Default profile 中设置的偏好设置。sharkd 也遵守 Default profile 的其他方面，例如 disabled_protos、enabled_protos 等。

Gold ​

Gold (gold_options): -a <socket>, --api <socket> listen on this socket -h, --help show this help information -v, --version show version information -C <config profile>, --config-profile <config profile> start with specified configuration profile Examples: sharkd -C myprofile sharkd -a tcp:127.0.0.1:4446 -C myprofile

如果你更改了所选 profile 中的任何偏好设置（通过编辑 preferences 文件或使用 Wireshark Edit -> Preferences），这些更改不会在任何当前 sharkd 会话中生效。你需要启动一个新会话。

sharkd 遵守所选 profile 的其他方面，例如 disabled_protos、enabled_protos 等。

sharkd 请求 ​

请求语法 ​

sharkd 服务请求具有以下通用格式：

 {"req":"command","_option_":"_value_","_option_":"_value_",...}

请求处理器使用一个简单的 gets(...) 函数来读取传入请求。这意味着：

• 请求只能包含可打印字符

• 特殊字符必须转义

• 数值可以加引号，也可以不加引号——通常不加引号，并且响应中的数值不加引号

• 例如

• 例如

• 例如 response -

• 整个请求必须位于单行

• 请求必须以换行符结束

命令必须采用如下所示的小写形式。key 和 value 周围的引号必须是双引号——单引号会产生 JSON 错误。另请注意使用的是英国英语拼写 analyse；analyze 不会工作。

如果你在连接上发送无效 JSON，sharkd 会写入 stdout 消息：

 invalid JSON -> closing

然后 sharkd 会话终止。

请求类型 ​

请求类型包括：

• analyse - 列出数据包文件中发现的协议及其开始和结束时间

• 例如

• bye - 结束一个 startd 会话

• 例如

• check - 用于检查字段或过滤器的有效性

• 例如

• 例如

• complete - 基于部分或完整引用返回字段或偏好设置的属性

• 例如

• 例如

• download - 获取已解码对象（导出的对象、SSL secrets 或 rtp data）；某些下载的数据经过 base64 编码

• 例如

• 参见 tshark --export-objects 和 Wireshark 中的 Export Objects 功能

• dumpconf - 列出一个、一些或全部配置参数

• 例如

• follow - 获取特定协议或 stream 的客户端和服务器信息，以及为容纳二进制内容而进行 JSON-Base64 编码的数据 payload。

• 例如

• 例如

• frame - 获取有关某个 frame 的完整信息，包括协议树

• 例如

• frames - 获取某一范围数据包的 Packet List 信息

• 例如 {"req":"frames","filter":"frame.number<=20"}

• info - 获取 sharkd clients 可用的格式和统计信息类型列表

• 例如

• 等同于 tshark -G 选项

• intervals - 按请求的时间间隔生成基本捕获统计信息（总帧数和总字节数）（默认按秒）

• 例如

• iograph - 创建用于绘图的按时间排序的值列表；默认逐秒

• 例如

• load - 加载 packet trace 文件以进行分析

• 例如 {"req":"load","file":"c:\traces\example.pcapng"}

• 例如

• setcomment - 在已加载 trace 中设置某个 frame 的注释——不会保存到 trace 文件

• 例如

• setconf - 设置配置参数

• 例如

• status - 获取已加载文件的基本信息（名称、大小、frame 数量等）

• 例如

• tap - 设置最多 16 个统计 tap 并从中获取统计信息；tap 类型包括 stats、nstat、conv、host、rtp-streams、rtp-analyse、eo、expert、rtd、srt 和 flow

• 例如

• 例如

通过 Console Interface 输入 JSON 请求有时会在 JSON 响应之外生成额外的 stdout 消息，例如：

{"req":"load","file":"c:/traces/Contoso_01/web01/web01_00001_20161012151754.pcapng"}load: filename=c:/traces/Contoso_01/web01/web01_00001_20161012151754.pcapng{"err":0}

wiki 页面 sharkd Request Syntax 提供了请求类型及其参数的完整详细信息。

Bug ​

在对 sharkd 进行实验期间，发现了一些值得注意的 bug。

未加载文件时的异常 ​

在加载任何文件之前发出命令来查询或修改数据包文件，通常会导致程序异常。

反斜杠未转义时的异常 ​

Windows 文件路径反斜杠（\）分隔符必须转义，如果没有转义，也会导致程序异常。或者，可以使用正斜杠，如上面的 load 请求示例所示。

意外结果 ​

sharkd 有时会产生意外结果：

• 如果输入空行，会话会立即终止
• 如果输入无效 JSON，可能会收到原始文本消息，但不会收到 JSON 响应
• 如果指定错误值，某些请求不会给出响应
• frame 请求的选项不是真正的 boolean，例如 "bytes":false 和 "bytes":true 会产生相同结果
• 某些请求类型不返回错误代码（"err":）
• 即使请求失败或格式不正确，错误代码几乎总是 0（零）

研究和调试 sharkd ​

许多人会想使用 Visual Studio 来研究 sharkd 的工作方式或进行调试。请记住，在 Daemon Mode 下运行时，JSON 请求将由专用的 sharkd 进程处理，而不是由你在 Visual Studio 中启动执行的那个进程处理。避免这种情况的最简单方法是在 Console Mode 下运行时进行研究或调试。

当文件加载到 Wireshark 中时，会对 PCAPNG 文件中的每个数据包调用一次协议解析器，然后在显示数据包时至少再调用一次。sharkd 也是如此：

• 执行 load 请求时，会为每个 frame 调用一次解析器
• 执行 frame 请求时，会为单个 frame 再次调用解析器

使用 Putty 测试 ​

合适的 putty 设置为：

• Host Name（或 IP address）：localhost
• Port：4446
• Connection Type：Raw

成功连接后，daemon 会写入一条 stdout 消息：

 Hello in child.

简单 Python 代码示例 ​

此程序连接到以 Daemon mode 运行的 sharkd，发送两个命令，显示每个命令的响应，然后关闭连接。

importsocketdefget_json_bytes(json_string):returnbytes((json_string+'\n'),'utf-8')defjson_send_recv(s,json)->str:s.sendall(get_json_bytes(json))data=s.recv(1024)returndata[:-4].decode('utf-8')host=socket.gethostbyname('localhost')port=4446# The port used by sharkds=socket.socket(socket.AF_INET,socket.SOCK_STREAM)print('c: Connecting to '+host+':'+str(port))s.connect((host,port))json_string='{"req":"load","file":"c:/traces/Contoso_01/web01/web01_00001_20161012151754.pcapng"}'print('s: '+json_string)recv_json=json_send_recv(s,json_string)print('r: '+recv_json)json_string='{"req":"status"}'print('s: '+json_string)rx_json=json_send_recv(s,json_string)print('r: '+rx_json)print('c: Closing connection to '+host+':'+str(port))s.close()

输出如下所示：

c: Connecting to 127.0.0.1:4446s: {"req":"load","file":"c:/traces/Contoso_01/web01/web01_00001_20161012151754.pcapng"}r: {"err":0}s: {"req":"status"}r: {"frames":53882,"duration":1841.532335000,"filename":"web01_00001_20161012151754.pcapng","filesize":36433896}c: Closing connection to 127.0.0.1:4446

致谢 ​

编写像 sharkd 这样的功能是一项艰巨任务，因此我们必须感谢 Jakub Zawadzki 的工作，他编写了这些代码。

相关 Wireshark Wiki 页面 ​

• Wireshark Wiki 首页Home · 入门与使用
• sharkd Request Syntaxsharkd Request Syntax · 全量归档