Scripts that execute in the context of the user interface

User interface scripts allow you to add custom functionality to the Unsniff Network Analyzer application. You can attach custom scripts to menu items. Your scripts will be triggered when the user selects the corresponding menu item.

In addition to all the objects you have seen in Section 3. Scripting Object Model – you get access to the following objects.

  1. The currently active capture document.
  2. The current selection context for packets, PDUs, streams, user objects
  3. A powerful scripting console that allows you to output formatted text

Script integration points

You can attach custom scripts to the following menus in Unsniff.

Capture Menu Use this menu if your scripts work on the entire capture file independent of the user selection.
Packet sheet context menu You can add a menu item to the packet sheet context menu. This context menu is shown when the user right clicks on the packets sheet. Use this is your script needs to work on selected packets.
PDU sheet context menu Add a menu item to the PDU sheet context menu. Use this method if your script needs to work with selected PDUs.
Streams sheet context menu Add a menu item to the Streams sheet context menu. This works on entire streams. Use this method if your script needs to work with selected streams.
User Objects sheet Context menu Add a menu item to the User Objects sheet context menu. Use this method if you want to work with selected user object

Script Integration Points

How to integrate scripts into Unsniff

ou can integrate your scripts into Unsniff via Tools → User Scripts. Step-by-step example

Assume that you have written a custom RTP Analysis script. This script analyzes an entire RTP session of a selected RTP packet that is part of the session. In this case you may wish to activate this script from the packets sheet context menu. Here is a step-by-step.

  1. Open the User Scripts Manager via Tools Æ User Scripts This opens the “Manage User Scripts” dialog.
  2. Click on the “New” button on the top-right corner of the dialog. This button opens the “Script Details Dialog” which allows you to create a new menu item and attach your script to it
  3. The “Script Details” Dialog is shown below. Use this dialog to enter the details shown in the table
NameA short name for the script functionality
ContextSelect where you want to attach your scripts. Five menu options are provided, you need to select one from the drop down list
Menu Tag A menu tag identifies how your script will be merged with the existing menu. You can use a “\” (backslash) character to create nested menus. In the above example RTP\RTP Analysis is a nested menu. You are encouraged to use nested menus to group related scripts together.
DescriptionOptional description
Script file Click the browse button to select your script file. A script file must follow these rules.
- VBScript files must have an extension *.vbs - Ruby files must have an extension *.rb - Jscript files must have an extension *.js

-Click OK – then restart Unsniff for your changes to take effect. The figure below shows a custom RTP Analysis script attached to the Packets sheet context menu.

The CurrentDocument object

Your script will automatically have access to an object called “CurrentDocument”. This object provides you with access to the currently active capture file as well as the current selection context. Here is a list of properties and method of this object.

NameTypeAccessDescription
DatabaseNameStringReadName of the currently open capture file
ConsoleObject ReadCreates a new scripting console object. This can be used to output results of your script. See the next section for a list of properties and methods for the Console object.
PacketCountLongReadNumber of packets in the currently open capture file
PacketIndexCollectionReadA collection of Packet objects. This represents all the packets in the capture file.
SelectedPacketObjectReadThe selected packet if a single packet (or) The first selected packet if multiple packets are selected
SelectedPacketsCollectionReadAll selected packets (a collection of Packet objects)
PDUCountLongReadNumber of PDUs in the currently open capture file
PDUIndexCollectionReadA collection of PDU objects. This represents all the PDUs in the currently active capture file
SelectedPDUObjectReadThe selected PDU if single selection (or) The first selected PDU if multiple selection
SelectedPDUsCollectionReadAll selected PDUs (a collection of PDU objects)
StreamCountLongReadNumber of streams in the currently open capture file
StreamIndexCollectionReadA collection of Stream objects. This represents all streams in the currently active capture file.
SelectedStreamObject ReadThe selected stream
SelectedStreamsCollectionReadAll selected streams (a collection of Stream objects)
UserObjectsCountLongReadNumber of user objects in the currently open capture file
UserObjectsIndexCollection ReadA collection of UserObject objects. This represents all the user objects in the currently active capture file.
SelectedUserObject ReadThe selected user object (or) The first selected user object if multiple selection
SelectedUserObjectsCollectionReadAll selected user objects (a collection of UserObject objects)

Methods

This object does not define any methods

The Script Console

Unsniff provides a powerful console via the CurrentDocument.Console object. The script console provides rich formatting features that can be used to create great reports. The properties and methods of the Script console are shown below.

Properties

NameTypeAccessDescription
TextColorStringRead/WriteThe current text color. The format of the text color is #RRGGBB. The RGB components are specified in hex.
For example:
Con.TextColor = “#FF0000”
Will set the current text color to full red.
BoldBooleanRead/WriteThe current bold text style. This is a boolean value.
In VBScript:
Con.Bold = True
In Ruby:
Con.Bold = true
HiliteBooleanRead/WriteThe current hilite style. Hilited text appears in a yellow hilite background.
ItalicsBooleanRead/Write The current italic style.

Methods

NameParametersDescription
WriteStringWrite the string to the console using the current styles
WriteLineStringWrite the string to the console using the current styles. This method automatically appends the required CR+LF characters. New text will start on a separate line.
SetDefaultFormatNoneReset all styles. Set TextColor to black.
SetTitle StringSet the title of the script console window
ClearNoneClear the contents of the script console window

Example

A simple example will illustrate the use of the CurrentDocument and the Script Console. Task : Print a description of each selected packet (Packet.Description)

  1. Write the following VBScript script and save it to a file (eg: myprint.vbs)
    myexample.vbs
    >
    VBScript 
    ' --------------------------------- 
    ' Get access to the script console 
    ' --------------------------------- 
    Dim Con 
    Set Con = CurrentDocument.Console 
    Con.TextColor = “#55EE33” 
    Con.WriteLine “Packet Printer Demo” 
    Con.WriteLine “-------------------“ 
    Set SelPacketList = CurrentDocument.SelectedPackets 
    For Each Packet In SelPacketList 
       Con.WriteLine Packet.Description 
    Next
  2. Attach the script to the packet sheet context menu. See Section 4.1.1 to find out how you can integrate your script into Unsniff
  3. Open a capture file in Unsniff or capture some packets from the network. Then select a few packets from the packets sheet. Right click and select the menu item corresponding to your script.
  4. Now the Script Console window will show the desired analysis output.
unsniff/intrgscr.txt · Last modified: 2014/09/11 23:23 (external edit)
 
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 3.0 Unported
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki