MAC-Scan

Scan hosts on a VLAN or network for vulnerabilities.

NAME

mac-scan – Scan hosts on a VLAN or network for vulnerabilities

SYNOPSIS

./mac-scan [-dhlv] [-a limit] [-b bridged ports file] [-e event notifications file] [<-k> private key file] [-n max number of hosts to scan] [-N network] [-p predominant agents file] [-r agent to poll] [-s nessus server] [-t host name] [-V VLAN] community_string

 DESCRIPTION

mac-scan uses SNMP via poll-switch, or ICMP via nmap to retrieve a list of active hosts on a VLAN or network, requests scans for the list of hosts via certificate authentication from a Nessus server (set with the -s switch) and upon receipt of those scan results installs the results into a SQL-query-able database (Security Scan History — see below).

PSC Note; due to access lists set on the PostgreSQL database, dirsdb, SNMP access lists on the layer-2/3 switches, and certificate authenication on Nessus servers kgband stasi, mac-scan can (currently) only be run from the user account scanner onsport and warden.

mac-scan can use poll-switch (which uses SNMP) to retrieve a list of hosts stored in the specific layer-2 switch’s Dynamic Cam Table for a specific VLAN by using the -V and -r switches. Nmap (set only to use ICMP) can be used to collect all active hosts on a network by using the -N and -p switches. If ICMP reconnaissance is used to gather active hosts, then mac-scan will not have port information for those hosts. Hence, if a predominant agents file was specificed with the -p switch and that file contains one or more predominant agents for the ICMP mapped network, then mac-scan will (for each learned host) SNMP poll (using poll-switch) each of thepredominant agents in order to ascertain which layer-2 device has knowledge of any learned host, and thus, retrieve the port information for that host. If SNMPpolling was used for reconnaissance, port information should already have been retrieved for each active host. Regardless which reconnaissance method was used, if a bridged-ports file was specified with the -b switch and the layer-2 device (agent) and port for any learned hosts matches an agent and port tuple bridged-port, thenew agent assigned to the bridged-port is then SNMP polled to request updated port information for that host. Note, this process is recursive if, e.g., a host’s default router is more than two layer-2 hops away.

Next, mac-scan then SQL queries the Host Security Scan database to compare its learned MAC and IP address tuples against all previous recorded MAC and IP address tuples saved in the database. If a MAC and IP address tuple is new (i.e., it has not be previously entered into the database), or the current time is equal to or greater than the MAC and IP address tuple’s next security scan date, mac-scanqueues the host (as a target) for the Nesssus daemon running on the Nessus server to be scanned in bath mode. Upon receipt of the Nessus scan results, mac-scaninstalls a new entry into the Host Security Scan database. Finally, if the MAC and IP address tuple was previously unknown (events passed-new-scan, failed-new-scanor omitted-new-scan), or the scan failed its last two scans (event failed-scan) for any reason, mac-scan will send e-mail to the e-mail address(es) specified in theEvent Notification File (set with the -e switch). Additional events that can trigger e-mail notification include; empty-scan and scan-error.

Additionally, mac-scan can be told to not scan a host by adding the exemption ALLfor that host’s MAC and IP address tuple (or simply that host’s MAC address) to theSecurity Scan Exemptions database (see below). Likewise, event notification can be surpressed for a normally failed scan (event failed-scan), by adding the nasl scan idvalue for each scan that failed to the Security Scan Exemptions database for that MAC and IP address tuple.

PSC Note; Since mac-scan is in the right place at the right time to audit the Life Cycle Database, that is exactly what will happen if the -l switch is set. That is, prior to scanning a host mac-scan will attempt to retrieve the MAC and IP address tuple from the LCDB to see if it matches what mac-scan just learned. If it fails, notification is sent to any e-mail addresses set for the event failed-audit.

mac-scan can be operated in one of two modes; first, called batch-mode, by specifying an Event Notification File (-e), Nessus Server (-s), either a Remote Agent (-r) and VLAN (-v) or Predominant Agents File (-p) and Network (-N) andcommunity string, mac-scan will scan all hosts learned from that VLAN or network, providing the criteria mentioned above are met, e.g., next scan date is less than or equal to the current time, not in exemptions database, etc. If mac-scan is run from cron, it is advantageous to use the -a limit option, which specifies a limit that is used by the rand command to skew the start time of the tool, e.g., a limit of 3600 will start mac-scan in 0-3599 seconds. The second, or instance-mode is accessed by specifying the -t target option, which then simply scans the host specificed bytarget, and installs the scan results into the database. In this mode, neither poll-switch or Nmap is called.

OPTIONS

 -a

Automatic mode. This option tells mac-scan that this is being run non-manually. Including a limit value will force mac-scan to skew its start time by rand(limit).

 -b

