1ARP-SCAN(1) General Commands Manual ARP-SCAN(1)
2
6 arp-scan - Send ARP requests to target hosts and display responses
7
9 arp-scan [options] [hosts...]
10 Target hosts must be specified on the command line unless the --file or
12 --localnet option is used.
13 Targets can be IPv4 addresses or hostnames. You can also use CIDR nota‐
15 tion (10.0.0.0/24) (network and broadcast included), ranges
16 (10.0.0.1-10.0.0.10), and network:mask (10.0.0.0:255.255.255.0).
17
19 arp-scan sends ARP request packets to the specified hosts and displays
20 any responses received. The network interface can be specified with the
21 --interface option. If no interface is specified, arp-scan will pick
22 the lowest numbered, configured up interface (excluding loopback).
23 arp-scan uses raw sockets, which requires privileges on some systems:
25 Linux with POSIX.1e capabilities support using libcap:
27 arp-scan is capabilities aware. It requires CAP_NET_RAW in the
28 permitted set and only enables that capability for the required
29 functions. use setcap cap_net_raw+p /path/to/arp-scan to add
30 CAP_NET_RAW to the permitted set of the arp-scan executable.
31 Capabilities support also makes SUID root much safer because
32 arp-scan will drop all capabilities except CAP_NET_RAW and will
33 not run with full root privileges.
34 BSD and macOS:
36 You need read/write access to /dev/bpf*
37 Any operating system:
39 Running as root or SUID root will work on any OS but other meth‐
40 ods are preferable where possible.
41 ARP only operates on the local network, and cannot be routed. Although
43 the ARP protocol uses IPv4 addresses, it is not an IP protocol and arp-
44 scan can be used on interfaces without an IPv4 address.
45 One ARP request is sent for each target. If a host does not respond,
47 the request will be re-sent once more. The number of retries can be
48 changed with the --retry option. Reducing the number of retries will
49 reduce the scanning time at the risk of missing some results due to
50 packet loss.
51 You can specify the bandwidth that arp-scan will use with the --band‐
53 width option. The default is 256000 bits per second. Increasing the
54 bandwidth will reduce scanning time, but setting the bandwidth too high
55 may cause a high broadcast packet rate. Another way to specify the
56 packet rate is with the --interval option.
57 The time for a single-pass scan (i.e. with --retry=1) is:
59 time=n×i+t+o
61 Where n is the number of hosts, i is the interval (given with --inter‐
63 val or calculated from --bandwidth), t is the timeout (specified with
64 --timeout) and o is the overhead time taken to load the target list and
65 read the MAC/Vendor mapping files. The overhead is normally negligible
66 (typically around 100ms) but can be reduced further by the --quiet op‐
67 tion. For small lists of hosts, the timeout value will dominate, but
68 for large lists the packet interval is the most important value.
69 Any part of the ARP request may be modified through the use of the
71 --arpXXX options as shown in the table below:
72 ┌────────────────────────────────────────────────────┐
74 │ ARP Request Packet Options │
75 ├───────┬──────┬──────────┬──────────────────────────┤
76 │Field │ Bits │ Option │ Default │
77 ├───────┼──────┼──────────┼──────────────────────────┤
78 │ar$hrd │ 16 │ --arphrd │ 1 (ARPHRD_ETHER) │
79 │ar$pro │ 16 │ --arppro │ 0x0800 │
80 │ar$hln │ 8 │ --arphln │ 6 (ETH_ALEN) │
81 │ar$pln │ 8 │ --arppln │ 4 (IPv4) │
82 │ar$op │ 16 │ --arpop │ 1 (ARPOP_REQUEST) │
83 │ar$sha │ 48 │ --arpsha │ interface h/w address │
84 │ar$spa │ 32 │ --arpspa │ interface IPv4 address │
85 │ar$tha │ 48 │ --arptha │ 00:00:00:00:00:00 │
86 │ar$tpa │ 32 │ None │ target host IPv4 address │
87 └───────┴──────┴──────────┴──────────────────────────┘
88 The most common option is --arpspa, which sets the source IPv4 address
89 in the ARP request, allowing the ARP request to use a different source
90 address from the interface address. This allows the use of arp-scan on
91 interfaces with no IPv4 address. Note: Setting ar$spa to the target's
92 IP address causes some operating systems to report an address clash
93 when they receive an ARP request for their own address.
94 You can also change the values in the Ethernet frame header as shown
96 below:
97 ┌────────────────────────────────────────────────────────┐
99 │ Ethernet Header Options │
100 ├───────────────┬──────┬─────────────┬───────────────────┤
101 │Field │ Bits │ Option │ Default │
102 ├───────────────┼──────┼─────────────┼───────────────────┤
103 │Dest Address │ 48 │ --destaddr │ ff:ff:ff:ff:ff:ff │
104 │Source Address │ 48 │ --srcaddr │ interface address │
105 │Protocol Type │ 16 │ --prototype │ 0x0806 (ARP) │
106 └───────────────┴──────┴─────────────┴───────────────────┘
107 The --destaddr option which sets the destination Ethernet address is
108 the only one that is commonly used.
109 By default, ARP responses are displayed in the following format:
111 <IPv4 Address> <MAC Address> <Vendor Details>
113 Where IPv4 Address is the IP address of the responding target, MAC Ad‐
115 dress is its link-layer address and Vendor Details are the vendor de‐
116 tails decoded from the hardware address. The output fields are sepa‐
117 rated by a single tab character. You can change the output format with
118 the --format option.
119 The responses are displayed in the order they are received, which can
121 be different from the order the requests were sent because some hosts
122 may respond quicker than others.
123 The vendor decoding uses the files ieee-oui.txt and mac-vendor.txt.
125 ieee-oui.txt is generated from the IEEE MA-L (OUI), MA-M, MA-S (OUI36)
126 and IAB registries. mac-vendor.txt contains additional MAC to Vendor
127 mappings, and can be used to add custom mappings. get-oui can be used
128 to update ieee-oui.txt with the latest data from the IEEE registries.
129 All IPv4 hosts should respond to ARP request packets, including hosts
131 with packet filtering such as firewalls. This makes arp-scan a useful
132 tool to discover all active IPv4 hosts on the local network.
133
135 Where an option takes a value, that value is specified as a letter in
136 angle brackets. The letter indicates the type of data that is expected:
137 <s> Character string.
139 <i> Decimal integer, or hex if preceeded by 0x e.g. 2048 or 0x800.
141 <f> Floating point decimal number.
143 <m> MAC address, e.g. 01:23:45:67:89:ab or 01-23-45-67-89-ab (case
145 insensitive)
146 <a> IPv4 address e.g. 10.0.0.1
148 <h> Hex encoded binary data. No leading 0x. (case insensitive).
150 <x> Something else - see option description.
152 General Options
154 --help or -h
155 Display this usage message and exit.
156 --verbose or -v
158 Display verbose progress messages. Can be used than once to in‐
159 crease verbosity. Max=3.
160 --version or -V
162 Display program version and exit. Displays the version, license
163 details, libpcap version, and whether POSIX.1e capability sup‐
164 port is included.
165 --interface=<s> or -I <s>
167 Use network interface <s>. If this option is not specified,
168 arp-scan will search the system interface list for the lowest
169 numbered, configured up interface (excluding loopback).
170 Host Selection
172 --file=<s> or -f <s>
173 Read hostnames or addresses from the specified file. One name
174 or address pattern per line. Use "-" for stdin.
175 --localnet or -l
177 Generate addresses from interface configuration. Generates list
178 from interface address and netmask (network and broadcast in‐
179 cluded). You cannot use the --file option or give targets on the
180 command line. Use --interface to specify the interface.
181 MAC/Vendor Mapping Files
183 --ouifile=<s> or -O <s>
184 Use IEEE registry vendor mapping file <s>. Default is ieee-
185 oui.txt in the current directory. If that is not found
186 /usr/share/arp-scan/ieee-oui.txt is used.
187 --macfile=<s> or -m <s>
189 Use custom vendor mapping file <s>. Default is mac-vendor.txt
190 in the current directory. If that is not found /etc/arp-
191 scan/mac-vendor.txt is used.
192 Output Format Control
194 --quiet or -q
195 Display minimal output for each responding host. Only the IP
196 address and MAC address are displayed. Reduces memory usage by
197 about 5MB because the vendor mapping files are not used. Only
198 the ${ip} and ${mac} fields are available for the --format op‐
199 tion if --quiet is specified.
200 --plain or -x
202 Supress header and footer text. Only display the responding
203 host details. Useful if the output will be parsed by a script.
204 --ignoredups or -g
206 Don't display duplicate packets. By default duplicate packets
207 are flagged with (DUP: n) where n is the number of times this
208 host has responded.
209 --rtt or -D
211 Calculate and display the packet round-trip time. The time is
212 displayed in milliseconds and fractional microseconds. Makes the
213 ${rtt} field available for --format.
214 --format=<s> or -F <s>
216 Specify the output format string. The format is a string that
217 will be output for each responding host. Host details can be in‐
218 cluded by inserting references to fields using the syntax
219 "${field[;width]}". Fields are displayed right- aligned unless
220 the width is negative in which case left alignment will be used.
221 The following case- insensitive field names are recognised:
222 IP Host IPv4 address in dotted quad format
225 Name Host name if --resolve option given
226 MAC Host MAC address xx:xx:xx:xx:xx:xx
227 HdrMAC Ethernet source addr if different
228 Vendor Vendor details string
229 Padding Padding after ARP packet in hex if nonzero
230 Framing Framing type if not Ethernet_II
231 VLAN 802.1Q VLAN ID if present
232 Proto ARP protocol if not 0x0800
233 DUP Packet number for duplicate packets (>1)
234 RTT Round trip time if --rtt option given
235 Only the ${ip} and ${mac} fields are available if the --quiet
237 option is specified.
238 Any characters that are not fields are output verbatim. "\" in‐
240 troduces escapes:
241 \n newline
244 \r carriage return
245 \t tab
246 \ suppress special meaning for following character
247 You should enclose the --format argument in 'single quotes' to
249 protect special characters from the shell.
250 Example: --format='${ip}\t${mac}\t${vendor}'
252 Host List Randomisation
254 --random or -R
255 Randomise the target host list.
256 --randomseed=<i>
258 Seed the pseudo random number generator. Useful if you want a
259 reproducible --random order.
260 Output Timing and Retry
262 --retry=<i> or -r <i>
263 Set total number of attempts per host to <i>, default=2.
264 --backoff=<f> or -b <f>
266 Set backoff factor to <f>, default=1.50. Multiplies timeout by
267 <f> for each pass.
268 --timeout=<i> or -t <i>
270 Set initial per host timeout to <i> ms, default=500. This time‐
271 out is for the first packet sent to each host. subsequent time‐
272 outs are multiplied by the backoff factor which is set with
273 --backoff.
274 --interval=<x> or -i <x>
276 Set minimum packet interval to <x>. This controls the outgoing
277 bandwidth usage by limiting the packet rate. If you want to use
278 up to a given bandwidth it is easier to use the --bandwidth op‐
279 tion instead. The interval is in milliseconds, or microseconds
280 if "u" is appended.
281 --bandwidth=<x> or -B <x>
283 Set outbound bandwidth to <x>, default=256000. The value is in
284 bits per second. Append K for kilobits or M for megabits (deci‐
285 mal multiples). You cannot specify both --interval and --band‐
286 width.
287 DNS Resolution
289 --numeric or -N
290 Targets must be IP addresses, not hostnames. Can reduce startup
291 time for large target lists.
292 --resolve or -d
294 Resolve responding addresses to hostnames. The default output
295 format will display the hostname instead of the IPv4 address.
296 This option makes the ${name} field available for the --format
297 option.
298 Output ARP Packet
300 --arpsha=<m> or -u <m>
301 Set the ARP source Ethernet address. Sets the 48-bit ar$sha
302 field but does not change the hardware address in the frame
303 header, see --srcaddr for how to change that address. Default is
304 the Ethernet address of the outgoing interface.
305 --arptha=<m> or -w <m>
307 Set the ARP target Ethernet address. Sets the 48-bit ar$tha
308 field. The default is zero, because this field is not used for
309 ARP request packets.
310 --arphrd=<i> or -H <i>
312 Set the ARP hardware type, default=1. Sets the 16-bit ar$hrd
313 field. The default is 1 (ARPHRD_ETHER). Many operating systems
314 also respond to 6 (ARPHRD_IEEE802).
315 --arppro=<i> or -p <i>
317 Set the ARP protocol type, default=0x0800. Sets the 16-bit
318 ar$pro field. Most operating systems only respond to 0x0800
319 (IPv4).
320 --arphln=<i> or -a <i>
322 Set the hardware address length, default=6. Sets the 8-bit
323 ar$hln field. The lengths of the ar$sha and ar$tha fields are
324 not changed by this option; it only changes the ar$hln field.
325 --arppln=<i> or -P <i>
327 Set the protocol address length, default=4. Sets the 8-bit
328 ar$pln field. The lengths of the ar$spa and ar$tpa fields are
329 not changed by this option; it only changes the ar$pln field.
330 --arpop=<i> or -o <i>
332 Specify the ARP operation, default=1. Sets the 16-bit ar$op
333 field. Most operating systems only respond to the value 1 (AR‐
334 POP_REQUEST).
335 --arpspa=<a> or -s <a>
337 Set the source IPv4 address. The address should be in dotted
338 quad format, or the string "dest" which sets the source address
339 to the target host address. The default is the outgoing inter‐
340 face address. Sets the 32-bit ar$spa field. Some operating
341 systems only respond if the source address is within the network
342 of the receiving interface. Setting ar$spa to the destination
343 IP address can cause some operating systems to report an address
344 clash.
345 Output Ethernet Header
347 --srcaddr=<m> or -S <m>
348 Set the source Ethernet MAC address. Default is the interface
349 MAC address. This sets the address in the Ethernet header. It
350 does not change the address in the ARP packet: use --arpsha to
351 change that address.
352 --destaddr=<m> or -T <m>
354 Set the destination MAC address. Sets the destination address
355 in the Ethernet header. Default is ff:ff:ff:ff:ff:ff (broadcast)
356 Hosts also respond if the request is sent to their unicast ad‐
357 dress, or to a multicast address they are listening on.
358 --prototype=<i> or -y <i>
360 Sets the Ethernet protocol type, default=0x0806. This sets the
361 protocol type field in the Ethernet header.
362 --llc or -L
364 Use RFC 1042 LLC/SNAP encapsulation for 802.2 networks. arp-
365 scan will decode and display ARP responses in both Ethernet-II
366 and IEEE 802.2 formats irrespective of this option.
367 --vlan=<i> or -Q <i>
369 Use 802.1Q tagging with VLAN id <i>. The id should be in the
370 range 0 to 4095. arp-scan will decode and display ARP responses
371 in 802.1Q format irrespective of this option.
372 Misc Options
374 --limit=<i> or -M <i>
375 Exit after the specified number of hosts have responded. arp-
376 scan will exit with status 1 if the number of responding hosts
377 is less than the limit. Can be used in scripts to check if fewer
378 hosts respond without having to parse the output.
379 --pcapsavefile=<s> or -W <s>
381 Write received packets to pcap savefile <s>. ARP responses will
382 be written to the specified file as well as being decoded and
383 displayed.
384 --snap=<i> or -n <i>
386 Set the pcap snap length to <i>. Default=64. Specifies the
387 frame capture length, including the Ethernet header. The default
388 is normally sufficient.
389 --retry-send=<i> or -Y <i>
391 Set number of send attempts, default=20.
392 --retry-send-interval=<i> or -E <i>
394 Set interval between send attempts. Interval is in milliseconds
395 or microseconds if "u" is appended. default=5.
396 --padding=<h> or -A <h>
398 Specify padding after packet data. Set padding after the ARP
399 request to hex value <h>.
400
402 arp-scan will exit with 0 on successful completion or >0 if an error
403 was encountered.
404 If the --limit option is specified, arp-scan will also exit with a non-
406 zero exit code if the number of responding hosts is less than the spec‐
407 ified limit.
408
410 /usr/share/arp-scan/ieee-oui.txt
411 List of IEEE OUI (Organisationally Unique Identifier) to vendor
412 mappings.
413 /etc/arp-scan/mac-vendor.txt
415 List of other Ethernet MAC to vendor mappings, including local
416 additions.
417
419 Simple Scan
420 Scan the default network using the interface IPv4 configuration to gen‐
421 erate the list of hosts to scan.
422 $ arp-scan --localnet
424 Interface: eth0, type: EN10MB, MAC: 50:65:f3:f0:6d:7c, IPv4: 10.0.0.106
425 Starting arp-scan 1.9.9 with 256 hosts (https://github.com/royhills/arp-scan)
426 10.0.0.14 a4:1f:72:7f:25:bb Dell Inc.
427 10.0.0.22 10:60:4b:73:43:de Hewlett Packard
428 10.0.0.74 00:0c:29:90:07:e9 VMware, Inc.
429 10.0.0.75 00:0c:29:66:9e:c2 VMware, Inc.
430 10.0.0.76 00:0c:29:d0:e1:ea VMware, Inc.
431 10.0.0.82 9c:b6:54:bb:f3:ec Hewlett Packard
432 10.0.0.84 00:21:9b:fd:b9:b3 Dell Inc.
433 10.0.0.85 00:02:b3:eb:5a:f8 Intel Corporation
434 10.0.0.91 00:9c:02:a5:7b:29 Hewlett Packard
435 10.0.0.92 d4:ae:52:d0:07:6f Dell Inc.
436 10.0.0.93 d4:ae:52:d0:04:9b Dell Inc.
437 10.0.0.96 9c:b6:54:bb:f5:35 Hewlett Packard
438 10.0.0.97 00:0c:29:0e:95:20 VMware, Inc.
439 10.0.0.104 50:65:f3:f0:70:a4 Hewlett Packard
440 15 packets received by filter, 0 packets dropped by kernel
442 Ending arp-scan 1.9.9: 256 hosts scanned in 1.532 seconds (167.10 hosts/sec). 14 responded
443 Output Formatting
445 Scan all hosts in 10.0.0.0/24 using interface eth0. Calculate round-
446 trip time and display in aligned columns using a custom format.
447 $ arp-scan -I eth0 --rtt --format='|${ip;-15}|${mac}|${rtt;8}|' 10.0.0.0/24
449 Interface: eth0, type: EN10MB, MAC: 50:65:f3:f0:6d:7c, IPv4: 10.0.0.106
450 Starting arp-scan 1.9.9 with 256 hosts (https://github.com/royhills/arp-scan)
451 |10.0.0.14 |a4:1f:72:7f:25:bb| 0.280|
452 |10.0.0.22 |10:60:4b:73:43:de| 0.293|
453 |10.0.0.74 |00:0c:29:90:07:e9| 0.380|
454 |10.0.0.75 |00:0c:29:66:9e:c2| 0.311|
455 |10.0.0.76 |00:0c:29:d0:e1:ea| 0.326|
456 |10.0.0.82 |9c:b6:54:bb:f3:ec| 0.216|
457 |10.0.0.84 |00:21:9b:fd:b9:b3| 0.244|
458 |10.0.0.85 |00:02:b3:eb:5a:f8| 0.244|
459 |10.0.0.91 |00:9c:02:a5:7b:29| 0.209|
460 |10.0.0.92 |d4:ae:52:d0:07:6f| 0.289|
461 |10.0.0.93 |d4:ae:52:d0:04:9b| 0.278|
462 |10.0.0.96 |9c:b6:54:bb:f5:35| 0.255|
463 |10.0.0.97 |00:0c:29:0e:95:20| 0.288|
464 |10.0.0.104 |50:65:f3:f0:70:a4| 0.263|
465 14 packets received by filter, 0 packets dropped by kernel
467 Ending arp-scan 1.9.9: 256 hosts scanned in 2.032 seconds (125.98 hosts/sec). 14 responded
468 CSV Output
470 --plain removes extraneous output.
471 $ arp-scan -I eth0 --plain --format='${ip},${mac},"${vendor}"' 10.0.0.0/24
473 10.0.0.14,a4:1f:72:7f:25:bb,"Dell Inc."
474 10.0.0.22,10:60:4b:73:43:de,"Hewlett Packard"
475 10.0.0.74,00:0c:29:90:07:e9,"VMware, Inc."
476 10.0.0.75,00:0c:29:66:9e:c2,"VMware, Inc."
477 10.0.0.76,00:0c:29:d0:e1:ea,"VMware, Inc."
478 10.0.0.82,9c:b6:54:bb:f3:ec,"Hewlett Packard"
479 10.0.0.84,00:21:9b:fd:b9:b3,"Dell Inc."
480 10.0.0.85,00:02:b3:eb:5a:f8,"Intel Corporation"
481 10.0.0.91,00:9c:02:a5:7b:29,"Hewlett Packard"
482 10.0.0.92,d4:ae:52:d0:07:6f,"Dell Inc."
483 10.0.0.93,d4:ae:52:d0:04:9b,"Dell Inc."
484 10.0.0.96,9c:b6:54:bb:f5:35,"Hewlett Packard"
485 10.0.0.97,00:0c:29:0e:95:20,"VMware, Inc."
486 10.0.0.104,50:65:f3:f0:70:a4,"Hewlett Packard"
487
489 get-oui(1)
490 arp-fingerprint(1)
492 http://www.royhills.co.uk/wiki/ The arp-scan wiki page.
494 https://github.com/royhills/arp-scan The arp-scan homepage.
496 November 9, 2022 ARP-SCAN(1)