
If you are not a LiveAction Maintenance Customer but would like to purchase a Maintenance contract for your LiveAction product please click here for sales information.
Category : Scripts
Submitted By : Savvius
Downloaded : 306 Times
View Comments (0)
OmniScript
OmniScript is a Python module that provides access to Savvius Capture Engine for Omnipeek. This allows scripts to be written in the Python language that interacts, controls, and uses data from Savvius Engines.
OmniScript is ideal for environments where the same set of tests need to be run over and over, such as test labs and other network environments. It is also ideal for controlling any number of Engines with a single script. Imagine the time you will save! For a more detailed discussion on the ROI of automation, check out the WildPackets Automation Primer.

Installing OmniScript 2 Python
OmniScript 2 Python is provided as a zipped Python Egg file.
- Download and unzip the egg file.
- Download ez_setup.py
- Run: ez_setup.py OmniScript-0.5.3-py2.7.egg
Python
Savvius recommends ActivePython.)
OmniScript requires that you use a 32-bit release of Python, even on 64-bit Windows. OmniScript is not compatible with 64-bit releases of Python.
OmniScript Utilities
OmniScript 2 Python includes 2 scripts: RCapture.py and Forensics.py, and one command line utility. These utilities are useful as is, and are great starting points for enhancement or development of your own automation solution.
- RCapture.py: This is a Python script that provides many of the basic functions to create and collect data from Engine captures.
- Forensics.py: This Python script is a utility that can perform a forensics search against an Engine and return a packet file.
- pkt2dcd: This Windows command line utility decodes a pkt files to a decoded text files.
Using OmniScript
In the following examples, the RCapture utility is used to demonstrate the various connection options. Connecting to an Engine is going to be the same from any utility, except that the name of the parameters may be different.
Download and install the latest version of OmniScript 2 Python from the link on this page. Then start a DOS command line and browse to Python's home directory.
To view the list of adapters on an Engine running on Windows enter:
rcapture -e 10.4.2.50 -u UserName -w Password -l
rcapture -e 10.4.2.50 -t 'Third Party' -u UserName -w Password -l
rcapture -l
OmniScript Functions
There are two main types of OmniScript functions: Configuration and Data. Configuration functions are used to configure captures and forensic searches in different ways. Data functions are used to collect packets and statistics from existing captures and forensic searches.
Below are the types of configuration and data functions that can be performed from OmniScript:
Configuration Functions
- Connect to an Engine
- List adapters, captures and forensic searches
- Get and Set filters
- Build filters programmatically
- Create new captures with filters and triggers
- Create new captures from capture templates
- Create new forensic searches
- Bind to existing captures
- Open a packet file capture
- Start, stop, and delete captures
Data Functions
- Get the list of, or find one of the, adapters from the engine
- Get the list of, or find one of the, captures from the engine
- Get the list of, or find one of the, forensic files from the engine
- Get the list of, or find one of the, forensic searches from the engine
- Get node statistics of a capture or forensic search
- Get protocol statistics or forensic search
- Get summary statistics or forensic search
Connecting to an Engine
The very first thing you have to do with OmniScript when you are writing an OmniScript program is create an OmniScript object. The OmniScript object is used to connect to Engines. The OmniEngine object is used to communicate with Engines.
include omniscript omni=omniscript.OmniScript() engine=omni.connect() # or engine=omni.connect("1.2.3.4, 6367, auth, domain, user, password)
Of course, auth, domain, user and password need to be defined in your program. Auth can be either 'Default' or 'Thrid Party'. Domain may be an empty string, if the Engine is not in a domain.
Captures and Forensic Searches
Captures are created from CaptureTemplate objects and Forensic Searches are created from ForensicTemplate objects.
To create a live capture, either specify all of the attributes of the capture or use an existing capture template to set the majority of the attributes.
template=omniscript.CaptureTemplate('my_template.xml') template.name = 'My New Capture' capture = engine.create_capture(template)
Filters
Use the existing Filters on the Engine or create custom filters.
# Create a Filter: 1.2.3.4 <-> Any AND Port 80 simple = omniscript.Filter(�Simple Filter�) # Create an Address Node: 1.2.3.4 <-> Any addr_node = omniscript.AddressNode() addr_node.address_1 = omniscript.IPv4Address('1.2.3.4') addr_node.accept_1_to_2 = True addr_node.accept_2_to_1 = True # Create a Port Node for port 80. port_node = omniscript.PortNode() port_node.port = 80 # The Address node AND the Port node. # Each node also has an �or_node� attribute. addr_node.and_node = port_node # Set the criteria of the filter. simple.criteria= addr_node # Add the filter to the engine. engine.add_filter(simple)
OmniScript API
OmniScript uses the same underlying protocol that is used by the Omnipeek Console. This protocol is called PeekDNX, and is secure and compressed. Many of the things that can be done with the Omnipeek Console against an Engine, can also be done through OmniScript.
For more detailed reference information about the OmniScript 2 Python, download the zip file from the link on this page, unzip the file and open the index.html with a Web browser.
Scripts that come with OmniScript
RCapture
The OmniScript installation includes a command line script called RCapture.py. Running rcapture without any parameters displays the following usage:
RCapture [-c command] : Capture command - create, start, stop, save, reset, delete. [--template template : Capture template (optional) [-e engine ip=""] : IP address of engine. Default is localhost. [-p engine port=""] : default is 6367 [-t auth] : Authentication type either: 'Default' or 'Third Party'. [-d domain] : The domain of the credentials. [-u username="" : User account Name. [-w password] : Account Password. [-a index] : The adapter index. Use -l to list adapters. [-q description] : The adapter description. -a takes precedence. [--wireless_channel channel] : Set the wireless adapter channel by channel number. --wireless_frequency takes precedence. [--wireless_frequency frequency] : Set the wireless adapter channel by channel frequency [-n capture name=""] : Capture name. [-o filename] : Filename for template or saved packets (see --format when saving capture) [--format format : Save formats; pkt, enc, pcap, raw [-b size : Capture buffer size in megabytes. Default is 1MB. [-f path] : Save To Disk filename template. [-r hours : Restart - The number of hours to start a new file. Default is 24 hours [-m size : Save to Disk file size in megabytes. Default is Capture Buffer size or 1MB. [--reserve size gb="": Amount of disk space to use for capture, in GB (Timeline only) [-h filter name=""] : Add named filter to the capture [-i name:ip] : Create named IP address filter. [-I name:BPF] : Create named BPF/TCP Dump filter. [-j filter name=""] : Delete the named filter. [--sec seconds] : Seconds between start and stop [--min minutes] : Minutes between start and stop [-l] : List the adapters. [-g] : List the captures. [-y] : List the filters. [-s] : Statistics command - node or flow or summary or protocol, or combinations separated by comma. For example: '-s node,summary,protocol' [--csv] : Print the stats as csv output [-v level] : Verbose mode. [-?] : Display this message and quit.
Forensics Script
The forensics script performs a forensics search across a range of time over the files captured by the Engine. Below is the usage for the forensics script:
usage: forensics [-v] [-h hostname] [-d domain] [-a authentication] [-u username] [-p password] [-o output filename] [-s starttime (yy.mm.dd.hh.mm.ss)] [-e stoptime (yy.mm.dd.hh.mm.ss)] [-f filtername] [-t filename] [-m filemask] -v Verbose output. Chatty. -h IP of the Engine to connect to. Default is localhost -d Domain of the Engine to connect to. Only necessary if the Engine is part of a domain. -a If the Engine is linux, use "Third Party" -u Username (if the Engine is remote) -p Password (if the Engine is remote) -o Name of new packet file to put resulting packets into -s Start time of search (e.g. 10.07.01.12.00.00) -e End time of search (e.g. 10.07.01.12.00.01) -f Name of filter to use in search (e.g. HTTP or ARP) -t Name of file to search. Must use absolute path. -m Mask used to select files for search.
Statistical Reports
OmniScript provides functions to output node statistics, flow statistics, protocol statistics, and summary statistics. Each of these can be displayed in a pre-formatted fashion, or in .csv for loading into a spreadsheet, a database, or some other type application or integrated solution.
Summary Statistics
c:>rcapture -n "Test1" -s summary Summary Statistics for capture - Test1: General Packets Bytes Value ------------------------------------------------------------------------------- Start Date 0 0 12/17/2010 Start Time 0 0 22:25:03Z Duration 0 0 3d 0:29:24 Trigger Count 0 0 0 Trigger Wait Time 0 0 0:00:00 Dropped Packets 0 0 0 Network Packets Bytes Value ------------------------------------------------------------------------------- Total Bytes 0 491563050 0 Total Packets 2312676 0 0 Total Broadcast 1191139 108746597 0 Total Multicast 513064 89198439 0 Average Utilization (percent) 0 0 0.016 Average Utilization (bits/s) 0 0 15636 Current Utilization (percent) 0 0 0.025 Current Utilization (bits/s) 0 0 24576 Errors Packets Bytes Value ------------------------------------------------------------------------------- Total 0 0 0 CRC 0 0 0 Frame Alignment 0 0 0 Runt 0 0 0 Oversize 0 0 0 Counts Packets Bytes Value ------------------------------------------------------------------------------- Physical Addresses 0 0 269 IP Addresses 0 0 1695 IPv6 Addresses 0 0 110 AppleTalk Addresses 0 0 4 DECnet Addresses 0 0 0 IPX Addresses 0 0 6 Protocols 0 0 86 Size Distribution Packets Bytes Value ------------------------------------------------------------------------------- <= 64 1062681 0 0 65-127 514080 0 0 128-255 381445 0 0 256-511 130065 0 0 512-1023 47481 0 0 1024-1517 176827 0 0 >= 1518 97 0 0 Expert Packets Bytes Value ------------------------------------------------------------------------------- Flows Analyzed (Total) 0 0 26412 Flows Analyzed (Current) 0 0 26412 Flows Analyzed (Recycled) 0 0 0 Node Pairs Analyzed (Total) 0 0 1876 Node Pairs Analyzed (Current) 0 0 1876 Node Pairs Analyzed (Recycled) 0 0 0 Packets Dropped 0 0 0 -- Snip -- Spanning Tree Topology Change 0 0 0 EAP Authentication Failure 0 0 0 Too Many Physical Errors 0 0 0 MAC Flooding 0 0 0 Flow Tracker Packets Bytes Value ------------------------------------------------------------------------------- Flows (all) 0 0 26412 Flows (current) 0 0 26412 Flows (recycled) 0 0 0 Max 0 0 50000 Voice & Video Packets Bytes Value ------------------------------------------------------------------------------- Total Calls 0 0 78 Current Calls 0 0 78 Open Calls 0 0 0 Closed Calls 0 0 78 -- Snip -- MOS-AV 0 0 4.670 MOS-V 0 0 4.670 AppleTalk Analysis Packets Bytes Value ------------------------------------------------------------------------------- AARP Requests 1 64 0 AARP Responses 0 0 0 AARP Unanswered 1 0 0 AARP Probes 40 2560 0 AppleTalk Broadcast/Multicast 52 3382 0 Email Analysis Packets Bytes Value ------------------------------------------------------------------------------- SMTP Transfers Initiated 0 0 0 SMTP Successful Transfers 0 0 0 SMTP Failed Transfers 0 0 0 FTP Analysis Packets Bytes Value ------------------------------------------------------------------------------- FTP Transfers Initiated 0 0 0 FTP Successful Transfers 0 0 0 FTP Failed Transfers 0 0 0 ICMP Analysis Packets Bytes Value ------------------------------------------------------------------------------- Pings Unanswered 439 0 0 ICMP Packets 561 57901 0 Ping Responses 3 192 0 Ping Requests 442 45036 0 -- Snip -- ICMP Host Violation 0 0 0 ICMP Precedence Cutoff 0 0 0 IP Analysis Packets Bytes Value ------------------------------------------------------------------------------- TCP SYNs 28135 0 0 TCP FINs 13993 0 0 TCP RSTs 8556 0 0 ARP Requests 700390 45417344 0 ARP Responses 35415 2266642 0 ARPs Unanswered 664976 0 0 RARP Requests 187 11968 0 RARP Responses 0 0 0 RARPs Unanswered 187 0 0 NetWare Analysis Packets Bytes Value ------------------------------------------------------------------------------- RIP Unanswered 0 0 0 SAP Unanswered 0 0 735 NCP Unanswered 0 0 0 Newsgroup Analysis Packets Bytes Value ------------------------------------------------------------------------------- Newsgroup Accesses 0 0 0 VoIP Analysis Packets Bytes Value ------------------------------------------------------------------------------- H.225 RAS 0 0 0 H.323 0 0 0 H.225/Q.931 0 0 0 -- Snip -- GSM 9 1465 0 RTP Dynamic 263 31134 0
Protocol Statistics
c:>rcapture -n "Test1" -s protocol Protocol Statistics for capture - Test1: Protocol Packets Bytes ------------------------------------------------------------------------------- EType2 0 0 IP 0 0 UDP 98920 14674306 -- Snip -- TCP 179899 73873676 HTTP 303911 231954424
Node Statistics
c:>rcapture -n "Test1" -s node | more Node Statistics for capture - Test1: Node Packets Received Packets Sent Bytes Received Bytes Sent ------------------------------------------------------------------------------- 10.4.58.11 0 133225 0 12992902 10.4.255.255 418908 0 52065444 0 10.4.2.27 0 21136 0 2040078 -- Snip -- 10.4.7.131 0 1195 0 239803 10.4.4.23 0 366 0 98454
Flow Statistics
c:>rcapture -n "Test1" -s flow | more Flow statistics for capture - Test1: Source IP Destination IP Packets In Packets Out Bytes In Bytes Out Protocol ------------------------------------------------------------------------------- 10.4.58.11 10.4.255.255 0 132160 0 12687360 NB Name Svc 10.4.2.27 10.4.255.255 0 21097 0 2025744 NB Name Svc 10.4.2.114 10.4.255.255 0 366 0 90402 SMB -- Snip -- 10.4.4.24 10.4.255.255 0 366 0 98454 SMB 10.4.4.42 10.4.255.255 0 366 0 98454 SMB
Using pkt2dcd
pkt2dcd requires the file path and name of the pkt file, followed by the path and name of the resulting decoded file. The following example will convert "http.pkt" to a decoded text file name "decoded_http.txt"
pkt2dcd.exe "c:http.pkt" "c:decoded_http.txt"
The supported decodes that come with OmniScript are a very basic set. If you have decodes of your own you wish to use, copy your decodes.bin file from:
C:Prorgam FilesSavviusOmnipeekdecodesdecodes.bin
to:
C:Python27Libsite-packagesOmniScript-0.5.3-py27.eggomniscriptDecodes
History
1/25/18 OmniScript 2.0 Python v0.5.3-50
- Audit and event log support
- Application and country statistics.
- Wireless adapter support, see the Tutorial in the documentation.
3/16/17 OmniScript 2.0 Python v0.5.3-39
- Omni 10 support. Lots of additional functionality.
8/19/14 OmniScript 2.0 Python v0.5.2
- Initial public release.