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 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.
Warning: Setting ar$spa to the destination IP address can disrupt some
operating systems, as they assume there is an IP address clash if they
receive an ARP request for their own address.
It is also possible to change the values in the Ethernet frame header that
precedes 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 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, and can be used to add
custom mappings.
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¶
Where an option takes a value, that value is specified as a letter in angle
brackets. The letter indicates the type of data that is expected:
- <s>
- A character string, e.g. --file=hostlist.txt.
- <i>
- An integer, which can be specified as a decimal number or as a hexadecimal
number if preceded with 0x, e.g. --arppro=2048 or --arpro=0x0800.
- <f>
- A floating point decimal number, e.g. --backoff=1.5.
- <m>
- An Ethernet MAC address, which 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 either upper or lower case. E.g. --arpsha=01:23:45:67:89:ab.
- <a>
- An IPv4 address, e.g. --arpspa=10.0.0.1
- <h>
- Binary data specified as a hexadecimal string, which should not include a
leading 0x. The alphabetic hex characters may be either upper or lower
case. E.g. --padding=aaaaaaaaaaaa
- <x>
- Something else. See the description of the option for details.
- --help or -h
- Display this usage message and exit.
- --file=<s> or -f <s>
- 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=<i> or -r <i>
- Set total number of attempts per host to <i>, default=2.
- --timeout=<i> or -t <i>
- Set initial per host timeout to <i> ms, default=100. 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=<x> or -i <x>
- Set minimum packet interval to <x>. 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=<x> or -B <x>
- Set desired outbound bandwidth to <x>, 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
underlying parameter.
- --backoff=<f> or -b <f>
- Set timeout backoff factor to <f>, default=1.50. The per-host
timeout is multiplied by this factor after each timeout. So, if the number
of retries 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 - Display the network address and mask used when the --localnet option
is specified, display any nonzero packet padding, display packets received
from unknown hosts, and show when each pass through the list
completes.
-
- 2 - Show each packet sent and received, when entries are removed from the
list, the pcap filter string, and counts of MAC/Vendor mapping
entries.
-
- 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. No DNS lookups
will be performed.
- --snap=<i> or -n <i>
- Set the pcap snap length to <i>. Default=64. This specifies the
frame capture length. This length includes the data-link header. The
default is normally sufficient.
- --interface=<s> or -I <s>
- Use network interface <s>. If this option is not specified, 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 files are not
used.
- --ignoredups or -g
- Don't display duplicate packets. By default, duplicate packets are
displayed and are flagged with "(DUP: n)".
- --ouifile=<s> or -O <s>
- Use OUI file <s>, default=/usr/local/share/arp-scan/ieee-oui.txt
This file provides the IEEE Ethernet OUI to vendor string mapping.
- --iabfile=<s> or -F <s>
- Use IAB file <s>, default=/usr/local/share/arp-scan/ieee-iab.txt
This file provides the IEEE Ethernet IAB to vendor string mapping.
- --macfile=<s> or -m <s>
- Use MAC/Vendor file <s>,
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.
- --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=<i> or -y <i>
- Set the Ethernet protocol type to <i>, 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 sent to the wrong protocol stack.
- --arphrd=<i> or -H <i>
- Use <i> 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=<i> or -p <i>
- Use <i> 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=<i> or -a <i>
- Set the hardware address length to <i>, 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=<i> or -P <i>
- Set the protocol address length to <i>, 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=<i> or -o <i>
- Use <i> 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=<a> or -s <a>
- Use <a> as the source IP address. The address should be specified in
dotted quad format; or the literal 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.
-
- WARNING: Setting ar$spa to the destination IP address can disrupt some
operating systems, as they assume there is an IP address clash if they
receive an ARP request for their own address.
- --padding=<h> or -A <h>
- Specify padding after packet data. Set the padding data to hex value
<h>. 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.
- --llc or -L
- Use RFC 1042 LLC framing with SNAP. This option causes the outgoing ARP
packets to use IEEE 802.2 framing with a SNAP header as described in RFC
1042. The default is to use Ethernet-II framing. arp-scan will decode and
display received ARP packets in either Ethernet-II or IEEE 802.2 formats
irrespective of this option.
- --vlan=<i> or -Q <i>
- Use 802.1Q tagging with VLAN id <i>. This option causes the outgoing
ARP packets to use 802.1Q VLAN tagging with a VLAN ID of <i>, which
should be in the range 0 to 4095 inclusive. arp-scan will always decode
and display received ARP packets in 802.1Q format irrespective of this
option.
- --pcapsavefile=<s> or -W <s>
- Write received packets to pcap savefile <s>. This option causes
received ARP responses to be written to the specified pcap savefile as
well as being decoded and displayed. This savefile can be analysed with
programs that understand the pcap file format, such as "tcpdump"
and "wireshark".
FILES¶
- /usr/local/share/arp-scan/ieee-oui.txt
- List of IEEE OUI (Organisationally 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.