~~NOTOC~~
[[http://www.unleashnetworks.com/products/unsniff.html|{{:unsniff_logo_64.png |Unsniff  Logo}}]] [[http://www.unleashnetworks.com|{{ :logo_web2.png|Unleash Logo}}]]

====== Unsniff Scripting Guide ======

===== Introduction =====

Unsniff Network Analyzer features is a new multi layer, content aware network protocol analyzer from Unleash Networks. It goes deeper than simple link layer packet analysis. In Unsniff. PDUs (reassembled packets into messages), TCP streams, content, annotations are all first class objects. Many network analysts are talented professionals who regularly write their own tools using scripting languages like Perl, Shell, Ruby, or VBScript. The Unsniff Scripting API delivers this power to the analyst. From monitoring digital certificates to checking for network performance problems – you can do it all via this  API.

The two features that really set Unsniff apart from the other tools are: 
  - **Scriptability **: Enables you to write your own powerful analysis scripts
  - **Extensibility **: Extend Unsniff by adding user interface elements or custom protocol decoders.

This document addresses the scriptability features of Unsniff. If you are interested in writing custom decoders (or) extending the Unsniff user interface – refer to the “Unsniff API Developers Guide”.



Read more:
  - [[unsniff:introduction| Getting started with Unsniff scripting]]

===== Objects Reference =====
All objects like Packets, PDUs, TCP Streams, are exposed as objects by the scripting API. A typical script would access top level objects and navigate downwards using the various methods and properties provided. 

Read more:
  - [[unsniff:scriptobjmod|Scripting Object Model Introduction]]

==== Methods and properties ====

 
  * [[unsniff:objectref:unsinffdb|Unsniff.Database]]
  * [[unsniff:objectref:collectionobj|Collection Objects]]
  * [[unsniff:objectref:packets|Packets]]
  * [[unsniff:objectref:layer|Layer]]
  * [[unsniff:objectref:field|Field]]
  * [[unsniff:objectref:pdu|PDU]]
  * [[unsniff:objectref:stream|Stream]]
  * [[unsniff:objectref:userobj|UserObject]]


===== Attaching scripts to the Unsniff user interface  =====

You can also write scripts that are executed when the user clicks on certain objects inside the Unsniff User Interface. For instance, you can launch a script to analyze selected packets by running a custom script. Currently, these user interface scripts must be in VBScript only. 

Read more:
  - [[unsniff:intrgscr|Integrated Scripts]]

===== Script Library =====

The Unsniff Scripting API allows you to write powerful snippets of Ruby or VBScript to accomplish very specific tasks. You get full access to reconstruction, protocol field details, TCP sessions, even user objects via the scripting API.


Read more:
[[unsniff:samples:samples|Samples]]


===== Common Problems =====

==== Library not registered ====

In some cases, the Unsniff Automation DLL (usnfaut.dll) is prevented from registering correctly by antivirus packages. If this happens you may encounter a // Library not registered // error as shown below.

<code dos>
C:\Users\Vivek\Documents\devbo\us\certxtract>ruby xcert.rb somecerts.usnf
xcert.rb:17:in `method_missing': unknown property or method: `Open' (NoMethodError)
    HRESULT error code:0x8002801d
      Library not registered.
        from xcert.rb:17:in `<main>'

</code>

To fix this register manually from a command prompt open as ** administrator ** .

<code dos>
C:\Windows\system32>cd "\Program Files\Unleash Networks\Unsniff\BIN"
C:\Program Files\Unleash Networks\Unsniff\BIN>regsvr32 usnfaut.dll
C:\Program Files\Unleash Networks\Unsniff\BIN>
</code>


==== Open Database Error ====

You cant have both the Unsniff user interface and your script open the same USNF file simultaneously. You have to open the script file as Read Only.

<code msdos>
C:\Users\Vivek\Documents\devbo\us\certxtract>ruby xcert.rb somecerts.usnf
xcert.rb:12:in `method_missing': (in OLE method `Open': ) (WIN32OLERuntimeError)
    OLE error code:80004005 in Unsniff.Database.1
      Open Database: Database Error
    HRESULT error code:0x80020009
      Exception occurred.
        from xcert.rb:12:in `<main>'

</code>

To fix this change '' Unsniff.Database.Open("t.usnf")'' to ** ''Unsniff.Database.OpenForRead("t.usnf")'' **

See the method [[unsniff:objectref:unsinffdb|OpenForRead]]