ciscodump(1)

1CISCODUMP(1)                                                      CISCODUMP(1)
2
3
4

NAME

6       ciscodump - Provide interfaces to capture from a remote Cisco device
7       through SSH.
8

SYNOPSIS

10       ciscodump [ --help ] [ --version ] [ --extcap-interfaces ]
11       [ --extcap-dlts ] [ --extcap-interface=<interface> ]
12       [ --extcap-config ] [ --extcap-capture-filter=<capture filter> ]
13       [ --capture ] [ --fifo=<path to file or pipe> ]
14       [ --remote-host=<IP address> ] [ --remote-port=<TCP port> ]
15       [ --remote-username=<username> ] [ --remote-password=<password> ]
16       [ --remote-filter=<filter> ] [ --sshkey=<public key path> ]
17       [ --remote-interface=<interface> ] [ --remote-count=<count> ]
18
19       ciscodump --extcap-interfaces
20
21       ciscodump --extcap-interface=ciscodump --extcap-dlts
22
23       ciscodump --extcap-interface=ciscodump --extcap-config
24
25       ciscodump --extcap-interface=ciscodump --fifo=<path to file or pipe>
26       --capture --remote-host=remotedevice --remote-port=22
27       --remote-username=user --remote-interface=<the device interface>
28       --remote-count=<count>
29

DESCRIPTION

31       Ciscodump is an extcap tool that relies on Cisco EPC to allow a user to
32       run a remote capture on a Cisco device in a SSH connection. It supports
33       IOS, IOS-XE based device and ASA devices.
34
35       The tool configures capture on the device, reads data and removes
36       configuration from the device. Provided credentials must allow the tool
37       to configure the device.
38
39       When capture is started, packets are provided as they are received from
40       the device. Capture stops when:
41
42       •   requested count of packets is reached (--remote-count is mandatory)
43
44       •   when capture finishes on the device (e.g. capture buffer is full)
45
46       •   the capture is stopped by the user
47
48       Capture performance depends on a device type. The tool tries to read
49       packets as soon as they received, but is usually slower than capturing
50       device captures packets. Therefore packets are read in batches.
51
52       IOS/IOS-XE provides only access to all captured packets from the top.
53       Therefore reading of second batch means to read all packets from first
54       batch, but ignore them and then read new packets in second batch.
55
56       ASA provides access to specific packet so tool reads every packet just
57       once.
58
59   SUPPORTED CISCO SOFTWARE
60       The application supports IOS version is 12.4 and higher. The IOS
61       version supporting capture feature is 12.4(20)T and higher. More
62       details can be found here:
63       https://www.cisco.com/c/en/us/products/collateral/ios-nx-os-software/ios-embedded-packet-capture/datasheet_c78-502727.html
64
65       The application supports IOS-XE version 16.1 and higher. Search for
66       "Embedded Packet Capture Configuration Guide, Cisco IOS XE" to get more
67       details.
68
69       The application supports ASA version 8.4 and higher. More details can
70       be found here:
71       https://community.cisco.com/t5/security-documents/asa-using-packet-capture-to-troubleshoot-asa-firewall/ta-p/3129889
72

OPTIONS