Bridged-port file. This option instructs mac-scan to use the file specified as a list of switch ports that are known to be bridged. The file should contain lines consisting ofagent_name agent_port bridged_agent. If mac-scan learns a MAC address from a VLAN that is on an agent_name agent_port listed in the file, then mac-scan will then poll bridged_agent to learn the new port on bridged_agent that the MAC address is on.

 -e

Event notifications file. This option instructs mac-scan to use the file specfied for a list of e-mail addresses per event. The file should contain lines consisting of event email1, email2, …. When an event occurs that matches an event in the file, any e-mail addresses will receive notification of that event.

 -h

Print help message.

 -k

SSH private-key file. This specifies the path to the private key used in SSH public key authentication with the Radius server. When scanning WPA wireless networks, the layer-2 port information will always be the same for each host, i.e., the access pointusually behaves as a layer-2 bridge. However, Radius keeps logs containing the description of the access point used for each host upon authentication. Thus, if a validSSH private key is specified with this option, mac-scan will attempt to grep the Radiusserver’s authlogs in-order to ascertain which access point the host being scanned last used.

 -n

Max scans. This option instructs mac-scan to only scan n number of hosts prior to terminating. By default, n is set to 10, but can be overridden with this option.

 -N

Scan network mode. This option instructs mac-scan to use Nmap to ICMP scan the network for hosts. Note, in-order for Nmap to return the MAC address of a host, it must run in promiscous mode (this requires the user running mac-scan to have the appropriate privledges, e.g., group permissions on /dev/bpf, sudo, etc.) and the host from where mac-scan is run must have a directly connected interface on that network (e.g., being on a trunked VLAN port). See -p.

 -p

Predominant agents file. This option instructs mac-scan to use the file specfied for a list of layer-2 SNMP agents for each network specified. The file should contain lines consisting of network agent1, agent2, …. When a host is found on a network matching one in the file, all the agents will be SNMP polled in order to find a layer-2 device that has knowledge of the host (i.e., the host is active in the layer-2 devices dynamic cam table), at which point port information for that host will be retrieved by mac-scan. Since poll-switch is called on each agent to determine the host’s port infromation,community_string must be set when using the -p switch. Moreover, this option additionally requires the use of -N.

 -r

Remote agent. This option instructs mac-scan to use the remote agent for SNMP polling of its dynamic cam table. This option requires the use of -V.

 -s

Nessus server. This option instructs mac-scan to use server as the host running the Nessus daemon.

PSC Note: By default, kgb.psc.edu will be used.

 -T

Nessus results file type. Request that Nessus generate its results of a specific type. Currently, the only two supported options are xml and text.

 -V

VLAN scanning mode. This option instructs mac-scan to request hosts within a layer-2 devices dynamic cam table over a specific VLAN. This option requires use of -r.

DATABASE FORMATS

The Security Scans History database record format is:

  MAC address, IP address, last scan date, next scan date, VLAN,    scan status, layer-2 switch, port on layer-2 device,    nessus results file

The Security Scans Exemptions database record format is:

  MAC address, IP address, nasl id

EXAMPLES

To (potentially) scan all hosts on the 160 VLAN on cepheus:

    ./mac-scan -r cepheus.psc.edu -V 160 COMMUNITY_STRING_PASSPHRASE

To scan all the hosts on 128.182.58.0/24 (using Nmap):

    ./mac-scan -N 128.182.58.0/24 -p ./predominant-agents.300sc \         COMMUNITY_STRING_PASSPHRASE

To scan the wireless VLAN from cron:

    ./mac-scan -a 300 -k ./ssh-radius.key -r andromeda.psc.edu -V 734 \         COMMUNITY_STRING_PASSPHRASE   To scan hosts on the 128.182.158.0/24 network, which are known to be on bridge-ports and to request "text" output:

    ./mac-scan -b ./bridged-ports.txt -N 128.182.158.0/24 \         -p ./predominant-agents.300sc -T text \         COMMUNITY_STRING_PASSPHRASE

To simply scan a specific host (on the third or fourth floor of 300SC):

    ./mac-scan -t foo.psc.edu -r cepheus.psc.edu \         COMMUNITY_STRING_PASSPHRASE

BUGS

Since poll-switch does not return IPv6 addresses, and the version of nessus that we are currently using does not scan IPv6 addresses, mac-scan could be hoodwinked into not scanning a host that has a valid IPv6 address, but no IPv4 address.

The -t option is currently not working.

The security zone, from the psc.nic file is not used.

For some reason poll-switch uses -v to specify a VLAN and -V for version, butmac-scan uses the exact opposite.

PSC Note: If a host (or MAC address) has an exemption ALL, it will not be audited in the LCDB.

Radius information should be moved to either command line switches or a config file.

Written by Andrew K. Adams akadams@psc.edu for the Pittsburgh Supercomputing Center.