ARP-SCAN(1) General Commands Manual ARP-SCAN(1)
NAME
arp-scan - Send ARP requests to target hosts and display responses
SYNOPSIS
arp-scan [options] [hosts...]
Target hosts must be specified on the command line unless the --file or
--localnet option is used.
Targets can be IPv4 addresses or hostnames. You can also use CIDR
notation (10.0.0.0/24) (network and broadcast included), ranges
(10.0.0.1-10.0.0.10), and network:mask (10.0.0.0:255.255.255.0).
DESCRIPTION
arp-scan sends ARP request packets to the specified hosts and displays
any responses received. The network interface can be specified with the
--interface option. If no interface is specified, arp-scan will pick
the lowest numbered, configured up interface (excluding loopback).
arp-scan uses raw sockets, which requires privileges on some systems:
Linux with POSIX.1e capabilities support using libcap:
arp-scan is capabilities aware. It requires CAP_NET_RAW in the
permitted set and only enables that capability for the required
functions. use setcap cap_net_raw+p /path/to/arp-scan to add
CAP_NET_RAW to the permitted set of the arp-scan executable.
Capabilities support also makes SUID root much safer because
arp-scan will drop all capabilities except CAP_NET_RAW and will
not run with full root privileges.
BSD and macOS:
You need read/write access to /dev/bpf*
Any operating system:
Running as root or SUID root will work on any OS but other
methods are preferable where possible.
ARP only operates on the local network, and cannot be routed. Although
the ARP protocol uses IPv4 addresses, it is not an IP protocol and arp-
scan can be used on interfaces without an IPv4 address.
One ARP request is sent for each target. If a host does not respond,
the request will be re-sent once more. The number of retries can be
changed with the --retry option. Reducing the number of retries will
reduce the scanning time at the risk of missing some results due to
packet loss.
You can specify the bandwidth that arp-scan will use with the
--bandwidth option. The default is 256000 bits per second. Increasing
the bandwidth will reduce scanning time, but setting the bandwidth too
high may cause a high broadcast packet rate. Another way to specify
the packet rate is with the --interval option.
The time for a single-pass scan (i.e. with --retry=1) is:
time = n × i + t + o
Where n is the number of hosts, i is the interval (given with
--interval or calculated from --bandwidth), t is the timeout (specified
with --timeout) and o is the overhead time taken to load the target
list and read the MAC/Vendor mapping files. The overhead is normally
negligible (typically around 100ms) but can be reduced further by the
--quiet option. For small lists of hosts, the timeout value will
dominate, but for large lists the packet interval is the most important
value.
Any part of the ARP request may be modified through the use of the
--arpXXX options as shown in the table below:
┌────────────────────────────────────────────────────┐
│ ARP Request Packet Options │
┝━━━━━━━┯━━━━━━┯━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━┥
│Field │ Bits │ Option │ Default │
┝━━━━━━━┿━━━━━━┿━━━━━━━━━━┿━━━━━━━━━━━━━━━━━━━━━━━━━━┥
│ar$hrd │ 16 │ --arphrd │ 1 (ARPHRD_ETHER) │
│ar$pro │ 16 │ --arppro │ 0x0800 │
│ar$hln │ 8 │ --arphln │ 6 (ETH_ALEN) │
│ar$pln │ 8 │ --arppln │ 4 (IPv4) │
│ar$op │ 16 │ --arpop │ 1 (ARPOP_REQUEST) │
│ar$sha │ 48 │ --arpsha │ interface h/w address │
│ar$spa │ 32 │ --arpspa │ interface IPv4 address │
│ar$tha │ 48 │ --arptha │ 00:00:00:00:00:00 │
│ar$tpa │ 32 │ None │ target host IPv4 address │
└───────┴──────┴──────────┴──────────────────────────┘
The most common option is --arpspa, which sets the source IPv4 address
in the ARP request, allowing the ARP request to use a different source
address from the interface address. This allows the use of arp-scan on
interfaces with no IPv4 address. Note: Setting ar$spa to the target's
IP address causes some operating systems to report an address clash
when they receive an ARP request for their own address.
You can also change the values in the Ethernet frame header as shown
below:
┌────────────────────────────────────────────────────────┐
│ Ethernet Header Options │
┝━━━━━━━━━━━━━━━┯━━━━━━┯━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━┥
│Field │ Bits │ Option │ Default │
┝━━━━━━━━━━━━━━━┿━━━━━━┿━━━━━━━━━━━━━┿━━━━━━━━━━━━━━━━━━━┥
│Dest Address │ 48 │ --destaddr │ ff:ff:ff:ff:ff:ff │
│Source Address │ 48 │ --srcaddr │ interface address │
│Protocol Type │ 16 │ --prototype │ 0x0806 (ARP) │
└───────────────┴──────┴─────────────┴───────────────────┘
The --destaddr option which sets the destination Ethernet address is
the only one that is commonly used.
By default, ARP responses are displayed in the following format:
<IPv4 Address> <MAC Address> <Vendor Details>
Where IPv4 Address is the IP address of the responding target, MAC
Address is its link-layer address and Vendor Details are the vendor
details decoded from the hardware address. The output fields are
separated by a single tab character. You can change the output format
with the --format option.
The responses are displayed in the order they are received, which can
be different from the order the requests were sent because some hosts
may respond quicker than others.
The vendor decoding uses the files ieee-oui.txt and mac-vendor.txt.
ieee-oui.txt is generated from the IEEE MA-L (OUI), MA-M, MA-S (OUI36)
and IAB registries. mac-vendor.txt contains additional MAC to Vendor
mappings, and can be used to add custom mappings. get-oui can be used
to update ieee-oui.txt with the latest data from the IEEE registries.
All IPv4 hosts should respond to ARP request packets, including hosts
with packet filtering such as firewalls. This makes arp-scan a useful
tool to discover all active IPv4 hosts on the local network.
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> Character string.
<i> Decimal integer, or hex if preceeded by 0x e.g. 2048 or 0x800.
<f> Floating point decimal number.
<m> MAC address, e.g. 01:23:45:67:89:ab or 01-23-45-67-89-ab (case
insensitive)
<a> IPv4 address e.g. 10.0.0.1
<h> Hex encoded binary data. No leading 0x. (case insensitive).
<x> Something else - see option description.
General Options
--help or -h
Display this usage message and exit.
--verbose or -v
Display verbose progress messages. Can be used than once to
increase verbosity. Max=3.
--version or -V
Display program version and exit. Displays the version, license
details, libpcap version, and whether POSIX.1e capability
support is included.
--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).
Host Selection
--file=<s> or -f <s>
Read hostnames or addresses from the specified file. One name
or address pattern per line. Use "-" for stdin.
--localnet or -l
Generate addresses from interface configuration. Generates list
from interface address and netmask (network and broadcast
included). You cannot use the --file option or give targets on
the command line. Use --interface to specify the interface.
MAC/Vendor Mapping Files
--ouifile=<s> or -O <s>
Use IEEE registry vendor mapping file <s>. Default is ieee-
oui.txt in the current directory. If that is not found or
cannot be opened /usr/share/arp-scan/ieee-oui.txt is used.
--macfile=<s> or -m <s>
Use custom vendor mapping file <s>. Default is mac-vendor.txt
in the current directory. If that is not found or cannot be
opened /etc/arp-scan/mac-vendor.txt is used.
Output Format Control
--quiet or -q
Display minimal output for each responding host. Only the IP
address and MAC address are displayed. Reduces memory usage by
about 5MB because the vendor mapping files are not used. Only
the ${ip} and ${mac} fields are available for the --format
option if --quiet is specified.
--plain or -x
Supress header and footer text. Only display the responding
host details. Useful if the output will be parsed by a script.
--ignoredups or -g
Don't display duplicate packets. By default duplicate packets
are flagged with (DUP: n) where n is the number of times this
host has responded.
--rtt or -D
Calculate and display the packet round-trip time. The time is
displayed in milliseconds and fractional microseconds. Makes the
${rtt} field available for --format.
--format=<s> or -F <s>
Specify the output format string. The format is a string that
will be output for each responding host. Host details can be
included by inserting references to fields using the syntax
"${field[;width]}". Fields are displayed right- aligned unless
the width is negative in which case left alignment will be used.
The following case- insensitive field names are recognised:
IP Host IPv4 address in dotted quad format
Name Host name if --resolve option given
MAC Host MAC address xx:xx:xx:xx:xx:xx
HdrMAC Ethernet source addr if different
Vendor Vendor details string
Padding Padding after ARP packet in hex if nonzero
Framing Framing type if not Ethernet_II
VLAN 802.1Q VLAN ID if present
Proto ARP protocol if not 0x0800
DUP Packet number for duplicate packets (>1)
RTT Round trip time if --rtt option given
Only the ${ip} and ${mac} fields are available if the --quiet
option is specified.
Any characters that are not fields are output verbatim. "\"
introduces escapes:
\n newline
\r carriage return
\t tab
\ suppress special meaning for following character
You should enclose the --format argument in 'single quotes' to
protect special characters from the shell.
Example: --format='${ip}\t${mac}\t${vendor}'
Host List Randomisation
--random or -R
Randomise the target host list.
--randomseed=<i>
Seed the pseudo random number generator. Useful if you want a
reproducible --random order.
Output Timing and Retry
--retry=<i> or -r <i>
Set total number of attempts per host to <i>, default=2.
--backoff=<f> or -b <f>
Set backoff factor to <f>, default=1.50. Multiplies timeout by
<f> for each pass.
--timeout=<i> or -t <i>
Set initial per host timeout to <i> 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=<x> or -i <x>
Set minimum packet interval to <x>. This controls the outgoing
bandwidth usage by limiting the packet rate. If you want to use
up to a given bandwidth it is easier to use the --bandwidth
option instead. The interval is in milliseconds, or microseconds
if "u" is appended.
--bandwidth=<x> or -B <x>
Set outbound bandwidth to <x>, default=256000. The value is in
bits per second. Append K for kilobits or M for megabits
(decimal multiples). You cannot specify both --interval and
--bandwidth.
DNS Resolution
--numeric or -N
Targets must be IP addresses, not hostnames. Can reduce startup
time for large target lists.
--resolve or -d
Resolve responding addresses to hostnames. The default output
format will display the hostname instead of the IPv4 address.
This option makes the ${name} field available for the --format
option.
Output ARP Packet
--arpsha=<m> or -u <m>
Set the ARP source Ethernet address. Sets the 48-bit ar$sha
field but does not change the hardware address in the frame
header, see --srcaddr for how to change that address. Default is
the Ethernet address of the outgoing interface.
--arptha=<m> or -w <m>
Set the ARP target Ethernet address. Sets the 48-bit ar$tha
field. The default is zero, because this field is not used for
ARP request packets.
--arphrd=<i> or -H <i>
Set the ARP hardware type, default=1. Sets the 16-bit ar$hrd
field. The default is 1 (ARPHRD_ETHER). Many operating systems
also respond to 6 (ARPHRD_IEEE802).
--arppro=<i> or -p <i>
Set the ARP protocol type, default=0x0800. Sets the 16-bit
ar$pro field. Most operating systems only respond to 0x0800
(IPv4).
--arphln=<i> or -a <i>
Set the hardware address length, default=6. Sets the 8-bit
ar$hln field. The lengths of the ar$sha and ar$tha fields are
not changed by this option; it only changes the ar$hln field.
--arppln=<i> or -P <i>
Set the protocol address length, default=4. Sets the 8-bit
ar$pln field. The lengths of the ar$spa and ar$tpa fields are
not changed by this option; it only changes the ar$pln field.
--arpop=<i> or -o <i>
Specify the ARP operation, default=1. Sets the 16-bit ar$op
field. Most operating systems only respond to the value 1
(ARPOP_REQUEST).
--arpspa=<a> or -s <a>
Set the source IPv4 address. The address should be in dotted
quad format, or the string "dest" which sets the source address
to the target host address. The default is the outgoing
interface address. Sets the 32-bit ar$spa field. Some
operating systems only respond if the source address is within
the network of the receiving interface. Setting ar$spa to the
destination IP address can cause some operating systems to
report an address clash.
Output Ethernet Header
--srcaddr=<m> or -S <m>
Set the source Ethernet MAC address. Default is the interface
MAC address. This sets the address in the Ethernet header. It
does not change the address in the ARP packet: use --arpsha to
change that address.
--destaddr=<m> or -T <m>
Set the destination MAC address. Sets the destination address
in the Ethernet header. Default is ff:ff:ff:ff:ff:ff (broadcast)
Hosts also respond if the request is sent to their unicast
address, or to a multicast address they are listening on.
--prototype=<i> or -y <i>
Sets the Ethernet protocol type, default=0x0806. This sets the
protocol type field in the Ethernet header.
--llc or -L
Use RFC 1042 LLC/SNAP encapsulation for 802.2 networks. arp-
scan will decode and display ARP responses in both Ethernet-II
and IEEE 802.2 formats irrespective of this option.
--vlan=<i> or -Q <i>
Use 802.1Q tagging with VLAN id <i>. The id should be in the
range 0 to 4095. arp-scan will decode and display ARP responses
in 802.1Q format irrespective of this option.
Misc Options
--limit=<i> or -M <i>
Exit after the specified number of hosts have responded. arp-
scan will exit with status 1 if the number of responding hosts
is less than the limit. Can be used in scripts to check if fewer
hosts respond without having to parse the output.
--pcapsavefile=<s> or -W <s>
Write received packets to pcap savefile <s>. ARP responses will
be written to the specified file as well as being decoded and
displayed.
--snap=<i> or -n <i>
Set the pcap snap length to <i>. Default=64. Specifies the
frame capture length, including the Ethernet header. The default
is normally sufficient.
--retry-send=<i> or -Y <i>
Set number of send attempts, default=20.
--retry-send-interval=<i> or -E <i>
Set interval between send attempts. Interval is in milliseconds
or microseconds if "u" is appended. default=5.
--padding=<h> or -A <h>
Specify padding after packet data. Set padding after the ARP
request to hex value <h>.
EXIT STATUS
arp-scan will exit with 0 on successful completion or >0 if an error
was encountered.
If the --limit option is specified, arp-scan will also exit with a non-
zero exit code if the number of responding hosts is less than the
specified limit.
FILES
/usr/share/arp-scan/ieee-oui.txt
List of IEEE OUI (Organisationally Unique Identifier) to vendor
mappings.
/etc/arp-scan/mac-vendor.txt
List of other Ethernet MAC to vendor mappings, including local
additions.
EXAMPLES
Simple Scan
Scan the default network using the interface IPv4 configuration to
generate the list of hosts to scan.
$ arp-scan --localnet
Interface: eth0, type: EN10MB, MAC: 50:65:f3:f0:6d:7c, IPv4: 10.0.0.106
Starting arp-scan 1.9.9 with 256 hosts (https://github.com/royhills/arp-scan)
10.0.0.14 a4:1f:72:7f:25:bb Dell Inc.
10.0.0.22 10:60:4b:73:43:de Hewlett Packard
10.0.0.74 00:0c:29:90:07:e9 VMware, Inc.
10.0.0.75 00:0c:29:66:9e:c2 VMware, Inc.
10.0.0.76 00:0c:29:d0:e1:ea VMware, Inc.
10.0.0.82 9c:b6:54:bb:f3:ec Hewlett Packard
10.0.0.84 00:21:9b:fd:b9:b3 Dell Inc.
10.0.0.85 00:02:b3:eb:5a:f8 Intel Corporation
10.0.0.91 00:9c:02:a5:7b:29 Hewlett Packard
10.0.0.92 d4:ae:52:d0:07:6f Dell Inc.
10.0.0.93 d4:ae:52:d0:04:9b Dell Inc.
10.0.0.96 9c:b6:54:bb:f5:35 Hewlett Packard
10.0.0.97 00:0c:29:0e:95:20 VMware, Inc.
10.0.0.104 50:65:f3:f0:70:a4 Hewlett Packard
15 packets received by filter, 0 packets dropped by kernel
Ending arp-scan 1.9.9: 256 hosts scanned in 1.532 seconds (167.10 hosts/sec). 14 responded
Output Formatting
Scan all hosts in 10.0.0.0/24 using interface eth0. Calculate round-
trip time and display in aligned columns using a custom format.
$ arp-scan -I eth0 --rtt --format='|${ip;-15}|${mac}|${rtt;8}|' 10.0.0.0/24
Interface: eth0, type: EN10MB, MAC: 50:65:f3:f0:6d:7c, IPv4: 10.0.0.106
Starting arp-scan 1.9.9 with 256 hosts (https://github.com/royhills/arp-scan)
|10.0.0.14 |a4:1f:72:7f:25:bb| 0.280|
|10.0.0.22 |10:60:4b:73:43:de| 0.293|
|10.0.0.74 |00:0c:29:90:07:e9| 0.380|
|10.0.0.75 |00:0c:29:66:9e:c2| 0.311|
|10.0.0.76 |00:0c:29:d0:e1:ea| 0.326|
|10.0.0.82 |9c:b6:54:bb:f3:ec| 0.216|
|10.0.0.84 |00:21:9b:fd:b9:b3| 0.244|
|10.0.0.85 |00:02:b3:eb:5a:f8| 0.244|
|10.0.0.91 |00:9c:02:a5:7b:29| 0.209|
|10.0.0.92 |d4:ae:52:d0:07:6f| 0.289|
|10.0.0.93 |d4:ae:52:d0:04:9b| 0.278|
|10.0.0.96 |9c:b6:54:bb:f5:35| 0.255|
|10.0.0.97 |00:0c:29:0e:95:20| 0.288|
|10.0.0.104 |50:65:f3:f0:70:a4| 0.263|
14 packets received by filter, 0 packets dropped by kernel
Ending arp-scan 1.9.9: 256 hosts scanned in 2.032 seconds (125.98 hosts/sec). 14 responded
CSV Output
--plain removes extraneous output.
$ arp-scan -I eth0 --plain --format='${ip},${mac},"${vendor}"' 10.0.0.0/24
10.0.0.14,a4:1f:72:7f:25:bb,"Dell Inc."
10.0.0.22,10:60:4b:73:43:de,"Hewlett Packard"
10.0.0.74,00:0c:29:90:07:e9,"VMware, Inc."
10.0.0.75,00:0c:29:66:9e:c2,"VMware, Inc."
10.0.0.76,00:0c:29:d0:e1:ea,"VMware, Inc."
10.0.0.82,9c:b6:54:bb:f3:ec,"Hewlett Packard"
10.0.0.84,00:21:9b:fd:b9:b3,"Dell Inc."
10.0.0.85,00:02:b3:eb:5a:f8,"Intel Corporation"
10.0.0.91,00:9c:02:a5:7b:29,"Hewlett Packard"
10.0.0.92,d4:ae:52:d0:07:6f,"Dell Inc."
10.0.0.93,d4:ae:52:d0:04:9b,"Dell Inc."
10.0.0.96,9c:b6:54:bb:f5:35,"Hewlett Packard"
10.0.0.97,00:0c:29:0e:95:20,"VMware, Inc."
10.0.0.104,50:65:f3:f0:70:a4,"Hewlett Packard"
SEE ALSO
get-oui(1)
arp-fingerprint(1)
http://www.royhills.co.uk/wiki/ The arp-scan wiki page.
https://github.com/royhills/arp-scan The arp-scan homepage.
January 14, 2023 ARP-SCAN(1)
arp scan \- Send ARP requests to target hosts and display responses