doc/extcap.pod

   1
   2 =head1 NAME
   3
   4 extcap - The extcap interface
   5
   6 =head1 DESCRIPTION
   7
   8 The extcap interface is a versatile plugin interface that allows external binaries
   9 to act as capture interfaces directly in wireshark. It is used in scenarios, where
  10 the source of the capture is not a traditional capture model
  11 (live capture from an interface, from a pipe, from a file, etc). The typical
  12 example is connecting esoteric hardware of some kind to the main wireshark app.
  13
  14 Without extcap, a capture can always be achieved by directly writing to a capture file:
  15
  16     the-esoteric-binary --the-strange-flag --interface=stream1 --file dumpfile.pcap &
  17     wireshark dumpfile.pcap
  18
  19 but the extcap interface allows for such a connection to be easily established and
  20 configured using the wireshark GUI.
  21
  22 The extcap subsystem is made of multiple extcap binaries that are automatically
  23 called by the GUI in a row. In the following chapters we will refer to them as
  24 "the extcaps".
  25
  26 Extcaps may be any binary or script within the extcap directory. Please note, that scripts
  27 need to be executable without prefacing a script interpreter before the call. To go deeper
  28 into the extcap utility development, please refer to README.extcap.
  29
  30 WINDOWS USER: Because of restrictions directly calling the script may not always work.
  31 In such a case, a batch file may be provided, which then in turn executes the script. Please
  32 refer to doc/extcap_example.py for more information.
  33
  34 =head1 GRAMMAR ELEMENTS
  35
  36 Grammar elements:
  37
  38 =over 4
  39
  40 =item arg (options)
  41
  42 argument for CLI calling
  43
  44 =item number
  45
  46 Reference # of argument for other values, display order
  47
  48 =item call
  49
  50 Literal argument to call (--call=...)
  51
  52 =item display
  53
  54 Displayed name
  55
  56 =item default
  57
  58 Default value, in proper form for type
  59
  60 =item range
  61
  62 Range of valid values for UI checking (min,max) in proper form
  63
  64 =item type
  65
  66 Argument type for UI filtering for raw, or UI type for selector:
  67
  68     integer
  69     unsigned
  70     long (may include scientific / special notation)
  71     float
  72     selector (display selector table, all values as strings)
  73     boolean (display checkbox)
  74     radio (display group of radio buttons with provided values, all values as strings)
  75     fileselect (display a dialog to select a file from the filesystem, value as string)
  76     multicheck (display a textbox for selecting multiple options, values as strings)
  77     password (display a textbox with masked text)
  78     timestamp (display a calendar)
  79
  80 =item value (options)
  81
  82     Values for argument selection
  83     arg     Argument # this value applies to
  84
  85 =back
  86
  87 =head1 EXAMPLES
  88
  89 Example 1:
  90
  91     arg {number=0}{call=--channel}{display=Wi-Fi Channel}{type=integer}{required=true}
  92     arg {number=1}{call=--chanflags}{display=Channel Flags}{type=radio}
  93     arg {number=2}{call=--interface}{display=Interface}{type=selector}
  94     value {arg=0}{range=1,11}
  95     value {arg=1}{value=ht40p}{display=HT40+}
  96     value {arg=1}{value=ht40m}{display=HT40-}
  97     value {arg=1}{value=ht20}{display=HT20}
  98     value {arg=2}{value=wlan0}{display=wlan0}
  99
 100 Example 2:
 101
 102     arg {number=0}{call=--usbdevice}{USB Device}{type=selector}
 103     value {arg=0}{call=/dev/sysfs/usb/foo/123}{display=Ubertooth One sn 1234}
 104     value {arg=0}{call=/dev/sysfs/usb/foo/456}{display=Ubertooth One sn 8901}
 105
 106 Example 3:
 107
 108     arg {number=0}{call=--usbdevice}{USB Device}{type=selector}
 109     arg {number=1}{call=--server}{display=IP address for log server}{type=string}{validation=(?:\d{1,3}\.){3}\d{1,3}}
 110     flag {failure=Permission denied opening Ubertooth device}
 111
 112 Example 4:
 113     arg {number=0}{call=--username}{display=Username}{type=string}
 114     arg {number=1}{call=--password}{display=Password}{type=password}
 115
 116 Example 5:
 117     arg {number=0}{call=--start}{display=Start Time}{type=timestamp}
 118     arg {number=1}{call=--end}{display=End Time}{type=timestamp}
 119
 120 =head1 Security awareness
 121
 122 =over 4
 123
 124 =item - Users running wireshark as root, we can't save you
 125
 126 =item - Dumpcap retains suid/setgid and group+x permissions to allow users in wireshark group only
 127
 128 =item - Third-party capture programs run w/ whatever privs they're installed with
 129
 130 =item - If an attacker can write to a system binary directory, we're game over anyhow
 131
 132 =item - Reference the folders tab in the wireshark->about information, to see from which directory extcap is being run
 133
 134 =back
 135
 136 =head1 SEE ALSO
 137
 138 wireshark(1), tshark(1), dumpcap(1), androiddump(1), sshdump(1), randpktdump(1)
 139
 140 =head1 NOTES
 141
 142 B<Extcap> is feature of B<Wireshark>.  The latest version
 143 of B<Wireshark> can be found at L<https://www.wireshark.org>.
 144
 145 HTML versions of the Wireshark project man pages are available at:
 146 L<https://www.wireshark.org/docs/man-pages>.