arpsweep
SYNOPSIS
arpsweep [OPTIONS] -i INTERFACE IP[,MAC] [ IP[,MAC] ... ]
arpsweep [OPTIONS] [ IP[,MAC] ... ] < FILE
DESCRIPTION
arpsweep uses the Address Resolution Protocol to identify hosts alive
and missing on the local Ethernet. Additionally, it will report on IP
address conflicts, usually obvious when receiving multiple ARP replies
for a single IP address. (For the impatient, jump to EXAMPLES.)
OPTIONS
-i, --interface=INTERFACE
Specify the Ethernet interface on which to send/receive ARP
requests for this invocation. This should be the interface name
as reported by the ifconfig or ip utilities, e.g. eth0, eth1 or
eth2.7
-h, --help, --usage
Print out a useful short help screen.
-q, --quiet
Suppress as much output as possible. Fatal warnings will still
be issued to STDERR and the final report will be printed to STD-
OUT.
-v, --verbose[=LEVEL]
Verbosity can be controlled in a number of ways. By using
--verbose with no argument, the verbosity level is increased
including all "lower" verbosity levels. If you wish to specify
only information or warning information, specify --verbose=WARN.
Valid LEVELs in descending order of diagnostic information are:
DEBUG, INFO, WARN, and ERR. Only the first character of the
argument is required (e.g., --verbose=W, --verbose=w and --ver-
bose=WARN all specify the same level of verbosity). Default
verbosity level is ERR, so throwing more than three unqualified
verbosity flags will yield no more diagnostic output.
-c, --count=NUM
Send a total of NUM ARP requests to each target host. Specify
zero (0) to continue until bored.
-p, --pending=NUM
Allow no more than NUM ARP requests to be in flight on the net-
work at any moment.
-w, --wait=MILLISECONDS
Allow a minimum of MILLISECONDS before assuming the remote host
is not responding to an ARP request. The default is one quarter
of a second (250 milliseconds), a very long time on most Ether-
nets. If you have a long-haul, bridged or wireless network, you
may need to increase this value to allow for the longer round
-f, --format=ARPSWEEP_FORMAT_STRING
Override default output format with a custom format string. See
OUTPUT FORMATTING below. Unimplemented as yet. The option will
be silently ignored.
-B, --broadcast-only, --no-unicast
Send only broadcast Ethernet frames (see METHODOLOGY AND INTER-
NALS below). This option is useful for catching duplicate IPs
or poorly behaved layer 3 devices. The presence of this option
will override any user-specified MAC addresses.
-N, --no-header
Do not print the header line in the report (just the data).
-A, --alive
Only produce output report on IPs which have replied to our ARP
requests.
-M, --missing
Only produce output report on IPs which have failed to reply.
-W, --weird
Only produce output report on IPs with various ARP problems,
e.g. more than one responding MAC address; mismatched frame
header address and link layer address specified in ARP reply;
mangled ARP reply.
-V, --version
Output a short listing identifying version information.
TARGET SPECIFICATION
For arpsweep, a target is any valid IP address and an optional MAC
address. Targets will be read as (an arbitrary number of) arguments on
the command line. Targets can also be supplied on STDIN via a file or
pipe. The expected target format differs slightly.
Accepted IP address formats
There is only one common format used for IP addresses, the ubiquitous
decimal dotted quad syntax. arpsweep only understands this common syn-
tax.
x.x.x.x
Dotted quad (e.g. 192.168.1.42)
Accepted MAC address formats
Although the numbers are always in hexadecimal, MAC addresses are writ-
ten in several different common formats. MAC address formats under-
stood and accepted by arpsweep are:
xx:xx:xx:xx:xx:xx
Linux, BSD, Mac (e.g. 00:80:c8:fb:78:d8)
Valid command line target specifications
Valid examples listed below:
192.168.1.42
192.168.1.42,00:80:c8:fb:78:d8
192.168.1.42,00-80-c8-fb-78-d8
192.168.1.42,0080.c8fb.78d8
STDIN target specification
Any target specified to STDIN of arpsweep is comprised of at least a
valid IP address and optionally, whitespace followed by a valid MAC
address specification. Surrounding whitespace is ignored.
IPADDR[ MACADDR]
Valid target specifications for STDIN
When arpsweep reads target specifications from STDIN, it accepts one
target per line with whitespace separating a valid IP address from an
optional MAC address.
192.168.1.42
192.168.1.42 00:80:c8:fb:78:d8
192.168.1.42 00-80-c8-fb-78-d8
192.168.1.42 0080.c8fb.78d8
OUTPUT FORMATTING
Unimplemented.
METHODOLOGY AND INTERNALS
Overview
The arpsweep utility uses the libnet packet creation and the pcap net-
work capture libraries to transmit and receive multiple ARP replies.
Address processing (arguments/STDIN)
After option processing and validation, arpsweep parses any command
line arguments as targets (see TARGET SPECIFICATION). If no command
line arguments remain, then whitespace separated IP and optional MAC
address pairs are read from from each line of a non-tty STDIN. arp-
sweep allocates memory for each entry stores each IP and MAC (inserting
the Ethernet broadcast MAC if no MAC address was specified). If arp-
sweep encounters any error in parsing an IP or a MAC address, it will
remove the address from the list of targets. Address parsing errors
will be reported to the user (unless -q has been thrown). If after
reading to the end of STDIN arpsweep received no valid address specifi-
cations, it politely quits, providing a usage string and complaining of
no target IP addresses.
Initializing PCAP
Reporting
Reporting is provided in an ASCII tabular output format. The output
will include the IP address of the target host, the link layer address
(MAC), the number of ARP requests sent and received, the cumulative
delay and a calculation of the average delay. (Maybe more statistics
fields in the future.)
EXAMPLES
Find out if the single host 192.168.1.42 is alive on eth0:
arpsweep 192.168.1.42
See if 192.168.1.42 is alive at MAC 00:80:c8:fb:78:d8 on VLAN 7 on
device eth1:
arpsweep -i eth1.7 192.168.1.42,00:80:c8:fb:78:d8
Send 10 ARP requests in broadcast Ethernet frames to see if
192.168.1.42 is alive on interface eth1. Only report if host does not
respond:
echo 192.168.1.42 00:80:c8:fb:78:d8 | arpsweep -MBc 10 -i eth1
BUGS
Please report bugs to the author (see AUTHOR).
Since ARP is a stateless protocol, there's no way to determine if a
captured ARP reply is in response to the network stack or this ARP
scanning application. Take the timings with a grain of salt.
This program requires root privileges (FIXME: presumably CAP_NET_RAWIO
and CAP_NET_ADMIN?) to run.
TODO
It would be convenient for the user to be able to specify a 'wait' time
in something other than milliseconds.
REFERENCES
libnet, http://www.packetfactory.net/libnet/
The libnet packet creation library provides an abstracted interface to
raw packet and frame creation.
pcap, http://www.tcpdump.org/
The pcap library provides an abstracted
An Ethernet Address Resolution Protocol, http://www.ietf.org/rfc/rfc826.txt
RFC 826 defines the standard for ARP.
Network Sorcery, http://www.networksorcery.com/enp/protocol/arp.htm
The RFC cookbook made available by Network Sorcery provides a clear
PURPOSE.
arpsweep 0.45 April 2006 arpsweep(8)
Man(1) output converted with
man2html