NetworkCaptureParams JobFile structure
1. NetworkCaptureParams element
  1. NICCaptureTasks element
  1. TempFolder element

NetworkCaptureParams JobFile structure

This section describes the settings available for configuring a Network Packet Capture job. Network Packet Capture is supported in all editions of Nuix Enterprise Collection Center 7.2 and newer.

The root element for a Network Packet Capture JobFile is a pair of <JobParameters>..</JobParameters> elements. The opening <JobParameters> tag appears just after the XML Declaration. This opening tag should include optional attributes for the XML namespace and schema, as follows:

<?xml version="1.0" encoding="UTF-16"?>

<JobParameters

xmlns="-//nuix.com/2014/CollectorEngine"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="-//nuix.com/2014/CollectorEngine

./CollectorEngine.xsd">

<!-- various "child" elements go here:

</NetworkCaptureParams>

</WorkerParameters>

</JobParameters>

Within the <JobParameters> element, the <WorkerParameters> child element contains a <NetworkCaptureParams> child element, as described below.

NetworkCaptureParams element

</NetworkCaptureParams>

</WorkerParameters>

The <NetworkCaptureParams> element contains no attributes or text value. It merely is the parent element for child elements which specify how network packets will be captured. These child elements are described below.

NICCaptureTasks element

</NICCaptureTasks>

</NetworkCaptureParams>

Contains one or more <NICCaptureTask> child elements which specify the network packet capture task(s) to perform.

NICCaptureTask element

</NICCaptureTask>

</NICCaptureTasks>

</NetworkCaptureParams>

Defines a network packet capture task. Settings are specified in child elements <Filter>, <NetworkCard> and <Target>, and in the following attributes:

The CaptureAllNetworkCards attribute can be set to "Yes" or "No":

Yes

Capture packets from each network card on the worker computer.

Capture packets from the network card specified by <NetworkCard>.

The CaptureTimeLength attribute specifies the amount of time to capture network packets, in seconds. A value of 60 (seconds) is typical.

The MaxCaptureFileSize attribute specifies the maximum file size to store captured packets, in kilobytes. Once the capture file reaches this size threshold, no further packet capture will occur.

The UsePromiscuousMode attribute can be set to "Yes" or "No":

Yes

Enable promiscuous mode to capture all available packets, including packets destined for other machines.

Do not enable promiscuous mode. Capture only packets destined for this worker computer.

In either mode, packets originating from the worker computer can also be captured - see the <Filter> child element.

Note: Promiscuous mode is more effective on networks using older network hubs, which do not isolate packets. Modern network switches and VLANs may restrict broad collection of network packets even when promiscuous mode is enabled.

Filter element

</NICCaptureTask>

Specifies which packets will be captured. Can be one of three values:

Value	Description
host {host}	Capture packets sent or received by this computer.
dst host {host}	Capture packets received by this computer.
src host {host}	Capture packets sent by this computer.

The above values must be entered as shown, in all lowercase.

NetworkCard element

</NetworkCard>

</NICCaptureTask>

Specifies the network adapter to capture from. These settings are ignored if the parent <NICCaptureTask> element has attribute CaptureAllNetworkCards set to "Yes".

Note: This setting may be ignored and CaptureAllNetworkCards forced to "Yes" in ECC version 7.2 and newer.

Name element

<Name>Local Area Connection</Name>

<Description>Primary gigabit network adapter</Description>

</NetworkCard>

</NICCaptureTask>

The text value of this element is the name of the network adapter to capture packets from.

Tip: For Windows computers, network adapter names can be seen from Control Panel > Network and Sharing Center > Change adapter settings.

From a Linux terminal, the command ifconfig -a will list the network adapters and their settings.

From a macOS terminal, the command
‎ networksetup –listallhardwareports
‎will list network adapter names (they appear as Devices).

Description element

<Name>Local Area Connection</Name>

<Description>Primary gigabit network adapter</Description>

</NetworkCard>

</NICCaptureTask>

A description of this network adapter.

Target element

</Target>

</NICCaptureTask>

Specifies where to save captured packets, and in what form.

The CreateFileSafe attribute can be set to "Yes" or "No":

Yes

Save the packet captures to a FileSafe specified by <FileSafePath>. The DoExtract attribute must be missing or set to "No".

Do not save the packet captures to a FileSafe.

The DoExtract attribute can be set to "Yes" or "No":

Yes

Save the packet captures to a file specified by <ExtractPath>. The CreateFileSafe attribute must be missing or set to "No".

Do not save the packet captures to a file.

The HashBlocks attribute specifies whether each chunk of data is hashed when being saved to a cloud destination, such as AmazonS3 or Azure Blob Storage. This attribute can be set to Yes or No:

Yes

As data is moved to the destination, each block of data is hashed before and after it is written. Enabling this feature requires more processing time.

No: The data is not hashed during the writing.

ExtractPath element

<ExtractPath Suffix="MyFolder">D:\Destination\MyFolder</ExtractPath>

</Target>

</NICCaptureTask>

Specifies the location for saving the captured network packet file. Note: The DoExtract attribute of the parent <Target> element must be set to "Yes".

The optional LoginUser attribute specifies the user ID for accessing the <ExtractPath>. Needed only when the <ExtractPath> resides on a password-protected network share.

The optional Password attribute specifies the password for accessing the <ExtractPath>. Needed only when the <ExtractPath> resides on a password-protected network share.

The optional LoginDomain attribute specifies the domain for accessing the <ExtractPath>. Needed only when the <ExtractPath> resides on a password-protected network share on an Active Directory domain.

