FadedCode
Network Self Discovery

Fathom Toolkit

The Fathom Toolkit is a suite of tools written with the goal of helping utilize Nmap to better understand your environment. The core tools are written in Ruby and leverage Kris Katterjohn's Nmap::Parser Ruby library for searching and manipulating Nmap's XML output.


News

Fathom 0.97 Released - 2010.11.07

Fathom 0.97 has been released. This version includes new scripts that round out the functionality of the suite. While previous releases primarily focused on querying existing XML formatted Nmap scan data, the new code handles the scan data's lifecycle including target management, recon, scanning, updating and purging.

The basic setup process and workflow overview can be found in the Basic Setup section of the Installation documenation.

New functionality:

Changes to prior functionality:


Tools

fathom.rb

Fathom searches a directory of Nmap XML output files and displays results based on the criteria specified on the command line. The data set can be searched based on port, service, operating system, NSE script name or NSE script output. Results can be excluded based on port number as well as service, product or OS string. The result is returned in bare (IP only), tab delimited and CSV formats.

Option Description
-p, --port <number> Search for specified port number
-s, --service <string> Search service, product and information fields for the specified string
-o, --operating-system <string> Search for specified OS string
-m, --mac-address <string> Search for specified MAC address or vendor string
-a, --all-hosts Return a list of all hosts in the logs
  
--ip-filter <ip_address> Filter results by IP Address
  Acceptable formats are as a single IP address (xxx.xxx.xxx.xxx)
  or in IP/CIDR notation    (xxx.xxx.xxx.xxx/xx)
  or in IP/netmask notation    (xxx.xxx.xxx.xxx/xxx.xxx.xxx.xxx)
  
--start-date <YYYY-MM-DD> Limit output to hosts scanned ON or AFTER the specified date, valid delimiters are . / and -
--end-date <YYYY-MM-DD> Limit output to hosts scanned ON or BEFORE the specified date, valid delimiters are . / and -
-e, --exclude-port <number> Exclude results matching the specified port
-x, --exclude-service <string> Exclude service where the service name or product matches the specified string
--exclude-os <string> Exclude results matching the specified OS (if the OS is identified by Nmap)
  
-l, --log <directory> Specify a particular Nmap XML file or the location of the directory containing Nmap XML logs
-r, --report <filename> Output results to specified file, as opposed to the terminal
-b, --bare Output IP Address only
-c, --csv Output results in CSV format
--metrics [number] Generate OS and port statistics, optionally limit result count
--script-data <string> Search NSE script result data (case insensitive)

fp-list.rb

fp-list searches a directory of Nmap XML output files and displays the fingerprints of unidentified services and OSes. The output can be limited to just OSes, just ports or just a specific port. Specific ports can be excluded in order to make the data easier to work with. The result is returned in bare (IP only), tab delimited and CSV formats.

Option Description
-p, --port <number> Search for specified port number
-s, --service <string> Return service fingerprints, optionally include service name to search for
-o, --operating-system <string> Return OS fingerprints
  
--ip-filter <ip_address> Filter results by IP Address
  Acceptable formats are as a single IP address (xxx.xxx.xxx.xxx)
  or in IP/CIDR notation    (xxx.xxx.xxx.xxx/xx)
  or in IP/netmask notation    (xxx.xxx.xxx.xxx/xxx.xxx.xxx.xxx)
  
--start-date <YYYY-MM-DD> Limit output to hosts scanned ON or AFTER the specified date, valid delimiters are . / and -
--end-date <YYYY-MM-DD> Limit output to hosts scanned ON or BEFORE the specified date, valid delimiters are . / and -
-e, --exclude-port <number> Exclude results matching the specified port
  
-l, --log <location> Specify a particular Nmap XML file or the location of the directory containing Nmap XML logs
-r, --report <filename> Output results to specified file, as opposed to the terminal
-b, --bare Output IP Address only
-c, --csv Output results in CSV format
--metrics [number] Generate OS and port statistics, optionally limit result count

Usage

Examples

  • Search for all hosts with port 25 open
    				./fathom.rb -p 25
    				
  • Search for all http services, exclude those on port 80, output in CSV to a file named http.csv
    				./fathom.rb -s http -e 80 -c -r http.csv
    				
  • Search for all ftp services, excluding printers, scanned on or after 2010-02-10 in the IP range 192.168.12.1/24
    				./fathom.rb -s ftp --exclude-os Printer --start-date 2010-02-10 --ip-filter 192.168.12.1/24
    				
  • Open every .xml file in the directory './xmlfiles/', search the services for those identified as Microsoft SQL Servers, output IP addresses only
    				./fathom.rb -l ./xmlfiles -s "Microsoft SQL" -b
    				
  • Display all service fingerprints, exclude those on port 80
    				./fp-list.rb -s -e 80
    				
  • Show the top 10 OSes, services and ports in the logs
    				./fathom.rb --metrics 10
    				
  • Show the count of OS fingerprints and a port breakdown of service fingerprints in the logs, limit to 10
    				./fp-list.rb --metrics 10