Tutorial First Script

Tutorial : Your first script (step by step)

Task:
Print the following details of each packet in a capture file.
- ID, Timestamp, Length, Type, Description

Before we show you the actual script; let us take a minute to understand the basics of using the Unsniff Scripting API.

Creating the Unsniff.Database object

The Unsniff Scripting API allows you to access the contents of a capture file using an object model. The object model consists of a root object named "Unsniff.Database". You must first create this root object and then navigate your way through all the other objects. To create the "Unsniff.Database" root object use the following code.

In Ruby:

using 'win32ole'
..
MyDB = WIN32OLE.new("Unsniff.Database")

In VBScript:

Set MyDB = CreateObject("Unsniff.Database")

Navigating your way through the object model

The complete object model is documented in the Unsniff Scripting Guide.You first task is to identify the properties and methods available in each object. Since we want to print out the details of each packet in the database - we will use the following methods.

First we use the Open method of the Unsniff.Database object to open our capture file. We will call the corresponding Close method at the end of our script.
From object Unsniff.Database we get the PacketIndex object, the PacketIndex object is a collection of packets in the capture file.
We can iterate through each packet using the For Each or For..Next syntax of Ruby/VBScript to get a handle to each Packet object.
We finally print out the ID, Timestamp, Type, and Description properties of each Packet object.

Armed with this information, let us see the script in action !

Ruby version

1. You need a capture file to test your script. If you do not have access to a capture file; use Unsniff to capture a few packets and save it a a file.

2. Type the following script into Notepad.

require 'win32ole'

USAGE = "myscript <capture-filename>"
endl = "\n"
tab = "\t"

#
# method prints all packet details
#
def printPacket(packet)
endl = "\n"
tab = "\t"
	$stdout << packet.ID << tab << packet.Timestamp << tab \
	<< packet.Length << tab << packet.Type << tab \
	<< packet.Description << endl
end


if ARGV.length != 1
	puts USAGE
	exit 1
end

InputFile = ARGV[0]
UnsniffDB = WIN32OLE.new("Unsniff.Database")
UnsniffDB.Open(InputFile)
Count = UnsniffDB.PacketCount
print("Number of Packets = #{Count}\n"

PacketStore = UnsniffDB['PacketIndex']
(0..Count-1).each{ |idx| printPacket(PacketStore.Item(idx)) }

UnsniffDB.Close()

3. Save the file as myscript.rb(note the extension)

4. Open a MS-DOS command prompt by Start->Accessories->MS-DOS prompt

5. Run the script using the command

C:\Test> myscript mycapture.usnf

VBScript version

1. You need a capture file to test your script. If you do not have access to a capture file; use Unsniff to capture a few packets and save it a a file.

2. Type the following script into Notepad.

' -----------------
' Declare variables
' -----------------
Dim ArgFile
Dim WshShell

' -----------------------
' Check usage & arguments
' -----------------------
if WScript.Arguments.Count <> 1 then
	WScript.Echo "Usage: myscript <filename>"
	WScript.Quit
end if
 
ArgFile = WScript.Arguments.Item(0)


Dim InputFile
Dim Unsniff
Dim Count
Dim Packet
Dim PacketStore

InputFile = ArgFile
Set UnsniffDB = CreateObject("Unsniff.Database")

UnsniffDB.Open(InputFile)
Wscript.Echo "Number of packets = " & UnsniffDB.PacketCount

Set PacketStore = UnsniffDB.PacketIndex

For Each Packet In PacketStore
	WScript.Echo Packet.ID & vbTAB & Packet.Timestamp & vbTab & _
	Packet.Length & vbTAB & Packet.Type & vbTAB & _
	Packet.Description 
Next



UnsniffDB.Close()

3. Save the file as myscript.vbs (note the extension)

4. Open a MS-DOS command prompt by Start->Accessories->MS-DOS prompt

5. Run the script using the command

C:\Test> cscript myscript.vbs mycapture.usnf