'\" t
.\" Copyright (C) Roy Hills, NTA Monitor Ltd.
.\"
.\" Copying and distribution of this file, with or without modification,
.\" are permitted in any medium without royalty provided the copyright
.\" notice and this notice are preserved.
.\"
.TH ARP-SCAN 1 "August 13, 2016"
.\" Please adjust this date whenever revising the man page.
.SH NAME
arp-scan \- The ARP scanner
.SH SYNOPSIS
.B arp-scan
.RI [ options ] " " [ hosts ...]
.PP
Target hosts must be specified on the command line unless the
.B --file
option is given, in which case the targets are read from the specified file
instead, or the
.B --localnet
option is used, in which case the targets are generated from the network
interface IP address and netmask.
.PP
You will need to be root, or
.B arp-scan
must be SUID root, in order to run
.BR arp-scan ,
because the functions that it uses to read and write packets require root
privilege.
.PP
The target hosts can be specified as IP addresses or hostnames.  You can also
specify the target as
.B IPnetwork/bits
(e.g. 192.168.1.0/24) to specify all
hosts in the given network (network and broadcast addresses included),
.B IPstart-IPend
(e.g. 192.168.1.3-192.168.1.27) to specify all hosts in the
inclusive range, or
.B IPnetwork:NetMask
(e.g. 192.168.1.0:255.255.255.0) to specify all hosts in the given network
and mask.
.SH DESCRIPTION
.B 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
.B --interface
option. If this option is not present,
.B 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
.B --destaddr
option.
.PP
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
.B --file
option; or by specifying the
.B --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
.B --file
option, you can use either IP addresses or hostnames.  You can also use network
specifications
.BR IPnetwork/bits ,
.BR IPstart-IPend ,
or
.BR IPnetwork:NetMask .
.PP
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.
.PP
.B 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.
.PP
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
.B 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
.B arp-scan
can be used on an interface that is not configured for IP.
.PP
ARP is only used by IPv4 hosts. IPv6 uses NDP (neighbour discovery protocol)
instead, which is a different protocol and is not supported by
.BR arp-scan .
.PP
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
.B --retry
option.  Reducing the number of retries will reduce the scanning time at
the possible risk of missing some results due to packet loss.
.PP
You can specify the bandwidth that
.B arp-scan
will use for the outgoing ARP
packets with the
.B --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:
.IR "No buffer space available" .
Another way to specify the outgoing ARP packet rate is with the
.B --interval
option, which is an alternative way to modify the same underlying parameter.
.PP
The time taken to perform a single-pass scan (i.e. with
.BR --retry=1 )
is given by:
.PP
.nf
time = n*i + t + o
.fi
.PP
Where
.I n
is the number of hosts in the list,
.I i
is the time interval between packets (specified with
.BR --interval ,
or calculated from
.BR --bandwidth ),
.I t
is the timeout value (specified with
.BR --timeout )
and
.I 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.
.PP
With 65,536 hosts, the default bandwidth of 256,000 bits/second (which results in a packet
interval of 2ms), the default timeout of 500ms, and a single pass (
.BR --retry=1 ),
and assuming an overhead of 1 second, the scan would take
65536*0.002 + 0.5 + 1 = 132.57
seconds, or about 2 minutes 13 seconds.
.PP
Any part of the outgoing ARP packet may be modified through the use of the
various
.B --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
.BR arp-fingerprint (1)
for information about a script which uses these options to fingerprint the
target operating system.
.PP
The table below summarises the options that change the outgoing ARP
packet. In this table, the
.I Field
column gives the ARP packet field name from RFC 826,
.I Bits
specifies the number of bits in the field,
.I Option
shows the
.B arp-scan
option to modify this field, and
.I Notes 
gives the default value and any other notes.
.TS
box;
cB S S S
LB | LB | LB | LB
L | L | L | L.
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
.TE
.\" We need two paragraphs under the table to get the correct spacing.
.PP
.PP
The most commonly used outgoing ARP packet option is
.BR --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
.B 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.
.PP
.B Warning: Setting ar$spa to the destination IP address can disrupt some
.B operating systems, as they assume there is an IP address clash if they
.B receive an ARP request for their own address.
.PP
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.
.TS
box;
cB S S S
LB | LB | LB | LB
L | L | L | L.
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
.TE
.\" We need two paragraphs under the table to get the correct spacing.
.PP
.PP
The most commonly used outgoing Ethernet frame option is
.BR --destaddr ,
which sets the destination Ethernet address for the ARP packet.
.B --prototype
is not often used, because it will cause the packet to be interpreted
as a different Ethernet protocol.
.PP
Any ARP responses that are received are displayed in the following format:
.TS
;
L L L.
<IP Address>	<Hardware Address>	<Vendor Details>
.TE
.PP
Where
.B IP Address
is the IP address of the responding target,
.B Hardware Address
is its Ethernet hardware address (also known as the MAC address) and
.B Vendor Details
are the vendor details, decoded from the hardware address.  The output
fields are separated by a single tab character.
.PP
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.
.PP
The vendor decoding uses the files
.IR ieee-oui.txt ,
.I ieee-iab.txt 
and
.IR mac-vendor.txt ,
which are supplied with
.BR arp-scan .
The
.I ieee-oui.txt
and
.I ieee-iab.txt
files are generated from the OUI and IAB data on the IEEE website at
.I http://standards-oui.ieee.org/oui/oui.txt
and
.IR http://standards.ieee.org/regauth/oui/iab.txt .
The Perl scripts
.B get-oui
and
.BR get-iab ,
which are included in the
.B arp-scan
package, can be used to update these
files with the latest data from the IEEE website.
The
.I 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.
.PP
Almost all hosts that support IP will respond to
.B 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,
.B arp-scan
is a useful tool to quickly determine all the active IP hosts
on a given Ethernet network segment.
.SH 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:
.TP
.B <s>
A character string, e.g. --file=hostlist.txt.
.TP
.B <i>
An integer, which can be specified as a decimal number or as a hexadecimal
number if preceeded with 0x, e.g. --arppro=2048 or --arpro=0x0800.
.TP
.B <f>
A floating point decimal number, e.g. --backoff=1.5.
.TP
.B <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.
.TP
.B <a>
An IPv4 address, e.g. --arpspa=10.0.0.1
.TP
.B <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
.TP
.B <x>
Something else. See the description of the option for details.
.TP
.B --help or -h
Display this usage message and exit.
.TP
.B --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.
.TP
.B --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.