README.rdoc

Path: README.rdoc
Last Update: Thu Oct 02 12:42:27 -0600 2008

Welcome to ANTFARM

ANTFARM is a passive network mapping application that utilizes output from existing network examination tools to populate its OSI-modeled database. This data can then be used to form a ‘picture’ of the network being analyzed. This documentation is consistent with version 0.4.0 of the ANTFARM software.

More About ANTFARM

ANTFARM is a data fusion tool that does not directly interact with the network. The analyst can use a variety of passive or active data gathering techniques, the outputs of which are loaded into ANTFARM and incorporated into the network map. Data gathering can be limited to completely passive techniques when minimizing the risk of disrupting the operational network is a concern.

Disclaimer

While the ANTFARM tool itself is completely passive (it does not have any built-in means of gathering data directly from devices or networks), network admin tools that users of ANTFARM may choose to gather data with may or may not be passive. The authors of ANTFARM hold no responsibility in how users decide to gather data they wish to feed into ANTFARM.

Getting Started

As of now, the ANTFARM application is a command-line tool written to be used in a Linux environment (hopefully someone will want to make a Windows verson… :). The following can be done to get up and running with ANTFARM.

Installation

ANTFARM is packaged as a Ruby Gem, so the easiest way to install it is to run ‘gem install ANTFARM’ from the command line.

The default database for ANTFARM is SQLite3, so at a minimum you will need libsqlite3-dev installed. The PostgreSQL database is also supported (good for concurrent access), which requires the development files for the PostgreSQL server to be installed, as well as the server and client software and the postgres Ruby Gem.

Initialization

ANTFARM can be ran purely from within the Gem environment, but users will not have the ability to (easily) save copies of the database and use custom input/output scripts. However, if the user executes

  antfarm db --initialize

from the command-line, a .antfarm directory will be created in the user‘s home directory. Within this directory there will exist a config, db, log, and scripts directory. The databases and log files created by ANTFARM will reside here, and any custom scripts written by the user can be placed here to be made available to the application.

Last, you need to create an actual database to store the data in.

  antfarm db --migrate

The above command will work out of the box if the SQLite3 database is used. If you intend to use the PostgreSQL database, you must first create a database in PostgreSQL. The name of the database should match the name of the environment you wish to use it in.

  su - postgres
  createuser <username> (you will only have to do this once)
  createdb antfarm (or whatever environment name you want)

Now you‘re ready to start parsing files and filling the database!

Description of Contents

Add stuff here…

Description of Defaults

Currently, the ANTFARM application is hard-coded to use an sqlite3 database. The name given for the ANTFARM environment (which defaults to ‘antfarm’) is the name used for the database file and the log file.

As of now, the application defaults to the antfarm environment and to a log level of warn. These can be changed on a per-execution basis by passing a -e and/or a -l option to the antfarm command. These can also be changed in the HOME_DIR/.antfarm/config/defaults.yml file so you do not have to specify it on the command line every time. This is probably also the safer way to go… if you forget one time to pass the -e argument when using the non-default environment you could corrupt some data!

You can also tell the ANTFARM application to use the PostgreSQL database for a particular environment by adding something similar to the following to your defaults.yml file:

 <env name>:
   adapter: postgresql

For example, the following will tell ANTFARM to use the PostgreSQL database for the default ‘antfarm’ environment:

 antfarm:
   adapter: postgresql

Example Usage

Scripts are used to input data into the ANTFARM database. Multiple scripts already exist in the tool for parsing configuration files, traffic sniffs, etc. To see the scripts that currently exist, type

  antfarm help

Every command within ANTFARM also has some help information associated with it, so typing something along the lines of

  antfarm help <command>

should be useful.

Below is a very simple example of a script to read in network segments. The script assumes it‘s parsing a file with one network defined per line.

  begin
    list = File.open(file)
  rescue Errno::ENOENT
    puts "The file '#{file}' does not exist"
    exit
  end

  list.each do |network|
    IpNetwork.create :address => network.strip
  end

The above code is acutally what‘s present in the load-network script. To run this script, you would type

  antfarm load-network <data_file>

Most built-in scripts have help text associated with them, so typing

  antfarm help <script_name>

will display some useful information.

Feel free to read the source code for the built-in scripts, which are located in the ANTFARM_ROOT/lib/scripts/ directory. These will most likely be good examples for learning how to create custom scripts. You may add custom scripts to HOME_DIR/.antfarm/scripts/ directory and they will be available in the ANTFARM application.

Database Management

Obviously, there will be some times when you might need to manually edit some of the data in the ANTFARM database. You are more than welcome to access the database you are using (which will be in HOME_DIR/.antfarm/db if you initialized your environment) with the sqlite3 application. However, for your convenience, a Rails application has been included that utilizes the ActiveScaffold plugin (www.activescaffold.com) to allow you to easily view and edit the database manually. Simply type the following command:

  antfarm rails

and browse to localhost:3000/ using your favorite internet browser.

Displaying Results

Currently, ANTFARM does not have any built-in ways of graphically viewing a network (good spot for volunteers! :). However, a Java application utilizing the open source Java Prefuse package (prefuse.sourceforge.net) has been created and included with ANTFARM. In order to use this application, the Java 6 Runtime Environment must be installed on your computer. A script has been provided to utilize this application. It can be ran by executing the following command:

  antfarm viz display-networks

This command will dump the data in the database to a temporary file (in the tmp directory in your user space) then provide this file to the viz application. Run it… it looks cool! :)

If you look at HOME_DIR/.antfarm/config/colors.xml, you‘ll see the default file this application uses to decide what colors to use for nodes and edges. Modify this file to get the colors you want.

Homepage

antfarm.rubyforge.org

RubyForge Project

rubyforge.org/projects/antfarm

GitHub Project

github.com/btrichardson/antfarm

All code development will take place from GitHub. The latest source code for each ANTFARM release will be mirrored at the RubyForge project SCM as well.

Legal Stuff

Copyright (2008) Sandia Corporation. Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains certain rights in this software.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

[Validate]