README: Setup Guide

Table of Contents

Overview 1

Requirements 2

Installation and Setup 2

Running The Sensor (Linux) 4

Running The Sensor (Win32) 5

Advanced Configurations 6

Linux Only 6

Linux and Win32 6

Changing Sensor Behavior 7

Type of Layer 4 Output: 7

Sensor Output 8

Layer 7 Parsers 8

The Remote Administration Client 9

Compiling 9

License and Acknowledgments 10

Contact 10

Overview

DNA is an open, flexible and extensible deep network analyzer (software server) and architecture for gathering and analyzing network packets, network sessions and applications protocols, passively off enterprise class networks. DNA is designed to be used for Internet Security, Intrusion detection, Network Management, Protocol and Network Analysis, Information Gathering, Network Monitoring applications

DNA runs as a distributed application under a Java Virtual Machine (JVM) environment and is portable across many OS environments, including: Network appliances, Switches and Routers.

Features

OS/Environment:

Collection:

Layer 7 Protocol Parsers:

Requirements

Optional Software



Installation and Setup

Installation

Download and follow the instructions appropriate to your environment:

Windows


  1. Dow load the "DNASetup.exe" file

  2. Execute the file (this can be done automatically by IE or by double-clicking on it) an MS-Dos window appears and shows the available Java Virtual Machines found on your system, if any.

  3. Choose the first one if proposed, or enter the path to your Java VM if asked.

  4. The installer starts and guides you through the rest of the installation process


Unix/Linux


  1. Download the "DNASetup.sh" file

  2. Open a shell console

  3. Cd to where you put the downloaded file

  4. Execute the file:

    	$ sh DNASetup.sh

  5. * the installer starts and guides you through the rest of the installation process

All platforms running Java 1.3 minimum

  1. Download the "DNASetup.jar" file

  2. Execute the jar: double-click on it, or if it fails, open a console and type

    java -jar DNASetup.jar

  3. The installer starts and guides you through the rest of the installation process

Deinstall

  1. Launch the uninstall script in the dnasystem’s install directory or on Windows, go to the "Software Install/Uninstall" panel and choose "DNASetup":


	$ sh uninstall_DNASetup.sh


Directory Map

./jars		jar files used in this release
./javadoc	dnasystem and openadaptor javadoc
./doc		Documentation
./lib		JNI libraries (e.g Libvservipq.so, libjavacap.so, javacap.dll)
./OS		OS specific patches and third party software
./scripts	Scripts for launching programs
./config	Configuration property files
./src		Java sources

Default Configuration

The system was installed to run a basic configuration of the analyzer. The ./scripts/sensor.bat (win32) and ./scripts/sensor.sh will start the analyzer using the default properties file ./config/DNASensor.props. The default properties will run the analyzer with the following configurations:


Note: The term sensor and analyzer are used interchangeably.


Running The Sensor (Linux)

This section will show how to run the sensor with the basic setup.
  1. Start from a shell window or console
  2. Set DNAHOME environment variable to the dnasystem install location
  3. Run the shell script $DNAHOME/scripts/sensor.sh with options.  The script will set the “-c config file to ./props/DNASensor.props. 
        > sh $DNAHOME/scripts/sensor.sh -h

        Help - use option:
                [-f file] to process from a tcpdump file
                [-d dev] to process a pcap device
                [-D] lists all interface devices capable of pcap cature
                [-q] to process from IPTables QUEUE
                [-h] print this help message
                [-c file] specify config file location, [default=$PWD/config.cfg]
  1. Run the sensor on “eth1” 
        > sh $DNAHOME/scripts/sensor.sh -d eth1
  1. Type Control-C to stop the sensor.  The server will complete it’s processing in a few seconds displaying the status.
        
        Server recieved shutdown command with time 0 seconds.
        Capture finished.  Recieved Packets: 4   Packets Dropped: 0
  1. The output will be placed in the users current directory in the file SensorData.out
  2. Any error will be placed in the log file sensor.log in the current directory.
