Host Discovery

One of the first things you'll probably want to do when doing networking happing is simply figuring out the hosts that are available for you to scan further. Because an IP range can be quite large; and we may only be interested in a small portion of that anyway.

This part of the scanning process is simply host discovery; and Nmapr provides clean ways to describe this, whether you're a system administrator just sending ICMP probes ( like with ping ) or a penetration tester with a customized schema to evade firewalls and intrusion detection systems. With that said, your needs may very and Nmapr's goal is to support as many Nmap options as possible; and we'll cover them here.

Ping

You may be familiar with the ping command which is found on a variety of systems that can be used to verify that a host is alive on a network. Typically, hosts will reply to the ICMP packets sent by ping to the target host. However, in other cases, you may want to work with other probes to detect hosts on a network; and maybe you'll want to disable ping scanning entirely.

Nmap Default

Nmapr relies on Nmap's default for pretty much all cases. Nmap's defaults to when no host discovery options are specified to simply end an ICMP echo request; and on other ports -- such as 443 and 80 -- other requests are used. It's also important to note that Nmap's phases are to run host discovery and then to do port scans on the hosts that are discovered; and Nmapr follows suite with this default as well.

Discovery Examples

Let's go over some practical examples you could use and how they look with Nmapr.

Skip Host Discovery

We can treat everyone as though they're online and totally skipping the ping scan.

Nmapr.scan :cmd do
  ping false
  # or
  ping :disable
end

A common Nmapr idiom is to treat true and :enable as well as false and :disable as the same operation where it's nice to have in the DSL. They'll do the same thing, so there's nothing to worry about.

Only Perform Host Discovery

We can disable port scanning entirely and just perform host discovery.

Nmapr.scan :cmd do
  ping :only
end

Or, what's also possible when describing the host discovery phase, you can also use the host_discovery method which is completely interchangeable with the ping method. This means the previous example is the exact same as:

Nmapr.scan :cmd do
  host_discovery :only
end

Explicitly Use Defaults

As descibed in the nmap man page, you can choose explicity to use the defaults ( which will happen anyway ) if you set ping or host_discovery to true or :enable as with typical Nmapr fashion.

Nmapr.scan :cmd do
  ping true
  # or 
  host_discovery true
end

Disable ARP and/or IPv6 Neighbor Discovery

As you can read in the nmap man pages, Nmap normally performs an IPv4 ARP or a IPv6 Neighbor Discovery of locally connected hosts, even if other ping or host_discovery options such as false or :echo are used. To disable this behavior, use the arp method to :disable it.

Nmapr.scan :cmd do
  arp :disable
  # or 
  arp false
end

Enable ARP and/or IPv6 Neighbor Discovery

The opposite of not using ARP, is to use ARP / Neighbor Discovery!

Nmapr.scan :cmd do
  arp :enable
  # or
  arp true
end

UDP Ping

Another host discovery option is the UDP ping, which sends a UDP packet to the given ports. Essentially, it can be taken advantage of to aid in bypassing firewalls and other network filters that only screen TCP packets. Since there are plenty of other packet types, like UDP, we can try it!

Nmapr.scan :cmd do
   ping :udp, ports: :all
   # or something like
   ping :udp, ports: [ 1, 2, 3 ]
end

TCP SYN

This option sends an empty TCP packet with the SYN flag set. The default destination port is port 80 as specified in the man page. For this example, remmber that ping and host_discovery do the same thing! This option suggests to the remote system that you are attempting to establish a connection.

Nmapr.scan :cmd do
  host_discovery :tcp_syn
  # specify ports
  # note that ranges can be achieved easily with strings,
  # however, there should be no spaces! Comma separated.
  host_discovery :tcp_syn, ports: [ "22-25", 80, 113, 1050, 35000 ]
end

TCP ACK

The TCP ACK ping or host_discovery option is quite similar to the just-discussed TCP SYN host discovery option. The difference, as you could likely guess, is that the TCP ACK flag is set instead of the SYN flag. The :tcp_ack option specifies a default port of 80. It is common to send both :tcp_ackand :tcp_syn probes where needed depending on the firewall configurations your attempting to work with, or as the case may be, against.

Nmapr.scan :cmd do
  host_discovery :tcp_ack
end

SCTP INIT

The SCTP INIT option sends an SCTP packet containing a minimal INIT chunk with a a default destination port of 80. Though, like the previous mentioned :tcp_syn and :tcp_ack options, alternate ports can be specified. Similarly to the TCP SYN option, this option's INIT chunk suggests to the remote system that you are attempting to establish an association.

Nmapr.scan :cmd do
  ping :sctp_init, ports: [ 80, 113, 8080 ]
end

ICMP Echo

Echo requests are the the standard ICMP ping query when you run ping in the command-line. The ports are not specified for this option.

Nmapr.scan :cmd do
  ping :echo
end

ICMP Timestamp

Another type of ICMP request that can be made like Echo is the Timestamp request. The ports are not specified for this option.

Nmapr.scan :cmd do
  ping :timestamp
end

ICMP Address Mask

The last type of ICMP request that can be made is the the Address Mask request. Like the previous Timestamp option, this can be helpful when other ICMP types are being denied, but the others have been forgotten about. Like Echo, and Timestamp, ports are not specified for this option.

Nmapr.scan :cmd do
  ping :address_mask
end

IP Protocol

One of the newer Nmap host discovery options is the IP protocol ping, which sends IP packets with the specified protocol number set in their IP header. The protocol list takes the same format as do port lists in the previously discussed TCP, UDP and SCTP host discovery options. If no protocols are specified, the default is to send multiple IP packets for ICMP (protocol 1), IGMP (protocol 2), and IP-in-IP (protocol 4).

Nmapr.scan :cmd do
  ping :protocol
  # or
  ping :protocol, protocols: [ 1, 2, 4 ]
end

Disable DNS Resolution

If you don't want to spend any time doing DNS resolution for your targets, we can easily disable it.

Nmapr.scan :cmd do
  dns :disable
end

Enable DNS Resolution

If you do want to spend any time doing some DNS resolution for your targets, we can easily explicitly enable it.

Nmapr.scan :cmd do
  dns :enable
end

Use System DNS

By default, Nmap resolves target IP addresses by sending queries directly to the name servers configured on your host.

Nmapr.scan :cmd do
  dns :system
end

Use a Given DNS Server

If you'd like to use another DNS server, you can totally do that.

Nmapr.scan :cmd do
  dns :server, "8.8.8.8"
end

Use Multiple Given DNS Servers

If you'd like to use more than one other DNS server.

Nmapr.scan :cmd do
  dns :servers, ["8.8.8.8", "8.8.4.4"]
end

Just List Targets

The list scan argument is a degenerate form of host discovery that simply lists each host of the network(s) specified, without sending any packets to the target hosts.

Nmapr.scan :cmd do
  just_list
  # or 
  list_targets
  # or 
  list_scan
  # or
  list
end