1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
|
Protocol Dissection in XML Format
=================================
Copyright (c) 2003 by Gilbert Ramirez <gram@alumni.rice.edu>
Wireshark has the ability to export its protocol dissection in an
XML format, tshark has similar functionality by using the "-Tpdml"
option.
The XML that Wireshark produces follows the Packet Details Markup
Language (PDML) specified by the group at the Politecnico Di Torino
working on Analyzer. The specification was found at:
http://analyzer.polito.it/30alpha/docs/dissectors/PDMLSpec.htm
That URL is not working anymore, but a copy can be found at the Internet
Archive:
https://web.archive.org/web/20050305174853/http://analyzer.polito.it/30alpha/docs/dissectors/PDMLSpec.htm
This is similar to the NetPDL language specification:
http://www.nbee.org/doku.php?id=netpdl:index
The domain registration there has also expired, but an Internet Archive
copy is also available at:
https://web.archive.org/web/20160305211810/http://nbee.org/doku.php?id=netpdl:index
A related XML format, the Packet Summary Markup Language (PSML), is
also defined by the Analyzer group to provide packet summary information.
The PSML format is not documented in a publicly-available HTML document,
but its format is simple. Wireshark can export this format too, and
tshark can produce it with the "-Tpsml" option.
PDML
====
The PDML that Wireshark produces is known not to be loadable into Analyzer.
It causes Analyzer to crash. As such, the PDML that Wireshark produces
is labeled with a version number of "0", which means that the PDML does
not fully follow the PDML spec. Furthermore, a creator attribute in the
"<pdml>" tag gives the version number of wireshark/tshark that produced the
PDML.
In that way, as the PDML produced by Wireshark matures, but still does not
meet the PDML spec, scripts can make intelligent decisions about how to
best parse the PDML, based on the "creator" attribute.
A PDML file is delimited by a "<pdml>" tag.
A PDML file contains multiple packets, denoted by the "<packet>" tag.
A packet will contain multiple protocols, denoted by the "<proto>" tag.
A protocol might contain one or more fields, denoted by the "<field>" tag.
A pseudo-protocol named "geninfo" is produced, as is required by the PDML
spec, and exported as the first protocol after the opening "<packet>" tag.
Its information comes from wireshark's "frame" protocol, which serves
the similar purpose of storing packet meta-data. Both "geninfo" and
"frame" protocols are provided in the PDML output.
The "<pdml>" tag
================
Example:
<pdml version="0" creator="wireshark/0.9.17">
The creator is "wireshark" (i.e., the "wireshark" engine. It will always say
"wireshark", not "tshark") version 0.9.17.
The "<proto>" tag
=================
"<proto>" tags can have the following attributes:
name - the display filter name for the protocol
showname - the label used to describe this protocol in the protocol
tree. This is usually the descriptive name of the protocol,
but it can be modified by dissectors to include more data
(tcp can do this)
pos - the starting offset within the packet data where this
protocol starts
size - the number of octets in the packet data that this protocol
covers.
The "<field>" tag
=================
"<field>" tags can have the following attributes:
name - the display filter name for the field
showname - the label used to describe this field in the protocol
tree. This is usually the descriptive name of the protocol,
followed by some representation of the value.
pos - the starting offset within the packet data where this
field starts
size - the number of octets in the packet data that this field
covers.
value - the actual packet data, in hex, that this field covers
show - the representation of the packet data ('value') as it would
appear in a display filter.
Deviations from the PDML standard
=================================
Various dissectors parse packets in a way that does not fit all the assumptions
in the PDML specification. In some cases Wireshark adjusts the output to match
the spec more closely, but exceptions exist.
Some dissectors sometimes place text into the protocol tree, without using
a field with a field-name. Those appear in PDML as "<field>" tags with no
'name' attribute, but with a 'show' attribute giving that text.
Some dissectors place field items at the top level instead of inside a
protocol. In these cases, in the PDML output the field items are placed
inside a fake "<proto>" element named "fake-field-wrapper" in order to
maximize compliance.
Many dissectors label the undissected payload of a protocol as belonging
to a "data" protocol, and the "data" protocol often resides inside
that last protocol dissected. In the PDML, the "data" protocol becomes
a "data" field, placed exactly where the "data" protocol is in Wireshark's
protocol tree. So, if Wireshark would normally show:
+-- Frame
|
+-- Ethernet
|
+-- IP
|
+-- TCP
|
+-- HTTP
|
+-- Data
In PDML, the "Data" protocol would become another field under HTTP:
<packet>
<proto name="frame">
...
</proto>
<proto name="eth">
...
</proto>
<proto name="ip">
...
</proto>
<proto name="tcp">
...
</proto>
<proto name="http">
...
<field name="data" value="........."/>
</proto>
</packet>
In cases where the "data" protocol appears at the top level, it is
still converted to a field, and placed inside the "fake-field-wrapper"
protocol, just as any other top level field.
Similarly, expert info items in Wireshark belong to an internal protocol
named "_ws.expert", which is likewise converted into a "<field>" element
of that name.
Some dissectors also place subdissected protocols in a subtree instead of
at the top level. Unlike with the "data" protocol, the PDML output does
_not_ change these protocols to fields, but rather outputs them as "<proto>"
elements. This results in well-formed XML that does, however, violate the
PDML spec, as "<proto>" elements should only appear as direct children of
"<packet>" elements, with only "<field>" elements nested therein.
Note that packet tag may have nonstandard color attributes, "foreground" and "background"
tools/WiresharkXML.py
====================
This is a python module which provides some infrastructure for
Python developers who wish to parse PDML. It is designed to read
a PDML file and call a user's callback function every time a packet
is constructed from the protocols and fields for a single packet.
The python user should import the module, define a callback function
which accepts one argument, and call the parse_fh function:
------------------------------------------------------------
import WiresharkXML
def my_callback(packet):
# do something
# If the PDML is stored in a file, you can:
fh = open(xml_filename)
WiresharkXML.parse_fh(fh, my_callback)
# or, if the PDML is contained within a string, you can:
WiresharkXML.parse_string(my_string, my_callback)
# Now that the script has the packet data, do something.
------------------------------------------------------------
The object that is passed to the callback function is an
WiresharkXML.Packet object, which corresponds to a single packet.
WiresharkXML Provides 3 classes, each of which corresponds to a PDML tag:
Packet - "<packet>" tag
Protocol - "<proto>" tag
Field - "<field>" tag
Each of these classes has accessors which will return the defined attributes:
get_name()
get_showname()
get_pos()
get_size()
get_value()
get_show()
Protocols and fields can contain other fields. Thus, the Protocol and
Field class have a "children" member, which is a simple list of the
Field objects, if any, that are contained. The "children" list can be
directly accessed by code using the object. The "children" list will be
empty if this Protocol or Field contains no Fields.
Furthermore, the Packet class is a sub-class of the PacketList class.
The PacketList class provides methods to look for protocols and fields.
The term "item" is used when the item being looked for can be
a protocol or a field:
item_exists(name) - checks if an item exists in the PacketList
get_items(name) - returns a PacketList of all matching items
General Notes
=============
Generally, parsing XML is slow. If you're writing a script to parse
the PDML output of tshark, pass a read filter with "-R" to tshark to
try to reduce as much as possible the number of packets coming out of tshark.
The less your script has to process, the faster it will be.
tools/msnchat
=============
tools/msnchat is a sample Python program that uses WiresharkXML to parse
PDML. Given one or more capture files, it runs tshark on each of them,
providing a read filter to reduce tshark's output. It finds MSN Chat
conversations in the capture file and produces nice HTML showing the
conversations. It has only been tested with capture files containing
non-simultaneous chat sessions, but was written to more-or-less handle any
number of simultaneous chat sessions.
pdml2html.xsl
=============
pdml2html.xsl is a XSLT file to convert PDML files into HTML.
See https://gitlab.com/wireshark/wireshark/-/wikis/PDML for more details.
|
