xenial (1) arp-scan.1.gz

Provided by: arp-scan_1.8.1-2ubuntu1_amd64 bug

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                   │
       ├───────┬──────┬──────────┬─────────────────────────────────────┤
       │FieldBitsOptionNotes                               │
       ├───────┼──────┼──────────┼─────────────────────────────────────┤
       │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                   │
       ├───────────────┬──────┬─────────────┬──────────────────────────────┤
       │FieldBitsOptionNotes                        │
       ├───────────────┼──────┼─────────────┼──────────────────────────────┤
       │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.

                                                January 31, 2011                                     ARP-SCAN(1)