Statup Scripts

Startup Scripting

Startup scripts are small programs written in VBScript or Ruby which are executed automatically when Unsniff Network Analyzer is launched. You can use startup scripts to automate network captures or for customizing Unsniff startup behavior.

If you have a requirement like below - you need to use Startup Scripts

I want to automatically start a new capture everytime I launch Unsniff
I want to import libpcap file(s) specified on the command line
I want to start capturing with a specified capture filter automatically
I want to start two simultaneous captures with different capture filters on startup
I want to start an offline capture
Any other complex startup requirements

Using startup scripts

1. Write the startup script in VBScript or Ruby (see examples below)
2. Save the script file
3. Specify the name of the script on the command line using script:<filename> notation

Usage:

usnfctr script:<script-file-name> [script-arguments]

usnfctr : Fixed Name of the main unsniff executable (the main EXE file)

script-file : The script file (.vbs or .rb extension required)

script-arguments : Any arguments to the script, accessible via the Application.Arguments object

Example:

c:\UnsniffInstallDir\Bin> usnfctr script:autoimport.vbs mypcapfile.pcap

The Application object

The key to using startup scripts is to understand the Application object. The application object exposes several methods and properties that you must access via VBScript or Ruby. The methods are summarized in the table below.

Method or Property	Parameters	Purpose
Arguments	-	Returns the command line argument specified to the script as a single string
New	-	Creates a new capture file
Open	String - Capture File Name	Opens the specified capture file name
Import	String - Libpcap File Name	Creates a new capture file and imports packets from the specified libpcap/tcpdump format file
SetCaptureFilter	String - Capture Filter Name	Selects the specified capture filter. The name of the capture filter must match a pre-existing capture filter in Unsniff.
SetDisplayFilter	String - Filter Name	Selects the specified display filter.
SelectAdaptor	String - Adaptor Name	Select the specified adaptor. If you do not call this method, the default adaptor is used for the next capture. The adaptor name must match the name seen in Tools->Customize->Capture Tab->Adaptors
Start	-	Start a new capture
StartOffline	-	Start a new offline capture, use this for very high speed networks

Example 1: Start a new capture on startup
We want to automatically create a new capture file and start capturing to that file upon startup.

Usage

c:\temp> usnfctr script:autostart.vbs

File autostart.vbs

Dim
App

Set App = Application

App.New

App.Start

Note: We first create a new capture document App.New followed by an App.Start

Example 2: Start a new capture on startup with a capture filter
A new capture with a specified capture filter. The capture filter was created previously in Unsniff via the capture filter wizard. The name of the filter is only "subnet 192.168.4"
Usage

c:\temp> usnfctr script:autostart2.vbs

File autostart2.vbs

Dim
App

Set App = Application

App.New

App.SetCaptureFilter "subnet 192.168.4"

App.Start

Example 3: Import a libpcap file specified on the command line
We will now look at a script that will import a libpcap file. The filename is specified on the command line so we can see how the Arguments property is used. The name of the libpcap file is "ethereal-capture-3.cap"

Usage

c:\temp> usnfctr script:import.vbs c:\captures\ethereal-capture-3.cap

File import.vbs

Dim
App

Set App = Application

Dim ImportFile 

ImportFile = App.Arguments

App.Import ImportFile

Example 4: Open two capture files
This script demonstrates how you can work with multiple files
Usage

c:\temp> usnfctr script:opentwo.vbs

File opentwo.vbs

Dim
App

Set App = Application

App.Open "c:\tcp-near-end.usnf" 

App.Open "c:\tcp-far-end.usnf"