Note: if you are running SELINUX or received the following error:
“Exception in thread "main" java.lang.UnsatisfiedLinkError: /tmp/dnasystem/lib/libjavacap.so: /tmp/dnasystem/lib/libjavacap.so: cannot restore segment prot after reloc: Permission denied
Issue the following command as root $chcon -t texrel_shlib_t lib/*

Running The Sensor (Win32)

This section will show how to run the sensor with the basic setup.
  1. Install WinPcap located in the install directory OS\win32\winpcap_3_1.exe
  2. Start from a dos command window (Start->run-> cmd)
  3. Set DNAHOME environment variable to the dnasystem install location
set DNAHOME=<dir>
  1. Run the batch file %DNAHOME%\scripts\sensor.bat with options.  The script will set the “-c config file to .\props\DNASensor.props. 
        > $DNAHOME/scripts/sensor.sh -h

        Help - use option:
                [-f file] to process from a tcpdump file
                [-d dev] to process a pcap device
                [-D] lists all interface devices capable of pcap cature
                [-q] to process from IPTables QUEUE
                [-h] print this help message
                [-c file] specify config file location, [default=$PWD/config.cfg]

  1. List the interfaces for your windows machine, since windows network interfaces have are generally hidden from the user.

    C:\ $DNAHOME/scripts/sensor.bat -D

1) \Device\NPF_GenericDialupAdapter  Generic dialup adapter
2) \Device\NPF_{0584B40D-F833-43FA-9D60-DAF22F2C7AD2} (Microsoft's Packet Scheduler)
3) \Device\NPF_{625526D2-72A5-4CBD-8CDA-461239EF0F57}  Dell Wireless WLAN 1450 Dual Band WLAN Mini-PCI Card (Microsoft's Packet Scheduler)

  1. Run the sensor on the “WiFi” interface 



        > $DNAHOME/scripts/sensor.sh -d \Device\NPF_{625526D2-72A5-4CBD-8CDA-461239EF0F57}

  1. Type Control-C to stop the sensor. The server will complete it’s processing in a few seconds displaying the status.

        Server recieved shutdown command with time 0 seconds.
        Capture finished.  Recieved Packets: 4   Packets Dropped: 0

  1. The output will be placed in the users current directory in the file SensorData.out

  2. Any error will be placed in the log file sensor.log in the current directory.



Advanced Configurations

Linux Only

IPTABLES Setup:

  1. Ensure you have IPtables configured into your kernel see: /usr/src/<kernel version>/make menuconfig

  2. Apply promiscous mode patch (if needed for passive monitoring. inline NAT/Firewalls do not need this patch)

  3. and build a new kernel, diff files found in : ./os/linux/iptables-promisc-diffs-1.3.0-kern-2.6.tar

  4. Change your linux start scripts to ensure that the following modules load:

ip_queue, iptable_filte, ip_tables

  1. For passive monitoring: Ensure that you have set one of your interfaces to promiscous mode (I use eth1 on my machine)


            ifconfig eth1 promisc up

  1. For NAT/Firewall users: See netfilter/iptables documenation to forward all packets to ip_queue.

  2. For passive monitoring: run the script ./script/iptables_rules.sh (change the script if your interface is not eth1). Output should look like this:

#./iptables_script.sh

        Chain FORWARD (policy ACCEPT 0 packets, 0 bytes)
        pkts bytes target     prot opt in     out     source               destination
        
        Chain INPUT (policy ACCEPT 1277K packets, 1027M bytes)
         pkts bytes target     prot opt in     out     source               destination 

        Chain OUTPUT (policy ACCEPT 1295K packets, 393M bytes)
         pkts bytes target     prot opt in     out     source               destination

        Chain PROMISC (policy ACCEPT 0 packets, 0 bytes)
        pkts bytes target     prot opt in     out     source               destination
        3159K 1319M QUEUE      all  --  eth1   any     anywhere             anywhere

Linux and Win32

JNDI NAMING SERVER:
 
Java provides a number of options to support JNDI naming.  The DNASensor.props provide templates for the following jndi services:
The simplest JDNI SERVICE is to use the rmiregistry command, shown below.  Refer to your ldap or J2EE server for server documentation for setup.
  1. Ensure the application jars ./jars can be found in the CLASSPATH.  The ./scripts/dna_classpath.sh or ./scripts/dna_classpath.bat scripts will set the correct classpath.
  2. Run rmiregistry. Found in your JAVA_HOME/bin directory
  3. Set the folloing properties in ./config/DNASensor.props 
  
        Admin.LOCAL_ONLY = true
        Admin.JNDIClass=isc.util.ServerAdmin
        Admin.NAMING_ADMIN_NAME=sensor
        Admin.NAMING_CONTEXT_CLASS=Context
        Admin.NAMING_PROVIDER_URL=rmi://localhost:1099
        Admin.NAMING_INITIAL_CONTEXT_FACTORY=com.sun.jndi.rmi.registry.RegistryContextFactory
        Admin.NAMING_URL_PKG_PREFIXES=com.sun.jndi.ldap

Changing Sensor Behavior 

The sensor’s behavior is controlled by an external property file.  The property file specifies the property/value pair the sensors java classes recognize as options.  The default property file shipped with the release is ./config/DNASensor.props.  For a complete list, refer to the sensor’s javadoc.  The main options to be concerned with are:
  1. Type of Layer 4 processing and output
  2. Location of sensor output via openadaptor
  3. The installed layer 7 parsers 
  4. The configuration options for each layer 7 parser

Type of Layer 4 Output:

The packet processor and session processor components of the DNA architecture are responsible for parsing the raw packets and producing the various type of Layer 4 output.

The following files contain the Layer 4 object data definitions and sample output: 

The Summary Flow output is included as part of the Session processing. Decide which type of output is desired and turn on/off (true/false) the following properties. 

        OutputType.TCPFlow = false
        OutputType.UDPFlow = false
        OutputType.TCPSession = true
        OutputType.UDPSession = true

Sensor Output

The output adapter component of the DNA architecture, encompassing a powerful data dictionary and pluggable resource adapt ors, is responsible for transforming processed data objects to a portable format and transmitting them to external resource managers. The output adapter is implemented using the OpenAdaptor open source product.

The location, type and format of the sensor’s output are determined by the configuration of Open Adapter. The following preconfigured adapter output property files are supplied.

To change the output, edit the sensor’s property file, setting the #include line to the appropriate adaptor property file. (it will default to the current directory).


#include OAFileSink.props  


In addition, to other property files are supplied to retrieve sensor data from datasources. These property files are meant to be used directly with OpenAdaptor.   See the OpenAdaptor’s manual for description to use.

Layer 7 Parsers

The application protocol session parser and APP protocol parser toolkit components of the DNA architecture are responsible for processing and selecting and passing packets to the configured protocol parser components.

The protocol parsers are pluggable modules developed to process a specific protocol or handle a specific task.


The following Parser currently supplied with this release:


To install a parser into the sensor’s configuration property file:

  1. Add the parser java class to the AppLayerXXX.Parsers list, where XXX is the protocol. The following will load the HttpParser for TCP only.


        AppLayerTCP.Parsers=isc.sensor.parser.HttpParser
        AppLayerUDP.Parsers=

  1. Configure the parser properties (see the parser’s javadoc for detail on the options). The following will configure HTTP on ports 80,8008 and 8080, output HTTP Summary records and suppress HTTP detail records.

        
        ! HTTP Parser specifics 
        HttpParser.Ports=80,8008,8080
        HttpParser.Flags=24,16
        HttpParser.OutputSummary=true
        HttpParser.OutputDetail=false

The Remote Administration Client

The DNA_adminClient java client allows the sensor to be administered remotely. Current administration commands supported are: 


  1. Start from a shell window (or dos shell)
  2. Run the command  ./scripts/admin.sh -h  (.\scripts\admin.bat for dos)
        Help - use option:
                [-s time] stop server, time = seconds, time=-1 will force stop
                [-h] print this help message
                [-c file] specify config file location, [default=$CWD/config.cfg]
 [-l logging property] specify the logging property in java.lang.properties form (property=value)

  1. Choose the -s options to stop the sensor daemon

        ./scripts/admin.sh -s 0

  1. Choose the -l option to change a logging property (turn logging on/off, etc) SeeL log4j for details on logging.


        ./scripts/admin.sh -l log4j.category.isc.main=debug

Compiling

The system is currently in compiled form under ./jars directory. The source code requires Apache Ant (http://ant.apache.org/) to compile.


ant -projecthelp


will list all build targets in build.xml.



License and Acknowledgments

The dnasystem is Copyright 2005 by John A. Casey and licensed under GPL described in the files in the install directory.

./LICENSE

./NOTICE


The dnasystem acknowledges the following open source software contribution



Contact

Email to: jcasey5366_at_sourceforge_dot_net