doc/README.xml-output

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