Network Self Discovery


Name Version Description Posted MD5 SHA1
fathom_0.97.zip 0.97 Complete Suite (Scan & Search) 2010.11.07 bbb1bcc250a55c99e8ab9bfd961c3ebf e0284f0d42b7a9d4737e5809aa74df122b9df202
fathom_0.96.zip 0.96 Core Fathom files (search only) 2010.07.11 a3b491f398d49e26ec4263e5f209d76d eb48cc778bffd83a0d394de4c06e9b7384fa5bcd
fathom_0.95.zip 0.95 Core Fathom files (search only) 2010.06.26 b907432a9dbe6e431829ee2f02b5fe8a a20874b65bb4c904afdfdcce3e2a024adbc4c19f


Fathom 0.97

  • Scanning: Package now includes scanning and maintenance shell scripts for generating data and keeping it up to date.
  • Scanning: Set --host-timeout to 10 minutes in scan-full.sh, scan-recon.sh and scan-genlogs.sh to limit impact of slow hosts.
  • Search: Added -m / --mac-address to search by MAC address or MAC vendor string. This will use results from nbstat.nse if the MAC data isn't present but nbstat data is.
  • Output: Cleanup of tabular (default) output from port and OS queries
  • General: Renamed scripts and files to use dash "-" instead of underscore for usability and consistency.
  • General: Cleanup of --metrics code to handle hashes more efficiently
  • Data Maint: util-cleanup.rb - Added IP address based selection of files to move to the backup directory
  • Data Maint: util-cleanup.rb - Added command to delete backup directory contents
  • BUG: Fixed a issue in Fathom where --script-data was not searching host script output.

Fathom 0.96

  • Cleanup: Code cleanup and efficiency changes - Thanks to Kris Katterjohn.
  • BUG: Fixed directory specification and options order issue - Thanks to David Fifield.
  • Metrics: Added counts for service product.
  • Output: Added -r / --report option to specify output file. All query results will be written to this file.
  • Input: Changed -l / --log to handle individual files as well as directories. Long option is now --log instead of --log-dir. Clarified error message when input XML file does not exist.
  • Output Filter: Added --ip-filter to permit filtering of output by host IP address, takes single host, IP/CIDR and IP/netmask notation. The metrics and all-host outputs respect this filter.
  • Output Filter: Added --start-date and --end-date to permit filtering of output to just scans that occurred before or after specified dates. The metrics and all-host outputs respect this filter.
  • Output Filter: Added --exclude-os to permit filtering of output by host OS. Usefulness depends on if Nmap was requested to perform OS identification and the accuracy of the result.
  • General: Improved grouping and format of -h output.
  • General: Improved error handling when an Interrupt is sent (Control-C).
  • Cleanup: Collapsed -a / --all method into special case of os_search.

Fathom 0.95

  • Changed format of -a / --all to include more data on OS family, type.
  • Updated fp-list -s / --service to allow optional service name parameter (http, ftp, etc).
  • Updated fp-list CSV output to include service name.
  • Flag -m has been changed to -e (--exclude-port).
  • Added --script-data to search for text in NSE script output or title. Honors port, service name and OS exclusion flags.



1. Ruby 1.9.1
  • Ubuntu:
    sudo apt-get install ruby1.9.1-full rubygems1.9.1 rdoc1.9.1
    sudo ln -s /usr/bin/ruby1.9.1 /usr/bin/ruby
  • Windows:
    Download Ruby from the Downloads section at Ruby-lang.org
    Install per instructions
2. Ruby Nmap::Parser by Kris Katterjohn (http://rubynmap.sourceforge.net/)

 Installation Options (pick one):
  • Via Ruby Gems:
    gem install nmap-parser
  • Via SourceForge download
    Download 0.3.5 or latest
    Unpack - Example: tar -xvf ruby-nmap-parser-0.3.5.tgz
    cd into the folder
    sudo ruby setup.rb all
  • Via SVN:
    svn co https://rubynmap.svn.sourceforge.net/svnroot/rubynmap/trunk
    cd trunk
    sudo ruby setup.rb all


  1. Download the appropriate file from the Downloads section.
  2. Unzip the files into the directory of your choice. Set execute rights on the .sh and .rb scripts as appropriate.
  3. Launch a command line interface (bash, cmd, etc) and change to the fathom directory.
  4. If you will be using Fathom to perform scanning as well as log queries then refer to the next section, Basic Setup.

Basic Setup

  1. A list of hosts and subnets is placed in ./lists/subnets.txt. If you are dealing with large numbers of hosts or subnets I strongly recommend using comments to keep notes on the entries. Comments prefixed by the # sign are permitted in this file. The comments can be on a line by themselves or after address entries.
  2. Edit ./lists/excludes-full.txt and ./lists/exclude-recon.txt and add any hosts or subnets that you want to PREVENT the scanning scripts from running nmap against. I strongly recommend using comments to document what addresses are being excluded and why. Be warned that if you have data for a host in the ./logs directory it will be deleted if that host is later added to an exclusion list and one of the Fathom scan scripts is run against it. This is due to the script calling Nmap, which initializes the files and then skips the host as instructed by the inclusion list.
  3. Next run util-genlist.sh to convert the subnets.txt file into two lists, ./lists/scanlist.txt and ./lists/scanlist-random.txt, that will be used by sweep-full.sh and sweep-recon.sh later.
  4. At this point you can run either sweep-full.sh or sweep-recon.sh. Both of these scripts will iterate over ./lists/scanlist-random.txt and scan each host. I recommend starting with sweep-recon.sh. This runs scan-recon.sh on each host which only performs portscans and OS identification on the targets. A more in-depth scan is performed by sweep-full.sh. It runs scan-full.sh which performs port scans, version detection, OS detection and runs all NSE scripts classified as 'default' or 'safe'. Both scan-full.sh and scan-recon.sh will hit every TCP port by default.

    Note: I recommend reviewing and editing the parameters used in scan-full.sh and scan-recon.sh. They are the parameters that I use and may be a bit aggressive, particularly if you are just starting to use the Fathom suite.

  5. At any time scan-full.sh and scan-recon.sh can be called against a single host to scan that host and create data files for it.

Data Maintenance

  • The shell script update-data.sh rescans the hosts in the ./logs directory with scan-full.sh starting with the oldest first. This can help keep data current. Keep in mind that a full scan will be performed regards of the type of scan that was originally used to generate the data.
  • The shell script fill-gaps.sh takes input from ./lists/gaps.txt and scans the hosts with scan-recon.sh ONLY if no files exist for the host in ./logs. This can be used to generate data for hosts that have not been previously scanned without taking a risk that existing data will be overwritten. Another benefit is that by skipping hosts it can fill in knowledge gaps without wasting time those that currently have data.
  • The Ruby script util-cleanup.rb, when used with the --archive parameter, will move files containing no active hosts to the ./logs/backup directory. The parameter --ip-filter will move files for host matching the IP specifications provided even if the files contain data on active hosts. The --purge parameter will delete everything in the ./logs/backup directory.