arp-scan.1.dist

'\" te
.\" Copyright (C) Roy Hills
.\"
.\" 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 "May 11, 2023"
.\" Please adjust this date whenever revising the man page.
.SH NAME
arp-scan \- Send ARP requests to target hosts and display responses
.SH SYNOPSIS
.B arp-scan
.RI [ options ] " " [ hosts ...]
.PP
Target hosts must be specified on the command line unless the \fB--file\fP or
\fB--localnet\fP option is used.
.PP
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).
.SH DESCRIPTION
\fBarp-scan\fP sends ARP request packets to the specified hosts and displays
any responses received. The network interface can be specified with the
\fB--interface\fP option. If no interface is specified, \fBarp-scan\fP
will pick the lowest numbered, configured up interface (excluding loopback).
.PP
\fBarp-scan\fP uses raw sockets, which requires privileges on some systems:
.TP
Linux with POSIX.1e capabilities support using libcap:
\fBarp-scan\fP is capabilities aware. It requires \fICAP_NET_RAW\fP in the
permitted set and only enables that capability for the required functions.
use \fIsetcap cap_net_raw+p /path/to/arp-scan\fP to add CAP_NET_RAW to the
permitted set of the arp-scan executable.
Capabilities support also makes SUID root much safer because \fBarp-scan\fP
will drop all capabilities except CAP_NET_RAW and will not run with full root
privileges.
.TP
BSD and macOS:
You need read/write access to \fI/dev/bpf*\fP
.TP
Any operating system:
Running as root or SUID root will work on any OS but other methods are
preferable where possible.
.PP
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 \fBarp-scan\fP can be used on interfaces without an
IPv4 address.
.PP
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 \fB--retry\fP option. Reducing the number of
retries will reduce the scanning time at the risk of missing some
results due to packet loss.
.PP
You can specify the bandwidth that \fBarp-scan\fP will use
with the \fB--bandwidth\fP 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 \fB--interval\fP option.
.PP
The time for a single-pass scan (i.e. with \fB--retry\fP=1) is:
.PP
.EQ
time = n times i + t + o
.EN
.PP
Where \fIn\fP is the number of hosts, \fIi\fP is the interval
(given with \fB--interval\fP or calculated from
\fB--bandwidth\fP), \fIt\fP is the timeout (specified with
\fB--timeout\fP) and \fIo\fP 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
\fB--quiet\fP option.
For small lists of hosts, the timeout value will dominate, but for large lists
the packet interval is the most important value.
.PP
Any part of the ARP request may be modified through the use of the
\fB--arpXXX\fP options as shown in the table below:
.TS
box;
cB S S S
LB | LB | LB | LB
L | L | L | L.
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
.TE
.\" We need two paragraphs under the table to get the correct spacing.
.PP
.PP
The most common option is \fB--arpspa\fP,
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 \fBarp-scan\fP
on interfaces with no IPv4 address.
Note: Setting \fIar$spa\fP 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.
.PP
You can also change the values in the Ethernet frame header as shown below:
.TS
box;
cB S S S
LB | LB | LB | LB
L | L | L | L.
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)
.TE
.\" We need two paragraphs under the table to get the correct spacing.
.PP
.PP
The \fB--destaddr\fP option which sets the destination Ethernet address
is the only one that is commonly used.
.PP
By default, ARP responses are displayed in the following format:
.TS
;
L L L.
<IPv4 Address>	<MAC Address>	<Vendor Details>
.TE
.PP
Where \fIIPv4 Address\fP is the IP address of the responding target,
\fIMAC Address\fP is its link-layer address and \fIVendor Details\fP
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 \fB--format\fP option.
.PP
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.
.PP
The vendor decoding uses the files \fIieee-oui.txt\fP and \fImac-vendor.txt\fP.
\fIieee-oui.txt\fP is generated from the IEEE \fIMA-L\fP (OUI), \fIMA-M\fP,
\fIMA-S\fP (OUI36) and \fIIAB\fP registries.
\fImac-vendor.txt\fP contains additional MAC to Vendor mappings, and can be
used to add custom mappings. \fBget-oui\fP can be used to update
\fIieee-oui.txt\fP with the latest data from the IEEE registries.
.PP
All IPv4 hosts should respond to ARP request packets, including
hosts with packet filtering such as firewalls. This makes \fBarp-scan\fP
a useful tool to discover all active IPv4 hosts on the local network.
.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:
.IP \fB<s>\fP
Character string.
.IP \fB<i>\fP
Decimal integer, or hex if preceeded by 0x e.g. 2048 or 0x800.
.IP \fB<f>\fP
Floating point decimal number.
.IP \fB<m>\fP
MAC address, e.g. 01:23:45:67:89:ab or 01-23-45-67-89-ab (case insensitive)
.IP \fB<a>\fP
IPv4 address e.g. 10.0.0.1
.IP \fB<h>\fP
Hex encoded binary data. No leading 0x. (case insensitive).
.IP \fB<x>\fP
Something else - see option description.
.SS "General Options"
.TP
.BR --help " or " -h
Display this usage message and exit.
.TP
.BR --verbose " or " -v
Display verbose progress messages.
Can be used than once to increase verbosity. Max=3.
.TP
.BR --version " or " -V
Display program version and exit.
Displays the version, license details, libpcap version,
and whether POSIX.1e capability support is included.
.TP
\fB--interface\fP=\fI<s>\fP or \fB-I \fI<s>\fR
Use network interface \fI<s>\fP.
If this option is not specified, arp-scan will search
the system interface list for the lowest numbered,
configured up interface (excluding loopback).
.SS "Host Selection"
.TP
\fB--file\fP=\fI<s>\fP or \fB-f \fI<s>\fR
Read hostnames or addresses from the specified file.
One name or address pattern per line. Use "-" for stdin.
.TP
.BR --localnet " or " -l
Generate addresses from interface configuration.
Generates list from interface address and netmask
(network and broadcast included). You cannot use the
\fB--file\fP option or give targets on the command line.
Use \fB--interface\fP to specify the interface.
.SS "MAC/Vendor Mapping Files"
.TP
\fB--ouifile\fP=\fI<s>\fP or \fB-O \fI<s>\fR
Use IEEE registry vendor mapping file \fI<s>\fP.
Default is \fIieee-oui.txt\fP in the current directory.
If that is not found or cannot be opened \fI@PKGDATADIR@/ieee-oui.txt\fP is used.
.TP
\fB--macfile\fP=\fI<s>\fP or \fB-m \fI<s>\fR
Use custom vendor mapping file \fI<s>\fP.
Default is \fImac-vendor.txt\fP in the current directory.
If that is not found or cannot be opened \fI@PKGSYSCONFDIR@/mac-vendor.txt\fP is used.
.SS "Output Format Control"
.TP
.BR --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 \fI${ip}\fP and \fI${mac}\fP fields are available for the \fB--format\fP
option if \fB--quiet\fP is specified.
.TP
.BR --plain " or " -x
Supress header and footer text.  Only display the responding host details.
Useful if the output will be parsed by a script.
.TP
.BR --ignoredups " or " -g
Don't display duplicate packets.
By default duplicate packets are
flagged with \fI(DUP: n)\fP where \fIn\fP is the number of
times this host has responded.
.TP
.BR --rtt " or " -D
Calculate and display the packet round-trip time.
The time is displayed in milliseconds and fractional
microseconds. Makes the \fI${rtt}\fP field
available for \fB--format\fP.
.TP
\fB--format\fP=\fI<s>\fP or \fB-F \fI<s>\fR
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
"\fI${field[;width]}\fP". 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:
.sp
.TS
L L .
IP	Host IPv4 address in dotted quad format
Name	Host name if \fB--resolve\fP 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 \fB--rtt\fP option given
IPnum	Host IPv4 address as a 32-bit integer
.TE
.sp
Only the \fI${ip}\fP and \fI${mac}\fP fields are available if the
\fB--quiet\fP option is specified.
.sp
Any characters that are not fields are output
verbatim. "\\" introduces escapes:
.sp
.TS
L L .
\\n	newline
\\r	carriage return
\\t	tab
\\	suppress special meaning for following character
.TE
.sp
You should enclose the \fB--format\fP argument in 'single
quotes' to protect special characters from the shell.
.sp
Examples:
.sp
.TS
L .
--format='${ip}\\t${mac}\\t${vendor}'\n
--resolve --format='${ip}\\t${mac}\\t${name;20}\\t${vendor}'
.TE
.TP
.SS "Host List Randomisation"
.TP
.BR --random " or " -R
Randomise the target host list.
.TP
\fB--randomseed\fP=\fI<i>\fR
Seed the pseudo random number generator.
Useful if you want a reproducible \fB--random\fP order.
.SS "Output Timing and Retry"
.TP
\fB--retry\fP=\fI<i>\fP or \fB-r \fI<i>\fR
Set total number of attempts per host to \fI<i>\fP,
default=2.
.TP
\fB--backoff\fP=\fI<f>\fP or \fB-b \fI<f>\fR
Set backoff factor to \fI<f>\fP, default=1.50.
Multiplies timeout by \fI<f>\fP for each pass.
.TP
\fB--timeout\fP=\fI<i>\fP or \fB-t \fI<i>\fR
Set initial per host timeout to \fI<i>\fP 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 \fB--backoff\fR.
.TP
\fB--interval\fP=\fI<x>\fP or \fB-i \fI<x>\fR
Set minimum packet interval to \fI<x>\fP.
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.
.TP
\fB--bandwidth\fP=\fI<x>\fP or \fB-B \fI<x>\fR
Set outbound bandwidth to \fI<x>\fP, default=256000.
The value is in bits per second. Append \fIK\fP for
kilobits or \fIM\fP for megabits (decimal multiples). You
cannot specify both \fB--interval\fP and \fB--bandwidth\fP.
.SS "DNS Resolution"
.TP
.BR --numeric " or " -N
Targets must be IP addresses, not hostnames.
Can reduce startup time for large target lists.
.TP
.BR --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
\fI${name}\fP field available for the \fB--format\fP option.
.SS "Output ARP Packet"
.TP
\fB--arpsha\fP=\fI<m>\fP or \fB-u \fI<m>\fR
Set the ARP source Ethernet address.
Sets the 48-bit \fIar$sha\fP field
but does not change the hardware address in the frame
header, see \fB--srcaddr\fP for how to change
that address. Default is the Ethernet address of
the outgoing interface.
.TP
\fB--arptha\fP=\fI<m>\fP or \fB-w \fI<m>\fR
Set the ARP target Ethernet address.
Sets the 48-bit \fIar$tha\fP field.
The default is zero, because this field is not used
for ARP request packets.
.TP
\fB--arphrd\fP=\fI<i>\fP or \fB-H \fI<i>\fR
Set the ARP hardware type, default=\fI1\fP.
Sets the 16-bit \fIar$hrd\fP field.
The default is \fI1\fP (\fIARPHRD_ETHER\fP). Many
operating systems also respond to \fI6\fP
(\fIARPHRD_IEEE802\fP).
.TP
\fB--arppro\fP=\fI<i>\fP or \fB-p \fI<i>\fR
Set the ARP protocol type, default=\fI0x0800\fP.
Sets the 16-bit \fIar$pro\fP field.
Most operating systems only respond to \fI0x0800\fP (IPv4).
.TP
\fB--arphln\fP=\fI<i>\fP or \fB-a \fI<i>\fR
Set the hardware address length, default=\fI6\fP.
Sets the 8-bit \fIar$hln\fP field.
The lengths of the \fIar$sha\fP and \fIar$tha\fP
fields are not changed by this
option; it only changes the \fIar$hln\fP field.
.TP
\fB--arppln\fP=\fI<i>\fP or \fB-P \fI<i>\fR
Set the protocol address length, default=\fI4\fP.
Sets the 8-bit \fIar$pln\fP field.
The lengths of the \fIar$spa\fP and \fIar$tpa\fP
fields are not changed by this
option; it only changes the \fIar$pln\fP field.
.TP
\fB--arpop\fP=\fI<i>\fP or \fB-o \fI<i>\fR
Specify the ARP operation, default=\fI1\fP.
Sets the 16-bit \fIar$op\fP field.
Most operating systems only respond to the value 1
(ARPOP_REQUEST).
.TP
\fB--arpspa\fP=\fI<a>\fP or \fB-s \fI<a>\fR
Set the source IPv4 address.
The address should be in dotted quad format,
or the string "\fIdest\fP" which sets the source
address to the target host address.
The default is the outgoing interface address.
Sets the 32-bit \fIar$spa\fP field.
Some operating systems only respond if the source address
is within the network of the receiving interface.
Setting \fIar$spa\fP to the destination IP address
can cause some operating systems to report
an address clash.
.SS "Output Ethernet Header"
.TP
\fB--srcaddr\fP=\fI<m>\fP or \fB-S \fI<m>\fR
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 \fB--arpsha\fP to
change that address.
.TP
\fB--destaddr\fP=\fI<m>\fP or \fB-T \fI<m>\fR
Set the destination MAC address.
Sets the destination address in the Ethernet
header. Default is \fIff:ff:ff:ff:ff:ff\fP (broadcast)
Hosts also respond if the request is sent to their
unicast address, or to a multicast address they
are listening on.
.TP
\fB--prototype\fP=\fI<i>\fP or \fB-y \fI<i>\fR
Sets the Ethernet protocol type, default=\fI0x0806\fP.
This sets the protocol type field in the Ethernet
header.
.TP
.BR --llc " or " -L
Use RFC 1042 LLC/SNAP encapsulation for 802.2 networks.
\fBarp-scan\fP will decode and display ARP responses in both
Ethernet-II and IEEE 802.2 formats irrespective of
this option.
.TP
\fB--vlan\fP=\fI<i>\fP or \fB-Q \fI<i>\fR
Use 802.1Q tagging with VLAN id \fI<i>\fP.
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.
.SS "Misc Options"
.TP
\fB--limit\fP=\fI<i>\fP or \fB-M \fI<i>\fR
Exit after the specified number of hosts have responded.
\fBarp-scan\fP 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.
.TP
\fB--pcapsavefile\fP=\fI<s>\fP or \fB-W \fI<s>\fR
Write received packets to pcap savefile \fI<s>\fP.
ARP responses will be written to the specified file
as well as being decoded and displayed.
.TP
\fB--snap\fP=\fI<i>\fP or \fB-n \fI<i>\fR
Set the pcap snap length to \fI<i>\fP. Default=64.
Specifies the frame capture length, including the
Ethernet header. The default is normally sufficient.
.TP
\fB--retry-send\fP=\fI<i>\fP or \fB-Y \fI<i>\fR
Set number of send attempts, default=20.
.TP
\fB--retry-send-interval\fP=\fI<i>\fP or \fB-E \fI<i>\fR
Set interval between send attempts.
Interval is in milliseconds or microseconds if "u"
is appended. default=5.
.TP
\fB--padding\fP=\fI<h>\fP or \fB-A \fI<h>\fR
Specify padding after packet data.
Set padding after the ARP request to hex value <h>.
.SH "EXIT STATUS"
\fBarp-scan\fP will exit with 0 on successful completion or >0 if an error was encountered.
.PP
If the \fI--limit\fP option is specified, \fBarp-scan\fP will also exit with
a non-zero exit code if the number of responding hosts is less than the
specified limit.
.SH FILES
.TP
.I @PKGDATADIR@/ieee-oui.txt
List of IEEE OUI (Organisationally Unique Identifier) to vendor mappings.
.TP
.I @PKGSYSCONFDIR@/mac-vendor.txt
List of other Ethernet MAC to vendor mappings, including local additions.
.SH EXAMPLES
.SS "Simple Scan"
Scan the default network using the interface IPv4 configuration to generate
the list of hosts to scan.
.PP
.nf
$ 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
.fi
.SS "Output Formatting"
Scan all hosts in \fI10.0.0.0/24\fP using interface \fIeth0\fP. Calculate round-trip time and display in aligned columns using a custom format.
.PP
.nf
$ 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
.fi
.SS "CSV Output"
\fB--plain\fP removes extraneous output.
.PP
.nf
$ 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"
.fi
.SH "SEE ALSO"
.BR get-oui (1)
.PP
.BR arp-fingerprint (1)
.PP
.I https://github.com/royhills/arp-scan/wiki
The arp-scan wiki page.
.PP
.I https://github.com/royhills/arp-scan
The arp-scan homepage.