NAME
arp-scan - The ARP scanner
SYNOPSIS
arp-scan [options] [hosts...]
Target hosts must be specified on the command line unless the --file
option is given, in which case the targets are read from the specified
file instead, or the --localnet option is used, in which case the
targets are generated from the network interface IP address and
netmask.
You will need to be root, or arp-scan must be SUID root, in order to
run arp-scan, because the functions that it uses to read and write
packets require root privilege.
The target hosts can be specified as IP addresses or hostnames. You
can also specify the target as IPnetwork/bits (e.g. 192.168.1.0/24) to
specify all hosts in the given network (network and broadcast addresses
included), IPstart-IPend (e.g. 192.168.1.3-192.168.1.27) to specify all
hosts in the inclusive range, or IPnetwork:NetMask (e.g.
192.168.1.0:255.255.255.0) to specify all hosts in the given network
and mask.
DESCRIPTION
arp-scan sends ARP packets to hosts on the local network and displays
any responses that are received. The network interface to use can be
specified with the --interface option. If this option is not present,
arp-scan will search the system interface list for the lowest numbered,
configured up interface (excluding loopback). By default, the ARP
packets are sent to the Ethernet broadcast address, ff:ff:ff:ff:ff:ff,
but that can be changed with the --destaddr option.
The target hosts to scan may be specified in one of three ways: by
specifying the targets on the command line; by specifying a file
containing the targets with the --file option; or by specifying the
--localnet option which causes all possible hosts on the network
attached to the interface (as defined by the interface address and
mask) to be scanned. For hosts specified on the command line, or with
the --file For hosts specified on the command line, or with the --file
option, you can use either IP addresses or hostnames. You can also use
network specifications IPnetwork/bits, IPstart-IPend, or
IPnetwork:NetMask.
The list of target hosts is stored in memory. Each host in this list
uses 28 bytes of memory, so scanning a Class-B network (65,536 hosts)
requires about 1.75MB of memory for the list, and scanning a Class-A
(16,777,216 hosts) requires about 448MB.
arp-scan supports Ethernet and 802.11 wireless networks. It could also
support token ring and FDDI, but they have not been tested. It does not
support serial links such as PPP or SLIP, because ARP is not supported
on them.
The ARP protocol is a layer-2 (datalink layer) protocol that is used to
determine a host’s layer-2 address given its layer-3 (network layer)
address. ARP was designed to work with any layer-2 and layer-3 address
format, but the most common use is to map IP addresses to Ethernet
hardware addresses, and this is what arp-scan supports. ARP only
operates on the local network, and cannot be routed. Although the ARP
protocol makes use of IP addresses, it is not an IP-based protocol and
arp-scan can be used on an interface that is not configured for IP.
ARP is only used by IPv4 hosts. IPv6 uses NDP (neighbour discovery
protocol) instead, which is a different protocol and is not supported
by arp-scan.
One ARP packet is sent for each for each target host, with the target
protocol address (the ar$tpa field) set to the IP address of this host.
If a host does not respond, then the ARP packet will be re-sent once
more. The maximum number of retries can be changed with the --retry
option. Reducing the number of retries will reduce the scanning time
at the possible risk of missing some results due to packet loss.
You can specify the bandwidth that arp-scan will use for the outgoing
ARP packets with the --bandwidth option. By default, it uses a
bandwidth of 256000 bits per second. Increasing the bandwidth will
reduce the scanning time, but setting the bandwidth too high may result
in an ARP storm which can disrupt network operation. Also, setting the
bandwidth too high can send packets faster than the network interface
can transmit them, which will eventually fill the kernel’s transmit
buffer resulting in the error message: No buffer space available.
Another way to specify the outgoing ARP packet rate is with the
--interval option, which is an alternative way to modify the same
underlying parameter.
The time taken to perform a single-pass scan (i.e. with --retry=1) is
given by:
time = n*i + t + o
Where n is the number of hosts in the list, i is the time interval
between packets (specified with --interval, or calculated from
--bandwidth), t is the timeout value (specified with --timeout) and o
is the overhead time taken to load the targets into the list and read
the MAC/Vendor mapping files. For small lists of hosts, the timeout
value will dominate, but for large lists the packet interval is the
most important value.
With 65,536 hosts, the default bandwidth of 256,000 bits/second (which
results in a packet interval of 2ms), the default timeout of 100ms, and
a single pass ( --retry=1), and assuming an overhead of 1 second, the
scan would take 65536*0.002 + 0.1 + 1 = 132.172 seconds, or about 2
minutes 12 seconds.
Any part of the outgoing ARP packet may be modified through the use of
the various --arpXXX options. The use of some of these options may
make the outgoing ARP packet non RFC compliant. Different operating
systems handle the various non standard ARP packets in different ways,
and this may be used to fingerprint these systems. See arp-
fingerprint(1) for information about a script which uses these options
to fingerprint the target operating system.
The table below summarises the options that change the outgoing ARP
packet. In this table, the Field column gives the ARP packet field name
from RFC 826, Bits specifies the number of bits in the field, Option
shows the arp-scan option to modify this field, and Notes gives the
default value and any other notes.
+---------------------------------------------------------------+
| Outgoing ARP Packet Options |
+-------+------+----------+-------------------------------------+
|Field | Bits | Option | Notes |
+-------+------+----------+-------------------------------------+
|ar$hrd | 16 | --arphrd | Default is 1 (ARPHRD_ETHER) |
|ar$pro | 16 | --arppro | Default is 0x0800 |
|ar$hln | 8 | --arphln | Default is 6 (ETH_ALEN) |
|ar$pln | 8 | --arppln | Default is 4 (IPv4) |
|ar$op | 16 | --arpop | Default is 1 (ARPOP_REQUEST) |
|ar$sha | 48 | --arpsha | Default is interface h/w address |
|ar$spa | 32 | --arpspa | Default is interface IP address |
|ar$tha | 48 | --arptha | Default is zero (00:00:00:00:00:00) |
|ar$tpa | 32 | None | Set to the target host IP address |
+-------+------+----------+-------------------------------------+
The most commonly used outgoing ARP packet option is --arpspa, which
sets the source IP address in the ARP packet. This option allows the
outgoing ARP packet to use a different source IP address from the
outgoing interface address. With this option it is possible to use
arp-scan on an interface with no IP address configured, which can be
useful if you want to ensure that the testing host does not interact
with the network being tested.
It is also possible to change the values in the Ethernet frame header
that proceeds the ARP packet in the outgoing packets. The table below
summarises the options that change values in the Ethernet frame header.
+-------------------------------------------------------------------+
| Outgoing Ethernet Frame Options |
+---------------+------+-------------+------------------------------+
|Field | Bits | Option | Notes |
+---------------+------+-------------+------------------------------+
|Dest Address | 48 | --destaddr | Default is ff:ff:ff:ff:ff:ff |
|Source Address | 48 | --srcaddr | Default is interface address |
|Protocol Type | 16 | --prototype | Default is 0x0806 |
+---------------+------+-------------+------------------------------+
The most commonly used outgoing Ethernet frame option is --destaddr,
which sets the destination Ethernet address for the ARP packet.
--prototype is not often used, because it will cause the packet to be
interpreted as a different Ethernet protocol.
Any ARP responses that are received are displayed in the following
format:
<IP Address> <Hardware Address> <Vendor Details>
Where IP Address is the IP address of the responding target, Hardware
Address is its Ethernet hardware address (also known as the MAC
address) and Vendor Details are the vendor details, decoded from the
hardware address. The output fields are separated by a single tab
character.
The responses are displayed in the order that they are received, which
is not always the same order as the requests were sent because some
hosts may respond faster than others.
The vendor decoding uses the files ieee-oui.txt, ieee-iab.txt and mac-
vendor.txt which are supplied with arp-scan. The ieee-oui.txt and
ieee-iab.txt files are generated from the OUI and IAB data on the IEEE
website at http://standards.ieee.org/regauth/oui/ieee-oui.txt and
http://standards.ieee.org/regauth/oui/iab.txt. The Perl scripts get-
oui and get-iab, which are included in the arp-scan package, can be
used to update these files with the latest data from the IEEE website.
The mac-vendor.txt file contains other MAC to Vendor mappings that are
not covered by the IEEE OUI and IAB files.
Almost all hosts that support IP will respond to arp-scan if they
receive an ARP packet with the target protocol address (ar$tpa) set to
their IP address. This includes firewalls and other hosts with IP
filtering that drop all IP traffic from the testing system. For this
reason, arp-scan is a useful tool to quickly determine all the active
IP hosts on a given Ethernet network segment.
OPTIONS
--help or -h
Display this usage message and exit.
--file=<fn> or -f <fn>
Read hostnames or addresses from the specified file instead of
from the command line. One name or IP address per line. Use "-"
for standard input.
--localnet or -l
Generate addresses from network interface configuration Use the
network interface IP address and network mask to generate the
list of target host addresses. The list will include the
network and broadcast addresses, so an interface address of
10.0.0.1 with netmask 255.255.255.0 would generate 256 target
hosts from 10.0.0.0 to 10.0.0.255 inclusive. If you use this
option, you cannot specify the --file option or specify any
target hosts on the command line. The interface specifications
are taken from the interface that arp-scan will use, which can
be changed with the --interface option.
--retry=<n> or -r <n>
Set total number of attempts per host to <n>, default=3.
--timeout=<n> or -t <n>
Set initial per host timeout to <n> ms, default=500. This
timeout is for the first packet sent to each host. subsequent
timeouts are multiplied by the backoff factor which is set with
--backoff.
--interval=<n> or -i <n>
Set minimum packet interval to <n> ms. This controls the
outgoing bandwidth usage by limiting the rate at which packets
can be sent. The packet interval will be no smaller than this
number. If you want to use up to a given bandwidth, then it is
easier to use the --bandwidth option instead. The interval
specified is in milliseconds by default, or in microseconds if
"u" is appended to the value.
--bandwidth=<n> or -B <n>
Set desired outbound bandwidth to <n>, default=256000. The
value is in bits per second by default. If you append "K" to
the value, then the units are kilobits per sec; and if you
append "M" to the value, the units are megabits per second. The
"K" and "M" suffixes represent the decimal, not binary,
multiples. So 64K is 64000, not 65536. You cannot specify both
--interval and --bandwidth because they are just different ways
to change the same parameter.
--backoff=<b> or -b <b>
Set timeout backoff factor to <b>, default=1.50. The per-host
timeout is multiplied by this factor after each timeout. So, if
the number of retrys is 3, the initial per-host timeout is 500ms
and the backoff factor is 1.5, then the first timeout will be
500ms, the second 750ms and the third 1125ms.
--verbose or -v
Display verbose progress messages. Use more than once for
greater effect: 1 - Show when hosts are removed from the list
and other useful information; 2 - Show each packet sent and
received; 3 - Display the host list before scanning starts.
--version or -V
Display program version and exit.
--random or -R
Randomise the host list. This option randomises the order of
the hosts in the host list, so the ARP packets are sent to the
hosts in a random order. It uses the Knuth shuffle algorithm.
--numeric or -N
IP addresses only, no hostnames. With this option, all hosts
must be specified as IP addresses. Hostnames are not permitted.
--snap=<s> or -n <s>
Set the pcap snap length to <s>. Default=64. This specifies the
frame capture length. This length includes the data-link
header. The default is normally sufficient.
--interface=<i> or -I <i>
Use network interface <i>. If this option is not specified, the
default is the value of the RMIF environment variable. If RMIF
is not defined, then arp-scan will search the system interface
list for the lowest numbered, configured up interface (excluding
loopback). The interface specified must support ARP.
--quiet or -q
Only display minimal output. If this option is specified, then
only the minimum information is displayed. With this option,
the OUI file is not used.
--ignoredups or -g
Don’t display duplicate packets. By default, duplicate packets
are displayed and are flagged with "(DUP: n)".
--ouifile=<o> or -O <o>
Use OUI file <o>, default=/usr/local/share/arp-scan/ieee-oui.txt
This file provides the Ethernet OUI to vendor string mapping.
--iabfile=<i> or -F <i>
Use IAB file <i>, default=/usr/local/share/arp-scan/ieee-iab.txt
This file provides the IEEE Ethernet IAB to vendor string
mapping.
--macfile=<m> or -m <m>
Use MAC/Vendor file <m>, default=/usr/local/share/arp-scan/mac-
vendor.txt This file provides the custom Ethernet MAC to vendor
string mapping.
--srcaddr=<m> or -S <m>
Set the source Ethernet MAC address to <m>. This sets the
48-bit hardware address in the Ethernet frame header for
outgoing ARP packets. It does not change the hardware address
in the ARP packet, see --arpsha for details on how to change
that address. The default is the Ethernet address of the
outgoing interface.
--destaddr=<m> or -T <m>
Send the packets to Ethernet MAC address <m> This sets the
48-bit destination address in the Ethernet frame header. The
default is the broadcast address ff:ff:ff:ff:ff:ff. Most
operating systems will also respond if the ARP request is sent
to their MAC address, or to a multicast address that they are
listening on. The address can be specified either in the format
01:23:45:67:89:ab, or as 01-23-45-67-89-ab. The alphabetic hex
characters may be upper or lower case.
--arpsha=<m> or -u <m>
Use <m> as the ARP source Ethernet address This sets the 48-bit
ar$sha field in the ARP packet It does not change the hardware
address in the frame header, see --srcaddr for details on how to
change that address. The default is the Ethernet address of the
outgoing interface.
--arptha=<m> or -w <m>
Use <m> as the ARP target Ethernet address This sets the 48-bit
ar$tha field in the ARP packet The default is zero, because this
field is not used for ARP request packets.
--prototype=<p> or -y <p>
Set the Ethernet protocol type to <p>, default=0x0806. This
sets the 16-bit protocol type field in the Ethernet frame
header. Setting this to a non-default value will result in the
packet being ignored by the target, or send to the wrong
protocol stack. This option is probably not useful, and is only
present for completeness.
--arphrd=<o> or -H <o>
Use <o> for the ARP hardware type, default=1. This sets the
16-bit ar$hrd field in the ARP packet. The normal value is 1
(ARPHRD_ETHER). Most, but not all, operating systems will also
respond to 6 (ARPHRD_IEEE802). A few systems respond to any
value.
--arppro=<o> or -p <o>
Use <o> for the ARP protocol type, default=0x0800. This sets
the 16-bit ar$pro field in the ARP packet. Most operating
systems only respond to 0x0800 (IPv4) but some will respond to
other values as well.
--arphln=<l> or -a <l>
Set the hardware address length to <l>, default=6. This sets
the 8-bit ar$hln field in the ARP packet. It sets the claimed
length of the hardware address in the ARP packet. Setting it to
any value other than the default will make the packet non RFC
compliant. Some operating systems may still respond to it
though. Note that the actual lengths of the ar$sha and ar$tha
fields in the ARP packet are not changed by this option; it only
changes the ar$hln field.
--arppln=<l> or -P <l>
Set the protocol address length to <l>, default=4. This sets
the 8-bit ar$pln field in the ARP packet. It sets the claimed
length of the protocol address in the ARP packet. Setting it to
any value other than the default will make the packet non RFC
compliant. Some operating systems may still respond to it
though. Note that the actual lengths of the ar$spa and ar$tpa
fields in the ARP packet are not changed by this option; it only
changes the ar$pln field.
--arpop=<o> or -o <o>
Use <o> for the ARP operation, default=1. This sets the 16-bit
ar$op field in the ARP packet. Most operating systems will only
respond to the value 1 (ARPOP_REQUEST). However, some systems
will respond to other values as well.
--arpspa=<s> or -s <s>
Use <s> as the source IP address. The address should be
specified in dotted quad format; or the string "dest", which
sets the source address to be the same as the target host
address. This sets the 32-bit ar$spa field in the ARP packet.
Some operating systems check this, and will only respond if the
source address is within the network of the receiving interface.
Others don’t care, and will respond to any source address. By
default, the outgoing interface address is used.
--padding=<p> or -A <p>
Specify padding after packet data. Set the padding data to hex
value <p>. This data is appended to the end of the ARP packet,
after the data. Most, if not all, operating systems will ignore
any Padding. The default is no padding, although the Ethernet
driver on the sending system may pad the packet to the minimum
Ethernet frame length.
FILES
/usr/local/share/arp-scan/ieee-oui.txt
List of IEEE OUI (Organizationally Unique Identifier) to vendor
mappings.
/usr/local/share/arp-scan/ieee-iab.txt
List of IEEE IAB (Individual Address Block) to vendor mappings.
/usr/local/share/arp-scan/mac-vendor.txt
List of other Ethernet MAC to vendor mappings.
EXAMPLES
The example below shows arp-scan being used to scan the network
192.168.0.0/24 using the network interface eth0.
$ arp-scan --interface=eth0 192.168.0.0/24
Interface: eth0, datalink type: EN10MB (Ethernet)
Starting arp-scan 1.4 with 256 hosts (http://www.nta-monitor.com/tools/arp-scan/)
192.168.0.1 00:c0:9f:09:b8:db QUANTA COMPUTER, INC.
192.168.0.3 00:02:b3:bb:66:98 Intel Corporation
192.168.0.5 00:02:a5:90:c3:e6 Compaq Computer Corporation
192.168.0.6 00:c0:9f:0b:91:d1 QUANTA COMPUTER, INC.
192.168.0.12 00:02:b3:46:0d:4c Intel Corporation
192.168.0.13 00:02:a5:de:c2:17 Compaq Computer Corporation
192.168.0.87 00:0b:db:b2:fa:60 Dell ESG PCBA Test
192.168.0.90 00:02:b3:06:d7:9b Intel Corporation
192.168.0.105 00:13:72:09:ad:76 Dell Inc.
192.168.0.153 00:10:db:26:4d:52 Juniper Networks, Inc.
192.168.0.191 00:01:e6:57:8b:68 Hewlett-Packard Company
192.168.0.251 00:04:27:6a:5d:a1 Cisco Systems, Inc.
192.168.0.196 00:30:c1:5e:58:7d HEWLETT-PACKARD
13 packets received by filter, 0 packets dropped by kernel
Ending arp-scan: 256 hosts scanned in 3.386 seconds (75.61 hosts/sec). 13 responded
This next example shows arp-scan being used to scan the local network
after configuring the network interface with DHCP using pump.
# pump
# ifconfig eth0
eth0 Link encap:Ethernet HWaddr 00:D0:B7:0B:DD:C7
inet addr:10.0.84.178 Bcast:10.0.84.183 Mask:255.255.255.248
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:46335 errors:0 dropped:0 overruns:0 frame:0
TX packets:1542776 errors:0 dropped:0 overruns:0 carrier:0
collisions:1644 txqueuelen:1000
RX bytes:6184146 (5.8 MiB) TX bytes:348887835 (332.7 MiB)
# arp-scan --localnet
Interface: eth0, datalink type: EN10MB (Ethernet)
Starting arp-scan 1.4 with 8 hosts (http://www.nta-monitor.com/tools/arp-scan/)
10.0.84.179 00:02:b3:63:c7:57 Intel Corporation
10.0.84.177 00:d0:41:08:be:e8 AMIGO TECHNOLOGY CO., LTD.
10.0.84.180 00:02:b3:bd:82:9b Intel Corporation
10.0.84.181 00:02:b3:1f:73:da Intel Corporation
4 packets received by filter, 0 packets dropped by kernel
Ending arp-scan 1.4: 8 hosts scanned in 0.820 seconds (9.76 hosts/sec). 4 responded
AUTHOR
Roy Hills <Roy.Hills@nta-monitor.com>
SEE ALSO
get-oui(1)
get-iab(1)
arp-fingerprint(1)
RFC 826 - An Ethernet Address Resolution Protocol
http://www.nta-monitor.com/wiki/ The arp-scan wiki page.
http://www.nta-monitor.com/tools/arp-scan/ The arp-scan homepage.
March 30, 2007