The NetShark class is the main interface to interact with a NetShark appliance. Among other things, it makes it possible to manage views, jobs, files and trace clips, and to query and modify the appliance settings.
Establishes a connection to a NetShark appliance.
Parameters: |
|
---|
See the base Service class for more information about additional functionality supported.
The following methods provide general information about the a NetShark:
The following methods are used to access view. Each of these methods returns a View.
The following methods are used to access packet sources (e.g., to obtain an object that can be used as an argument to create_view(), etc. The objects they return are described below in the section Packet Source Objects.
The following methods are used to work directly with trace files on the NetShark appliance filesystem:
The following methods are used to access extractor fields.
Complete method descriptions:
Create a clip in the NetShark appliance
Create a new directory. It will trigger an exception if the directory exist.
Returns: | a reference to the new directory |
---|
Create a Capture Job on this NetShark, and return it as a a capture job object that can be used to work with the new job.
Parameters: |
|
---|
Creates a merged file. ‘path’ is the new file full name and ‘files’ is a File objects list
Returns: | a reference to the new file |
---|
Creates a multisegment file. ‘path’ is the new file full name and ‘files’ is a File objects list
Returns: | a reference to the new file |
---|
Create a new view on this NetShark.
Parameters: |
|
---|---|
Returns: |
Create a new view on this NetShark using template.
For 9.5.x and earlier, template should be an XML view document, for later releases, template should be a JSON view description.
Returns: | View4 |
---|
Download log archive to local machine into path If path is None a temporary file is created
log_type can be:
case_id is an integer that represent the case id
Check if a path exists, works for files or directories.
Returns: | true if the path exists, false otherwise |
---|
Return a specific extractor field given its name
Return a CaptureJob object for the capture job jobname
If force_refetch is True, the list of jobs will be re-fetched from the NetShark. Otherwise, the list may be cached.
Return a list of CaptureJob objects, corresponding to the capture jobs currently running on the NetShark.
If force_refetch is True, the list of jobs will be re-fetched from the NetShark. Otherwise, the list may be cached.
Return a list of TraceClip objects, corresponding to the trace clips available on the NetShark.
If force_refetch is True, the list of clips will be re-fetched from the NetShark. Otherwise, the list may be cached.
Get a directory. It will trigger an exception if the directory does not exist.
Returns: | a reference to the directory |
---|
Return a list of all extractor fields available on this netshark
Given a path retrieve the File associated with it
Return a list of TraceFile, MergedFile or Multisegment objects, corresponding to the trace files available on the NetShark.
If force_refetch is True, the list of files will be re-fetched from the NetShark. Otherwise, the list may be cached.
Return an Interface object corresponding to the interface named ifname.
If force_refetch is True, the list of interfaces will be re-fetched from the NetShark. Otherwise, the list may be cached.
Return a list of Interface objects, corresponding to the capture interfaces available on the NetShark.
If force_refetch is True, the list of interfaces will be re-fetched from the NetShark. Otherwise, the list may be cached.
Return a dictionary with the information useful prior to logging in to the netshark, including the protocol version, banner, and whether or not a login purpose should be requested from the user.
Look up the view handle and return its View object
Get a list of View objects, one for each open view on the NetShark appliance.
Return the API protocol version used by this netshark.
Get the NetShark appliance overall info.
Returns: | a named tuple with the server parameters |
---|
Get the NetShark appliance storage info
Return a TraceClip object for the trace clip with the given description.
If force_refetch is True, the list of jobs will be re-fetched from the NetShark. Otherwise, the list may be cached.
Note: Clips don’t have descriptions by default. A description can be added to a clip by right-clicking on it in Pilot.
Returns the NetShark software model
Ping the probe.
Returns: | True/False depending whether the server is up and running or not |
---|
Restart the NetShark appliance. This will issue a system reboot.
Restart the NetShark probe. This will restart the Pilot server only.
Search through the extractor fields to find the ones that match the given string in either the field name or the description.
Uploads a new trace file. ‘path’ is the complete destination path, ‘local_file’ is the the local file to upload.
Returns: | reference to the new trace file |
---|
Returns the NetShark software version
The objects described in this section are used to access packet sources. None of these objects are directly instantiated from external code, they are returned by methods on NetShark or other routines. Any of the objects in this section may be used as the src argument to NetShark.create_view().
There are three basic data sources:
Capture job objects are used to work with capture jobs. These objects are not instantiated directly but are returned from NetShark.get_capture_jobs() and NetShark.get_capture_job_by_name().
Note
See Job4 if connecting to a NetShark using API 4.0
Bases: steelscript.netshark.core._source4.Job4
Capture job objects have the following properties:
The following methods access information about a job:
The following methods are useful for controlling a capture job:
The following methods can be used to create and delete jobs, though create() does the same thing as NetShark.create_clip().
Finally, these methods are useful for creating trace clips and for downloading raw packets from a capture job.
Complete method and property descriptions:
Create a new trace clip under this job.
filters limit which packets from the clip should go into this clip. Since all packets in the new clip will be kept on disk if the clip is locked, this field typically includes time filters to limit the clip to a fixed time interval.
description is a name for the clip, it is shown next to the clip in the Pilot user interface.
If locked is True, packets in the new clip will not be deleted from disk as long as the clip exists. Note that locking packets in trace clips necessarily reduces the amount of disk capacity for existing capture jobs.
Returns a trace clip object representing the new clip.
Clear data in the NetShark appliance
Create a new capture job
Delete job from the NetShark appliance
Download the Job packets to a path. If path is None packets will be exported to a temporary file. A file object that contains the packets is returned.
Get the complete list of capture jobs on given a NetShark.
netshark is an steelscript.netshark.core.netshark.NetShark object
Returns a list of CaptureJob objects
Return statistics about the capture job index.
Return the state of the job (e.g. RUNNING, STOPPED)
Return statistics about the capture job.
Return status information about the capture job.
The internal capture job handle. The handle is sometimes required for advanced operations on the job.
an Interface object, representing the interface used as a packet source for this job.
Can be used to determine if a source object is live or offline. The result is always False for a CaptureJob.
The capture job name
The capture job maximum size, corresponding to the one shown by the NetShark UI shows.
The capture job actual size, corresponding to the one shown by the NetShark UI shows.
Start a job in the NetShark appliance
Stop a job in the NetShark appliance
Update the data of the current object with new data from the server
Note
See Interface4 if connecting to a NetShark using API 4.0
Bases: steelscript.netshark.core._source4.Interface4
The interface description.
Can be used to determine if a source object is live or offline. The result is always True for an Interface4.
The interface device name.
Update current object with the values from the server
Trace clip objects are used to work with trace clips. These objects are not instantiated directly but are returned from methods such as NetShark.get_clips().
A trace clip packet source. These objects are returned by NetShark.get_clips.
Trace clip objects have the following properties:
These methods provide a way to obtain clip objects, though it is usually easier to use methods like NetShark.get_clips.
Complete method and property descriptions:
Create a new clip given a NetShark connection and a job handle.
netshark is a NetShark object
description will be associated with the new clip. (The description is shown near the clip in grey in Pilot)
job is the capture job to use
filters is the list of filters to associate to the clip. In order for the clip to be valid, there must be at list one time filter in this list
Returns a trace clip object for the new clip.
Erase the clip from netshark
Returns the description of the clip
Download the Clip packets to a file. If path is None packets will be exported to a temporary file. A file object that contains the packets is returned.
Get the complete list of trace files on given a NetShark.
netshark is an steelscript.netshark.core.netshark.NetShark object
Returns a list of TraceFile objects
Set or retrieve locked state of a clip
Returns the size of the clip
Return the path of a Clip used for the internal netshark representation
Extractor Field objects represent individual extractor fields. These objects are returned by NetShark.get_extractor_fields(), NetShark.find_extractor_field_by_name(), and NetShark.search_extractor_fields().
Each extractor field is a python namedtuple with the following fields:
View objects are returned from NetShark.create_view().
A View object encapsulates everything needed to read data from an existing view on a NetShark. Every view has one or more associated outputs. For example, the standard “Bandwidth over time” view has separate outputs for “bits over time”, “bytes over time”, and “packets over time”. In flyscript, a View object contains an associated Output object for each output. To read data from a view, you must first locate the appropriate Output object, then use the method Output4.get_data().
Return a list of Output objects, one for each output in this view
Close this view on the server (which permanently deletes the view plus any associated configuration and output data).
Returns the data from the output in this view. Shorthand for all_outputs()[0].get_data().
Raises a LookupError if the view has more than one output.
For a full description of the function arguments, refer to the method Output.get_data().
Returns an iterator for the data from the output in this view. Shorthand for all_outputs()[0].get_iterdata().
Raises a LookupError if the view has more than one output.
For a full description of the function arguments, refer to the method Output.get_iterdata()
Returns the legend from the output in this view. Shorthand for all_outputs()[0].get_legend().
Raises a LookupError if the view has more than one output.
Return the Output object corresponding to the output id.
For views applied to non-live sources (i.e., to trace clips or trace files), returns an integer between 0 and 100 indicating the percentage of the packet source that has been processed. Output data is not available on the view until this value reaches 100%
Return a dictionary object with details about the time range covered by this view. The returned object has the following entries:
This function adds a delta to the end time of the view provided by netshark If you need the timeinfo provided by netshark as it is use _get_timeinfo
Returns a boolean indicating whether data can be retrieved from this view or not. If this function returns False, the view data is still being computed, its progress can be followed with the method get_progress().
Bases: steelscript.netshark.core._interfaces.Output
Get the data for this view. This function downloads the whole dataset before returning it, so it’s useful when random access to the view data is necessary.
The arguments have the same meanings as corresponding arguments to get_iterdata(), see its documentation for a full explanation of all arguments and their meanings.
Returns an iterator to the output data. This function is ideal for sequential parsing of the view data, because it downloads the dataset incrementally as it is accessed.
start and end are datetime.datetime objects representing the earliest and latest packets that should be considered. If start and end are unspecified, the start/end of the underlying packet source are used.
delta is a datetime.timedelta object that can be used to override the default data aggregation interval. If this parameter is unspecified, the underlying view sample interval (which defaults to 1 second) is used. If this parameter is specified, it must be an even multiple of the underlying view sample interval.
If aggregated is True, the parameter delta is automatically computed to be the full extent of this request (i.e., the difference between the effective start and end times). This is useful if you do not care about timeseries data (e.g., if the data from this view is to be plotted in a single chart that has no time component).
The sortby parameter is one of the fields of the output (x1, x2 ...)
The sorttype can be: * ascending: the output is sorted from smallest to largest * descending: the output is sorted largest to smallest
The fromentry parameter represent the first sorted item we want to appear in the output. 0 means from the first one.
The toentry parameter represent the last sorted item we want to appear in the output. 0 means all of them.
Return the legend for this output. The legend consists of an ordered list of entries, one for each column of data in this output. Each entry is a dictionary object with the following entries:
The following parameters are intended for internal netshark use:
Filters are used to reduce the traffic that is fed to NetShark views, and are basic tools when doing data analysis with a NetShark Appliance. NetShark supports 4 main classes of filters: Time filters, the native NetShark filters, BPF filters (also known as Wireshark capture filters) and Wireshark display filters.
Create a TimeFilter representing a time range.
Parameters: |
|
---|
Creata a TimeFilter based on human readable string.
Parameters: | string (str) – time string |
---|
The string parameter can be any time range string such as:
This is a set of utility functions for working with views.
Utilities for writing view data
Print the data of a given view output to stdout.
widths is an optional list of integers, specifying how many characters wide each column should be. If it is not specified, reasonable defaults are chosen.
If limit is specified, only the first limit rows are printed.
line_prefix is a string that is printed at the start of every line.
Saves the data of a view output to a comma separated values (csv) file.
legend is an output legend, typically just the result of output.get_legend()
stream is a series of data samples, typically the result of output.get_data() or output.get_iterdata()
If include_column_names is True, the first line in the file will be a summary row indicating the fileds that the file contains.
If include_sample_times is True, the first column will be a timestamp.
Helper class that blends multiple data streams (ie from View.get_data) into a single combined stream. For example, given a “Bandwidth Over Time” view with separate outputs for bytes and packets, this class can be used to create a single output stream with bytes and packets columns.
Mixing is only supported on simple time-based views that do not include any keys (e.g., bandwidth over time, etc.)
See examples/netshark/readview.py for typical usage.
Mixing multiple view outputs
Add new source to mixer
src is time-based view object
Return a generator for the combined stream of outputs from each source object
Return the legend for each of the source objects