The Suffix attribute specifies the portion of the <ExtractPath> value that represents the additional sub-folders to be created inside the destination folder specified by the user. When using ECC a typical value for Suffix is "Case\Collection\Custodian\Target\Native Copies", where blue values represent placeholders for the specified case, collection, etc. The New Collection Wizard in ECC Admin Console obtains the default Suffix value from the Job XML template.

FileSafePath element

<FileSafePath FileSafeName="MyFileSafe"

SegmentSizeMagnitude="GB"

SegmentSize="2"

Suffix="MyFolder"

Compression="None"

QuickValidate="No">

D:\Destination\MyFolder\MyFileSafe</FileSafePath>

</Target>

</NICCaptureTask>

Specifies the path and filename of the target FileSafe to be created, as well as various FileSafe options.

Note: The .mfs01 filename extension is omitted.

Note: The CreateFileSafe attribute of the parent <Target> element must be set to "Yes".

The FileSafeName attribute specifies the portion of the <FileSafePath> value that represents the "name" of the FileSafe. If the AlternateDestination path is used for the collection destination, a FileSafe named according to this attribute value will be created in the AlternateDestination path.

The SegmentSizeMagnitude attribute specifies the magnitude of the sizes of each segment in a multi-segment FileSafe. This attribute can be set to one of the following: KB: Kilobyte MB: Megabyte GB: Gigabyte

The SegmentSize attribute specifies a positive whole number to be applied to the SegmentSizeMagnitude attribute to specify the maximum size of each segment in a multi-segment FileSafe. For example: SegmentSizeMagnitude="GB" SegmentSize="2" will create 2 GB segments for the resulting FileSafe.

The Compression attribute specifies the compression level for a FileSafe. This setting can be set to one of the following:

None	No compression — largest FileSafe, with fewest CPU cycles
Medium	Medium compression — smaller FileSafe
High	High compression — smallest FileSafe, but highest CPU cycles (possibly slower, depending on CPU speed)

Note: High compression collections may run slower or faster than with medium or no compression, depending on the relative speeds of your network, hard disk(s) and CPU.

The QuickValidate attribute specifies whether to do a "Quick Validate" after the FileSafe is closed. A Quick Validate verifies that the FileSafe can be opened, and checks the number of files contained in it, but does not hash each file by reading the FileSafe contents. Quick Validate is a good option when the destination is a remote file share or cloud destination, where Post Validate would incur a significant performance penalty.

Yes

Perform a Quick Validate.

Perform a standard Post Validate. Enabling this feature requires more processing time.

The optional LoginUser attribute specifies the user ID for accessing the <FileSafePath>. Needed only when the <ExtractPath> resides on a password-protected network share.

The optional Password attribute specifies the password for accessing the <FileSafePath>. Needed only when the <FileSafePath> resides on a password-protected network share.

The optional LoginDomain attribute specifies the domain for accessing the <FileSafePath>. Needed only when the <FileSafePath> resides on a password-protected network share on an Active Directory domain.

The Suffix attribute specifies the portion of the <FileSafePath> value that represents the additional sub-folders to be created inside the destination folder specified by the user. When using ECC a typical value for Suffix is "Case\Collection\Custodian\Target\FileSafe", where blue values represent placeholders for the specified case, collection, etc. The New Collection Wizard in ECC Admin Console obtains the default Suffix value from the Job XML template.

AlternateDestination element

<FileSafePath FileSafeName="MyFileSafe"

SegmentSizeMagnitude="GB"

SegmentSize="2"

Suffix="MyFolder"

Compression="None">

D:\Destination\MyFolder\MyFileSafe</FileSafePath>

<AlternateDestination

Force="No"

LoginUser="Alice"

Password="G1sv4zz2#"

LoginDomain="MYCOMPANY">

\\OtherServer\AlternateShare

</AlternateDestination>

</Target>

</NICCaptureTask>

Optional. Specifies an alternate target folder path for the collection. This path does not specify any filename. It is used only if the primary destination specified in the <ExtractPath> or <FileSafePath> is not reachable.

Note: AlternateDestination, if present, can specify a local path, a network path, a URL for an Amazon S3 bucket, or a URL for a storage container within Azure Blob Storage. Saving to Azure Blob Storage is only available on PCs running Windows 7 / Windows Server 2008 R2 or newer, Linux 64-bit, or macOS. For details see the guidelines for Amazon S3 and Azure Blob Storage URLs under the topics ExtractPath element and FileSafePath element.

The AlternateDestination element has several attributes:

The Force attribute, if set to "Yes", ensures the AlternateDestination is used regardless of the accessibility of the primary destination. Otherwise, the AlternateDestination is used only if the primary destination is not accessible and writeable.

The LoginUser attribute specifies the user ID for accessing the <AlternateDestination> when it resides on a network path, an Amazon S3 bucket, or Azure Blob Storage. For an Amazon S3 bucket, this LoginUser attribute corresponds to the Access Key ID. For Azure, the LoginUser is the name of the Storage Account.

The Password attribute specifies the password for the above LoginUser. For an Amazon S3 bucket, this Password attribute corresponds to the Secret Access Key. For Azure, the Password attribute is the Access Key, which is generated at the time the Storage Account is created.

The optional LoginDomain attribute specifies the login domain for the above LoginUser. Omit this attribute when accessing workgroup shares via local users.

TempFolder element

</NICCaptureTasks>

<TempFolder>C:\Windows\TEMP</TempFolder>

</NetworkCaptureParams>

Optional setting to specify the temporary folder used during packet capture.