74       --help
75
76           Print program arguments.
77
78       --version
79
80           Print program version.
81
82       --extcap-interfaces
83
84           List available interfaces.
85
86       --extcap-interface=<interface>
87
88           Use specified interfaces.
89
90       --extcap-dlts
91
92           List DLTs of specified interface.
93
94       --extcap-config
95
96           List configuration options of specified interface.
97
98       --capture
99
100           Start capturing from specified interface and save it in place
101           specified by --fifo.
102
103       --fifo=<path to file or pipe>
104
105           Save captured packet to file or send it through pipe.
106
107       --remote-host=<remote host>
108
109           The address of the remote host for capture.
110
111       --remote-port=<remote port>
112
113           The SSH port of the remote host.
114
115       --remote-username=<username>
116
117           The username for ssh authentication.
118
119       --remote-password=<password>
120
121           The password to use (if not ssh-agent and pubkey are used).
122           WARNING: the passwords are stored in plaintext and visible to all
123           users on this system. It is recommended to use keyfiles with a SSH
124           agent.
125
126       --remote-filter=<filter>
127
128           The remote filter on the device. This is a capture filter that
129           follows the Cisco standards.
130
131           For IOS/IOS-XE see
132           https://www.cisco.com/c/en/us/support/docs/ip/access-lists/26448-ACLsamples.html.
133
134           For ASA see
135           https://www.cisco.com/c/en/us/td/docs/security/asa/asa96/configuration/firewall/asa-96-firewall-config/access-acls.html.
136
137           Multiple filters can be specified using a comma between them.
138           BEWARE: when using a filter, the default behavior is to drop all
139           the packets except the ones that fall into the filter.
140
141           Examples for IOS/IOS-XE:
142
143               permit ip host MYHOST any, permit ip any host MYHOST (capture the traffic for MYHOST)
144
145               deny ip host MYHOST any, deny ip any host MYHOST, permit ip any any (capture all the traffic except MYHOST)
146
147           Examples for ASA:
148
149               permit any4 host MYHOST, permit host MYHOST any4 (capture IPv4 traffic for MYHOST)
150
151               Note
152               Different capture types support or do not support specific ACL
153               keywords. The tool is not able to check it, just tries to
154               configure it. If error occurs, the tool just reports it and
155               terminates. Debris are left in configuration in this case.
156
157       --sshkey=<SSH private key path>
158
159           The path to a private key for authentication.
160
161       --remote-interface=<remote interface>
162
163           The remote network interface to capture from. One interface or list
164           of interface names can be used. Iterfaces are separated by comma.
165           Interface names must be supported by the device.
166
167           There are interface names causing different capture types. They are
168           specific to used Cisco software.
169
170           IOS special names
171
172           •   process-switched - capture process switched packets in both
173               directions
174
175           •   from-us - capture process switched packets originating at the
176               device
177
178           IOS-XE special names
179
180           •   control-plane - captures in/out packets touching control plane
181
182           ASA special names
183
184           •   asp-drop - capture packets dropped by all asp categories
185
186           •   TYPE---ifname - syntax to refer ASA capture types, see
187               https://www.cisco.com/c/en/us/td/docs/security/asa/asa-cli-reference/A-H/asa-command-ref-A-H/ca-cld-commands.html#wp2435483314
188
189               •   isakmp---ifname - capture isakmp packets
190
191               •   lacp---ifname - capture lacp packets (just physical
192                   interfaces are supported)
193
194               •   tls-proxy---ifname - capture tls-proxy packets
195
196               •   inline-tag---ifname - capture all SGT tagget packets
197
198               •   raw-data---ifname - same as ifname
199
200           •   syntax to capture decrypted traffic for some of capture types:
201
202               •   isakmp/decrypted---ifname - capture isakmp packets
203                   including decrypted payload
204
205               •   tls-proxy/decrypted---ifname - capture tls-proxy packets
206                   including decrypted payload
207
208               •   inline-tag/decrypted---ifname - capture inline-tag packets
209                   including decrypted payload
210
211               •   raw-data/decrypted---ifname - capture raw-data packets
212                   including decrypted payload
213
214           Use e. g. isakmp/decrypted---outside to capture encrypted and
215           decrypted isakmp traffic on outside interface.
216
217       --remote-count=<count>
218
219           Count of packets to capture. Capture is stopped when count is
220           reached.
221
222       --extcap-capture-filter=<capture filter>
223
224           Unused (compatibility only).
225

EXAMPLES

227       To see program arguments:
228
229           ciscodump --help
230
231       To see program version:
232
233           ciscodump --version
234
235       To see interfaces:
236
237           ciscodump --extcap-interfaces
238
239       Only one interface (ciscodump) is supported.
240
241       Example output
242
243           interface {value=ciscodump}{display=SSH remote capture}
244
245       To see interface DLTs:
246
247           ciscodump --extcap-interface=ciscodump --extcap-dlts
248
249       Example output
250
251           dlt {number=147}{name=ciscodump}{display=Remote capture dependent DLT}
252
253       To see interface configuration options:
254
255           ciscodump --extcap-interface=ciscodump --extcap-config
256
257       Example output
258
259           ciscodump --extcap-interface=ciscodump --extcap-config
260           arg {number=0}{call=--remote-host}{display=Remote SSH server address}
261               {type=string}{tooltip=The remote SSH host. It can be both an IP address or a hostname}
262               {required=true}{group=Server}
263           arg {number=1}{call=--remote-port}{display=Remote SSH server port}
264               {type=unsigned}{default=22}{tooltip=The remote SSH host port (1-65535)}
265               {range=1,65535}{group=Server}
266           arg {number=2}{call=--remote-username}{display=Remote SSH server username}
267               {type=string}{default=<current user>}{tooltip=The remote SSH username. If not provided, the current user will be used}
268               {group=Authentication}
269           arg {number=3}{call=--remote-password}{display=Remote SSH server password}
270               {type=password}{tooltip=The SSH password, used when other methods (SSH agent or key files) are unavailable.}
271               {group=Authentication}
272           arg {number=4}{call=--sshkey}{display=Path to SSH private key}
273               {type=fileselect}{tooltip=The path on the local filesystem of the private ssh key}
274               {group=Authentication}
275           arg {number=5}{call=--proxycommand}{display=ProxyCommand}
276               {type=string}{tooltip=The command to use as proxy for the SSH connection}{group=Authentication}
277           arg {number=6}{call--sshkey-passphrase}{display=SSH key passphrase}
278               {type=password}{tooltip=Passphrase to unlock the SSH private key}{group=Authentication
279           arg {number=7}{call=--remote-interface}{display=Remote interface}
280               {type=string}{tooltip=The remote network interface used for capture}
281               {required=true}{group=Capture}
282           arg {number=8}{call=--remote-filter}{display=Remote capture filter}
283               {type=string}{tooltip=The remote capture filter}{default=<filter to exclude current host>}
284               {group=Capture}
285           arg {number=9}{call=--remote-count}{display=Packets to capture}
286               {type=unsigned}{tooltip=The number of remote packets to capture.}
287               {required=true}{group=Capture}
288           arg {number=10}{call=--debug}{display=Run in debug mode}
289               {type=boolflag}{default=false}{tooltip=Print debug messages}
290               {required=false}{group=Debug}
291           arg {number=11}{call=--debug-file}{display=Use a file for debug}
292               {type=string}{tooltip=Set a file where the debug messages are written}
293               {required=false}{group=Debug}
294
295       To capture on IOS/IOS-XE:
296
297           ciscodump --extcap-interface ciscodump --fifo=/tmp/cisco.pcap --capture --remote-host 192.168.1.10
298               --remote-username user --remote-interface gigabit0/0,gigiabit0/1
299               --remote-filter "permit ip host 192.168.1.1 any, permit ip any host 192.168.1.1"
300               --remote-count=10
301
302       To capture on IOS/IOS-XE:
303
304           ciscodump --extcap-interface ciscodump --fifo=/tmp/cisco.pcap --capture --remote-host 192.168.1.10
305               --remote-username user --remote-interface outside,dmz
306               --remote-filter "permit host 192.168.1.1 any4, permit any4 host 192.168.1.1"
307               --remote-count=10
308
309           ciscodump --extcap-interface ciscodump --fifo=/tmp/cisco.pcap --capture --remote-host 192.168.1.10
310               --remote-username user --remote-interface raw-data/decrypted---outside
311               --remote-filter "permit host 192.168.1.1 any4, permit any4 host 192.168.1.1"
312

KNOWN ISSUES

314       When capture stopped by the user before it finishes on Windows
315       platform, configuration is not cleared on the device. Next run will
316       probably fails because parts of configuration already exists on the
317       device.
318
319       Reading performance on IOS/IOS-XE is poor because re-reading of capture
320       buffer over and over.
321
322       The configuration of the capture on the device is a multi-step process.
323       If the SSH connection is interrupted during it, the configuration can
324       be in an inconsistent state. That can happen also if the capture is
325       stopped and ciscodump can’t clean the configuration up. In this case it
326       is necessary to log into the device and manually clean the
327       configuration, removing configuration elements:
328
329       •   IOS
330
331           •   capture points WSC_P_<number> (depends on count of capture
332               interfaces)
333
334           •   the capture buffer WSC_B
335
336           •   the capture capture acl WSC_ACL (if filter was used)
337
338       •   IOS-XE
339
340           •   the capture WSC
341
342           •   the capture capture acl WSC_ACL (if filter was used)
343
344       •   ASA
345
346           •   the capture WSC
347
348           •   the capture capture acl WSC_ACL (if filter was used)
349
350       On IOS platforms, only IPv4 commands issued and only IPv4 packets are
351       captured.
352

NOTES

357       ciscodump is part of the Wireshark distribution. The latest version of
358       Wireshark can be found at https://www.wireshark.org.
359
360       HTML versions of the Wireshark project man pages are available at
361       https://www.wireshark.org/docs/man-pages.
362

AUTHORS

364       Original Author
365       Dario Lombardo <lomato[AT]gmail.com>
366
367
368
369                                  2023-08-31                      CISCODUMP(1)