Trigger API Reference

Instance methods

The methods in this section cannot be called directly on the Application class. You can only call these methods on specific Application class instances. For example, the following statement is valid:

Application("sampleApp").metricAddCount("responses", 1);

However, the following statement is invalid:

Application.metricAddCount("responses", 1);

commit(id: String): void

Creates an application, commits built-in metrics associated with the event to the application, and adds the application to any built-in or custom records committed during the event.

The application ID must be a string. For built-in application metrics, the metrics are committed only once, even if the commit() method is called multiple times on the same event.

The following statement creates an application named "myApp" and commits built-in metrics to the application:

Application("myApp").commit();

Copy

If you plan to commit custom metrics to an application, you can create the application without calling the commit() method. For example, if the application does not already exist, the following statement creates the application and commits the custom metric to the application:

Application("myApp").metricAddCount("requests", 1);

Copy

You can call the Application.commit method only on the following events:

Metric types	Event
AAA	AAA_REQUEST -and- AAA_RESPONSE
AJP	AJP_RESPONSE
CIFS	CIFS_RESPONSE
DB	DB_RESPONSE
DHCP	DHCP_REQUEST -and- DHCP_RESPONSE
DNS	DNS_REQUEST -and- DNS_RESPONSE
FIX	FIX_REQUEST -and- FIX_RESPONSE
FTP	FTP_RESPONSE
HTTP	HTTP_RESPONSE
IBMMQ	IBMMQ_REQUEST -and- IBMMQ_RESPONSE
ICA	ICA_TICK -and- ICA_CLOSE
Kerberos	KERBEROS_REQUEST -and- KERBEROS_RESPONSE
LDAP	LDAP_REQUEST -and- LDAP_RESPONSE
Memcache	MEMCACHE_REQUEST -and- MEMCACHE_RESPONSE
Modbus	MODBUS_RESPONSE
MongoDB	MONGODB_REQUEST -and- MONGODB_RESPONSE
NAS	CIFS_RESPONSE -and/or- NFS_RESPONSE
NetFlow	NETFLOW_RECORD Note that the commit will not occur if enterprise IDs are present in the NetFlow record.
NFS	NFS_RESPONSE
RDP	RDP_TICK
Redis	REDIS_REQUEST -and- REDIS_RESPONSE
RPC	RPC_REQUEST -and- RPC_RESPONSE
RTP	RTP_TICK
RTCP	RTCP_MESSAGE
SCCP	SCCP_MESSAGE
SIP	SIP_REQUEST -and- SIP_RESPONSE
SFlow	SFLOW_RECORD
SMTP	SMTP_RESPONSE
SSH	SSH_CLOSE -and- SSH_TICK
SSL	SSL_RECORD -and- SSL_CLOSE
WebSocket	WEBSOCKET_OPEN, WEBSOCKET_CLOSE, and WEBSOCKET_MESSAGE

metricAddCount(metric_name: String, count: Number, options: Object):void

Creates a custom top-level count metric. Commits the metric data to the specified application.

metric_name: String

The name of the top-level count metric.

count: Number

The increment value. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following property:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailCount(metric_name: String, key: String | IPAddress, count: Number, options: Object):void

Creates a custom detail count metric by which you can drill down. Commits the metric data to the specified application.

metric_name: String

The name of the detail count metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

count: Number

The increment value. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following property:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDataset(metric_name: String, val: Number, options: Object):void

Creates a custom top-level dataset metric. Commits the metric data to the specified application.

metric_name: String

The name of the top-level dataset metric.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

freq: Number

An option that enables you to simultaneously record multiple occurrences of particular values in the dataset when set to the number of occurrences specified by the val parameter. If no value is specified, the default value is 1.

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailDataset(metric_name: String, key: String | IPAddress, val: Number, options: Object):void

Creates a custom detail  dataset metric by which you can drill down. Commits the metric data to the specified application.

metric_name: String

The name of the detail count metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

freq: Number

An option that enables you to simultaneously record multiple occurrences of particular values in the dataset when set to the number of occurrences specified by the val parameter. If no value is specified, the default value is 1.

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDistinct(metric_name: String, item: Number | String | IPAddress:void

Creates a custom top-level distinct count metric. Commits the metric data to the specified application.

metric_name: String

The name of the top-level distinct count metric.

item: Number | String | IPAddress

The value to be placed into the set. The value is converted to a string before it is placed in the set.

metricAddDetailDistinct(metric_name: String, key: String | IPAddress, item: Number | String | IPAddress:void

Creates a custom detail distinct count metric by which you can drill down. Commits the metric data to the specified application.

metric_name: String

The name of the detail distinct count metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

item: Number | String | IPAddress

The value to be placed into the set. The value is converted to a string before it is placed in the set.

metricAddMax(metric_name: String, val: Number, options: Object):void

Creates a custom top-level maximum metric. Commits the metric data to the specified application.

metric_name: String

The name of the top-level maximum metric.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailMax(metric_name: String, key: String | IPAddress, val: Number, options: Object):void

Creates a custom detail maximum metric by which you can drill down. Commits the metric data to the specified application.

metric_name: String

The name of the detail maximum metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddSampleset(metric_name: String, val: Number, options: Object):void

Creates a custom top-level sampleset metric. Commits the metric data to the specified application.

metric_name: String

The name of the top-level sampleset metric.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailSampleset(metric_name: String, key: String | IPAddress, val: Number, options: Object):void

Creates a custom detail sampleset metric by which you can drill down. Commits the metric data to the specified application.

metric_name: String

The name of the detail sampleset metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddSnap(metric_name: String, count: Number, options: Object):void

Creates a custom top-level snapshot metric. Commits the metric data to the specified application.

metric_name: String

The name of the top-level snapshot metric.

count: Number

The observed value, such as current established connections. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailSnap(metric_name: String, key: String | IPAddress, count: Number, options: Object):void

Creates a custom detail snapshot metric by which you can drill down. Commits the metric data to the specified application.

metric_name: String

The name of the detail sampleset metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

count: Number

The observed value, such as current established connections. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

toString(): String

Returns the Application object as a string in the following format:

[object Application <application_id>]

Copy

Instance properties

id: String

The unique ID of the application, as shown in the ExtraHop system on the page for that application.

Trigger examples

• Example: Create an application container

A buffer is an object with the characteristics of an array. Each element in the array is a number between 0 and 255, representing one byte. Each buffer object has a length property (the number of items in an array) and a square bracket operator.

Encrypted payload is not decrypted for TCP and UDP payload analysis.

UDP_PAYLOAD requires a matching string but TCP_PAYLOAD does not. If you do not specify a matching string for TCP_PAYLOAD, the trigger runs one time after the first N bytes of payload.

Instance methods

decode(type: String): String

Interprets the contents of the buffer and returns a string with one of the following options:

• utf-8
• utf-16
• ucs2
• hex

equals(buffer: Buffer): Boolean

Performs an equality test between Buffer objects, where buffer is the object to be compared against.

slice(start: Number, end: Number): Buffer

Returns the specified bytes in a buffer as a new buffer. Bytes are selected starting at the given start argument and ending at (but not including) the end argument.

start: Number

Integer that specifies where to start the selection. Specify negative numbers to select from the end of a buffer. This is zero-based.

end: Number

Optional integer that specifies where to end the selection. If omitted, all elements from the start position and to the end of the buffer will be selected. Specify negative numbers to select from the end of a buffer. This is zero-based.

toString(format: String): String

Converts the buffer to a string. The following parameter is optional:

format: String

The format to encode the string with. If no encoding is specified, the string is unencoded. The following encoding formats are valid:

• base64
• base64url
• hex

unpack(format: String, offset: Number): Array

Processes binary or fixed-width data from any buffer object, such as one returned by HTTP.payload, Flow.client.payload, or Flow.sender.payload, according to the given format string and, optionally, at the specified offset.

Returns a JavaScript array that contains one or more unpacked fields and contains the absolute payload byte position +1 of the last byte in the unpacked object. The bytes value can be specified as the offset in further calls to unpack a buffer.

Note:

The buffer.unpack method interprets bytes in big-endian order by default. To interpret bytes in little-endian order, prefix the format string with a less than sign (<). The format does not have to consume the entire buffer. Null bytes are not included in unpacked strings. For example: buf.unpack('4s')[0] - > 'example'. The z format character represents variable-length, null-terminated strings. If the last field is z, the string is produced whether or not the null character is present. An exception is throw when all of the fields cannot be unpacked because the buffer does not contain enough data.

The table below displays supported buffer string formats:

Format	C type	JavaScript type	Standard size
x	pad type	no value
A	struct in6_addr	IPAddress	16
a	struct in_addr	IPAddress	4
b	signed char	string of length 1	1
B	unsigned char	number	1
?	_Bool	boolean	1
H	unsigned short	number	2
h	short	number	2
i	int	number	4
I	unsigned int	number	4
l	long	number	4
L	unsigned long	number	4
q	long long	number	8
Q	unsigned long long	number	8
f	number	number	4
d	double	number	4
s	char[]	string
z	char[]	string

Instance Properties

length: Number

The number of bytes in the buffer.

Trigger Examples

• Example: Parse NTP with universal payload analysis
• Example: Parse syslog over TCP with universal payload analysis

Events

DETECTION_UPDATE

Runs when a detection is created or updated on the ExtraHop system.

Important:

This event runs for all detections, regardless of the module access granted to the user who creates the trigger. For example, triggers created by users with NPM module access run on DETECTION_UPDATE events for both security and performance detections.

Note:

This event does not run when a detection ticket status is updated. For example, changing a detection assignee will not cause the DETECTION_UPDATE event to run. This event also does not run for hidden detections.

Note:

You cannot assign triggers that run only on this event to specific devices or device groups. Triggers that run on this event will run whenever this event occurs.

Properties

applianceId: Number

If called on a console, returns the ID of the connected sensor that the detection occurred on. If called on a sensor, returns 0.

assignee: String

The assignee of the ticket associated with the detection.

categories: Array of Strings

The list of categories the detection belongs to.

description: String

The description of the detection.

Tip:	It is often easier to extract information about a detection from the Detection.properties property than parsing the Detection.description text. For more information, see the Detection.properties description.

The following table shows common Markdown formats that you can include in the description:

Format	Description	Example
Headings	Place a number sign (#) and a space before your text to format headings. The level of heading is determined by the amount of number signs.	#### Example H4 heading
Unordered lists	Place a single asterisk (*) before your text. If possible, put each list item on a separate line.	* First example * Second example
Ordered lists	Place a the number 1 and period (1.) before your text for each line item; Markdown will automatically increment the list number. If possible, put each list item on a separate line.	1. First example 1. Second example
Bold	Place double asterisks before and after your text.	**bold text**
Italics	Place an underscore before and after your text.	_italicized text_
Hyperlinks	Place link text in brackets before the URL in parentheses. Or type your URL. Links to external websites open in a new browser tab. Links within the ExtraHop system, such as dashboards, open in the current browser tab.	[Visit our home page](https://www.extrahop.com) https://www.extrahop.com
Blockquotes	Place a right angle bracket and a space before your text.	On the ExtraHop website: > Access the live demo and review case studies.
Emojis	Copy and paste an emoji image into the text box. See the Unicode Emoji Chart website for images. Markdown syntax does not support emoji shortcodes.

endTime: Number

The time that the detection ended, expressed in milliseconds since the epoch.

id: Number

The unique identifier for the detection.

isCustom: Boolean

The value is true if the detection is a custom detection generated by a trigger.

mitreCategories: Array of Objects

An array of objects that contains the MITRE techniques and tactics associated with the detection. Each object contains the following properties:

id

The ID of the MITRE technique or tactic.

name

The name of the MITRE technique or tactic.

url

The web address of the technique or tactic on the MITRE website.

participants: Array of Objects

An array of participant objects associated with the detection. A participant object contains the following properties:

object: Object

The Device, Application, or IP address object associated with the participant.

id: Number

The ID of the participant.

role: String

The role of the participant in the detection. The following values are valid:

• offender
• victim

properties: Object

An object that contains the properties of the detection. Only built-in detection types include detection properties. The detection type determines which properties are available.

The field names of the object are the names of the detection properties. For example, the Anonymous FTP Auth Enabled detection type includes the client_port property, which you can access with the following code:

Detection.properties.client_port

Copy

To view detection property names, view detection types with the GET /detections/formats operation in the ExtraHop REST API.

Tip:

In the trigger editor, you can view valid detection properties with the autocomplete functionality if you include logic that determines the detection type. For example, if the trigger contains the following code, and you type a period after "properties", the trigger editor displays the valid properties for the Anonymous FTP Auth Enabled detection: if (Detection.type === 'anonymous_ftp') { Detection.properties } Copy

resolution: String

The resolution of the ticket associated with the detection. Valid values are action_taken and no_action_taken.

riskScore: number | null

The risk score of the detection.

startTime: Number

The time that the detection started, expressed in milliseconds since the epoch.

status: String

The status of the ticket associated with the detection. Valid values are acknowledged, new, in_progress, and closed.

ticketId: String

The ID of the ticket associated with the detection.

title: String

The title of the detection.

type: String

The type of detection. For custom detections, "custom" is prepended to the user-defined string. For example, if you specify brute_force_attack in the commitDetection function, the detection type is custom.brute_force_attack.

updateTime: Number

The last time that the detection was updated, expressed in milliseconds since the epoch.

Methods

Device(id: String)

Constructor for the Device object that accepts one parameter, which is a unique 16-character string ID.

If supplied with an ID from an existing Device object, the constructor creates a copy of that object with all of the object properties, as shown in the following example:

myDevice = new Device(Flow.server.device.id);
debug("myDevice MAC: " + myDevice.hwaddr);

Copy

Metrics committed to a Device object through a metricAdd* function are persisted to the datastore

lookupByIP(addr: IPAddress | String, vlan: Number): Device

Returns the L3 device that matches the specified IP address and VLAN ID. Returns null if no match is found.

addr: IPAddress | String

The IP address for the device. The IP address can be specified as an IPAddress object or as a string.

vlan: number

The VLAN ID for the device. Returns a default value of 0 if a VLAN ID is not provided or if the value of the devices_across_vlans settings is set to true in the running configuration file.

lookupByMAC(addr: String, vlan: Number): Device

Returns the L2 device that matches the specified MAC address and VLAN ID. Returns null if no match is found.

addr: String

The MAC address for the device.

vlan: Number

The VLAN ID for the device. Returns a default value of 0 if a VLAN ID is not provided or if the value of the devices_across_vlans settings is set to true in the running configuration file.

toString(): String

Returns the Device object as a string in the following format:

[object Device <discovery_id>]

Copy

Instance methods

The methods described in this section are present only on instances of the Device class. The majority of the methods enable you to create device-level custom metrics, as shown in the following example:

Flow.server.device.metricAddCount("slow_rsp", 1);

equals(device: Device): Boolean

Performs an equality test between Device objects, where device is the object to be compared against.

metricAddCount(metric_name: String, count: Number, options: Object):void

Creates a custom top-level count metric. Commits the metric data to the specified device.

metric_name: String

The name of the top-level count metric.

count: Number

The increment value. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following property:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailCount(metric_name: String, key: String | IPAddress, count: Number, options: Object):void

Creates a custom detail count metric by which you can drill down. Commits the metric data to the specified device.

metric_name: String

The name of the detail count metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

count: Number

The increment value. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following property:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDataset(metric_name: String, val: Number, options: Object):void

Creates a custom top-level dataset metric. Commits the metric data to the specified device.

metric_name: String

The name of the top-level dataset metric.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

freq: Number

An option that enables you to simultaneously record multiple occurrences of particular values in the dataset when set to the number of occurrences specified by the val parameter. If no value is specified, the default value is 1.

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailDataset(metric_name: String, key: String | IPAddress, val: Number, options: Object):void

Creates a custom detail dataset metric by which you can drill down. Commits the metric data to the specified device.

metric_name: String

The name of the detail count metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

freq: Number

An option that enables you to simultaneously record multiple occurrences of particular values in the dataset when set to the number of occurrences specified by the val parameter. If no value is specified, the default value is 1.

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDistinct(metric_name: String, item: Number | String | IPAddress:void

Creates a custom top-level distinct count metric. Commits the metric data to the specified device.

metric_name: String

The name of the top-level distinct count metric.

item: Number | String | IPAddress

The value to be placed into the set. The value is converted to a string before it is placed in the set.

metricAddDetailDistinct(metric_name: String, key: String | IPAddress, item: Number | String | IPAddress:void

Creates a custom detail distinct count metric by which you can drill down. Commits the metric data to the specified device.

metric_name: String

The name of the detail distinct count metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

item: Number | String | IPAddress

The value to be placed into the set. The value is converted to a string before it is placed in the set.

metricAddMax(metric_name: String, val: Number, options: Object):void

Creates a custom top-level maximum metric. Commits the metric data to the specified device.

metric_name: String

The name of the top-level maximum metric.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailMax(metric_name: String, key: String | IPAddress, val: Number, options: Object):void

Creates a custom detail maximum metric by which you can drill down. Commits the metric data to the specified device.

metric_name: String

The name of the detail maximum metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddSampleset(metric_name: String, val: Number, options: Object):void

Creates a custom top-level sampleset metric. Commits the metric data to the specified device.

metric_name: String

The name of the top-level sampleset metric.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailSampleset(metric_name: String, key: String | IPAddress, val: Number, options: Object):void

Creates a custom detail sampleset metric by which you can drill down. Commits the metric data to the specified device.

metric_name: String

The name of the detail sampleset metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddSnap(metric_name: String, count: Number, options: Object):void

Creates a custom top-level snapshot metric. Commits the metric data to the specified device.

metric_name: String

The name of the top-level snapshot metric.

count: Number

The observed value, such as current established connections. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailSnap(metric_name: String, key: String | IPAddress, count: Number, options: Object):void

Creates a custom detail snapshot metric by which you can drill down. Commits the metric data to the specified device.

metric_name: String

The name of the detail sampleset metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

count: Number

The observed value, such as current established connections. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

Instance properties

The following properties enable you to retrieve device attributes and are present only on instances of the Device class.

cdpName: String

The CDP name associated with the device, if present.

dhcpName: String

The DHCP name associated with the device, if present.

discoverTime: Number

The last time the capture process discovered the device (not the original discovery time), expressed in milliseconds since the epoch (January 1, 1970). Previously discovered devices can be rediscovered by the capture process if they become idle and later become active again, or if the capture process is restarted.

To direct a trigger to run only on the initial discovery of a device, see the NEW_DEVICE event discussed in the Discover class.

dnsNames: Array

An array of strings listing the DNS names associated with the device, if present.

hasTrigger: Boolean

The value is true if a trigger assigned to the Device object is currently running.

If the trigger is running on an event associated with a Flow object, the hasTrigger property value is true on at least one of the Device objects in the flow.

The hasTrigger property is useful to distinguish device roles. For example, if a trigger is assigned to a group of proxy servers, you can easily determine whether a device is acting as the client or the server, rather than checking for IP addresses or device IDs, such as in the following example:

//Event: HTTP_REQUEST
if (Flow.server.device.hasTrigger) {
    // Incoming request
} else {
    // Outgoing request
}

Copy

hwaddr: String

The MAC address of the device, if present.

id: String

The 16-character unique ID of the device, as shown in the ExtraHop system on the page for that device.

ipaddrs: Array

An array of IPAddress objects representing the device's known IP addresses. For L3 devices, the array always contains one IPAddress.

isGateway: Boolean

The value is true if the device is a gateway.

isL3: Boolean

The value is true if the device is an L3 child device.

Important:

If you have not enabled the ExtraHop system to discover devices by IP address, the isL3 property is always set to False because the system does not make a distinction between L3 child and L2 parent devices.

netbiosName: String

The NetBIOS name associated with the device, if present.

vlanId: Number

The VLAN ID for the device.

Trigger Examples

• Example: Monitor CIFS actions on devices
• Example: Track 500-level HTTP responses by customer ID and URI
• Example: Collect response metrics on database queries
• Example: Send discovered device data to a remote syslog server
• Example: Access HTTP header attributes
• Example: Record Memcache hits and misses
• Example: Parse memcache keys
• Example: Parse custom PoS messages with universal payload analysis
• Example: Add metrics to the metric cycle store

Events

NEW_APPLICATION

Runs when an application is first discovered. This event consumes capture resources.

Note:

You cannot assign triggers that run only on this event to specific devices or device groups. Triggers that run on this event will run whenever this event occurs.

NEW_DEVICE

Runs when activity is first observed on a device. This event consumes capture resources.

Note:

You cannot assign triggers that run only on this event to specific devices or device groups. Triggers that run on this event will run whenever this event occurs.

Properties

application: Application

A newly discovered application.

Applies only to NEW_APPLICATION events.

device: Device

A newly discovered device.

Applies only to NEW_DEVICE events.

Note:

You cannot specify this property as a participant in the commitDetection function.

Trigger Examples

• Example: Send discovered device data to a remote syslog server

Events

If a flow is associated with an ExtraHop-monitored L7 protocol, events that correlate to the protocol will run in addition to flow events. For example, a flow associated with HTTP will also run the HTTP_REQUEST and HTTP_RESPONSE events.

FLOW_CLASSIFY

Runs whenever the ExtraHop system initially classifies a flow as being associated with a specific protocol.

Note:

For TCP flows, the FLOW_CLASSIFY event runs after the TCP_OPEN event.

Through a combination of L7 payload analysis, observation of TCP handshakes, and port number-based heuristics, the FLOW_CLASSIFY event identifies the L7 protocol and the device roles for the endpoints in a flow such as client/server or sender/receiver.

The nature of a flow can change over its lifetime, for example, tunneling over HTTP or switching from SMTP to SMTP-SSL. In these cases, FLOW_CLASSIFY runs again after the protocol change.

The FLOW_CLASSIFY event is useful for initiating an action on a flow based on the earliest knowledge of flow information such as the L7 protocol, client/server IP addresses, or sender/receiver ports.

Common actions initiated upon FLOW_CLASSIFY include starting a packet capture through the captureStart() method or associating the flow with an application container through the addApplication() method.

Additional options are available when you create a trigger that runs on this event. By default, FLOW_CLASSIFY does not run upon flow expiration; however, you can configure a trigger to do so in order to accumulate metrics for flows that were not classified before expiring. See Advanced trigger options for more information.

FLOW_DETACH

Runs when the parser has encountered an unexpected error or has run out of memory and stops following the flow. In addition, a low quality data feed with missing packets can cause the parser to detach.

The FLOW_DETACH event is useful for detecting malicious content sent by clients and servers. The following is an example of how a trigger can detect bad DNS responses upon FLOW_DETACH events:

if (event == "FLOW_DETACH" && Flow.l7proto== "DNS") {
    Flow.addApplication("Malformed DNS");
}

Copy

FLOW_RECORD

Enables you to record information about a flow at timed intervals. After FLOW_CLASSIFY has run, the FLOW_RECORD event will run every N seconds and whenever a flow closes. The default value for N, known as the publish interval, is 30 minutes; the minimum value is 60 seconds. You can set the publish interval in the Administration settings.

FLOW_TICK

Enables you to record information about a flow per amount of data or per turn. The FLOW_TICK event will run on every FLOW_TURN or every 128 packets, whichever occurs first. Also, L2 data is reset on every FLOW_TICK event which enables you to add data together at each tick. If counting throughput, collect data from FLOW_TICK events which provide more complete metrics than FLOW_TURN.

FLOW_TICK provides a means to periodically check for certain conditions on the flow, such as zero windows and Nagle delays, and then take an action, such as initiating a packet capture or sending a syslog message.

The following is an example of FLOW_TICK:

log("RTT " + Flow.roundTripTime);
Remote.Syslog.info(
  " eh_event=FLOW_TICK" +
  " ClientIP="+Flow.client.ipaddr+
  " ServerIP="+Flow.server.ipaddr+
  " ServerPort="+Flow.server.port+
  " ServerName="+Flow.server.device.dnsNames[0]+
  " RTT="+Flow.roundTripTime);

Copy

FLOW_TURN

Runs on every TCP or UDP turn. A turn represents one full cycle of a client transferring request data followed by a server transferring a response.

FLOW_TURN also exposes a Turn object.

Methods

addApplication(name: String, turnTiming: Boolean): void

Creates an application with the specified name and collects L2-L4 metrics from the flow. The application can be viewed in the ExtraHop system and the metrics are displayed on an L4 page in the application. A flow can be associated with one or more applications at a given instant; the L2-L4 metrics collected by each application will be the same.

Calling Flow.addApplication(name) on a FLOW_CLASSIFY event is common on unsupported protocols. For flows on supported protocols with L7 trigger events, it is recommended to call the Application(name).commit() method, which collects a larger set of protocol metrics.

The optional turnTiming flag is set to false by default. If set to true, the ExtraHop system collects additional turn timing metrics for the flow. If this flag is omitted, no turn timing metrics are recorded for the application on the associated flow. Turn timing analysis analyzes L4 behavior in order to infer L7 processing times when the monitored protocol follows a client-request, server-response pattern and in which the client sends the first message. "Banner" protocols (where the server sends the first message) and protocols where data flows in both directions concurrently are not recommended for turn timing analysis.

captureStart(name: String, options: Object): String

Initiates a Precision Packet Capture (PPCAP) for the flow and returns a unique identifier of the packet capture in the format of a decimal number as a string. Returns null if the packet capture fails to start.

name: String

The name of the packet capture file.

• The maximum length is 256 characters
• A separate capture is created for each flow.
• Capture files with the same name are differentiated by timestamps.

options: Object

The options contained in the capture object. Omit any of the options to indicate unlimited size for that option. All options apply to the entire flow except the "lookback" options which apply only to the part of the flow before the trigger event that started the packet capture.

maxBytes: Number

The total maximum number of bytes.

maxBytesLookback: Number

The total maximum number of bytes from the lookback buffer. The lookback buffer refers to packets captured before the call to Flow.captureStart().

maxDurationMSec: Number

The maximum duration of the packet capture, expressed in milliseconds.

maxPackets: Number

The total maximum number of packets. The maximum value might be exceeded if the trigger load is heavy.

maxPacketsLookback: Number

The maximum number of packets from the lookback buffer. The lookback buffer refers to packets captured before the call to Flow.captureStart().

The following is an example of Flow.captureStart():

// EVENT: HTTP_REQUEST
// capture facebook HTTP traffic flows
if (HTTP.uri.indexOf("www.facebook.com") !== -1) {
   var name = "facebook-" + HTTP.uri;
   //packet capture options: capture 20 packets, up to 10 from the lookback buffer
   var opts = {
      maxPackets: 20,
      maxPacketsLookback: 10
   };
   Flow.captureStart(name, opts);
}

Copy

Note:

The Flow.captureStart() function call requires that you have a license for precision packet capture. You can specify the number of bytes per packet (snaplen) you want to capture when configuring the trigger in the ExtraHop system. This option is available only on some events. See Advanced trigger options for more information. On ExtraHop Performance systems, captured files are available in the Administration settings. On Reveal(x) systems, captured files are available from the Packets page in the ExtraHop system. On ExtraHop Performance systems, if the precision packet capture disk is full, no new captures are recorded until the user deletes the files manually. On Reveal systems, older packet captures are deleted when the precision packet capture disk becomes full to enable the system to continue recording new packet captures. The maximum file name string length is 256 characters. If the name exceeds 256 characters, it will be truncated and a warning message will be visible in the debug log, but the trigger will continue to execute. The capture file size is the whichever maximum is reached first between the maxPackets and maxBytes options. The size of the capture lookback buffer is whichever maximum is reached first between the maxPacketsLookback and maxBytesLookback options. Each passed max* parameter will capture up to the next packet boundary. If the packet capture was already started on the current flow, Flow.captureStart() calls result in a warning visible in the debug log, but the trigger will continue to run. There is a maximum of 128 concurrent packet captures in the system. If that limit is reached, subsequent calls to Flow.captureStart() will generate a warning visible in the debug log, but the trigger will continue to execute.

captureStop(): Boolean

Stops a packet capture that is in progress on the current flow.

commitRecord1(): void

Sends a record to the configured recordstore that represents data sent from device1 in a single direction on the flow.

You can call this method only on FLOW_RECORD events, and each unique record is committed only once for built-in records.

To view the properties committed to the record object, see the record property below.

commitRecord2(): void

Sends a record to the configured recordstore that represents data sent from device2 in a single direction on the flow.

You can call this method only on FLOW_RECORD events, and each unique record is committed only once for built-in records.

To view the properties committed to the record object, see the record property below.

findCustomDevice(deviceID: String): Device

Returns a single Device object that corresponds to the specified deviceID parameter if the device is located on either side of the flow. Returns null if no corresponding device is found.

getApplications(): String

Retrieves all applications associated with the flow.

Properties

The Flow object properties and methods discussed in this section are available to every L7 trigger event associated with the flow.

By default, the ExtraHop system uses loosely-initiated protocol classification, so it will try to classify flows even after the connection was initiated. Loose initiation can be turned off for ports that do not always carry the protocol traffic (for example, the wildcard port 0). For such flows, device1, port1, and ipaddr1 represent the device with the numerically lower IP address and device2, port2, and ipaddr2 represent the device with the numerically higher IP address.

age: Number

The time elapsed since the flow was initiated, expressed in seconds.

bytes1: Number

The number of L4 payload bytes transmitted by one of two devices in the flow; the other device is represented by bytes2. The device represented by bytes1 remains consistent for the flow.

Access only on FLOW_TICK, FLOW_TURN, or FLOW_RECORD events; otherwise, an error will occur.

bytes2: Number

The number of L4 payload bytes transmitted by one of two devices in the flow; the other device is represented by bytes1. The device represented by bytes2 remains consistent for the flow.

Access only on FLOW_TICK, FLOW_TURN, or FLOW_RECORD events; otherwise, an error will occur.

customDevices1: Array

An array of custom Device objects on a flow. Custom devices on the other side of the flow are available by accessing customDevices2. The device represented by customDevices1 remains consistent for the flow.

customDevices2: Array

An array of custom Device objects on a flow. Custom devices on the other side of the flow are available by accessing customDevices1. The device represented by customDevices2 remains consistent for the flow.

device1: Device

The Device object associated with one of two devices in the flow; the other device is represented by device2. The device represented by device1 remains consistent for the flow. For example, Flow.device1.hwaddr accesses the MAC addresses of this device in the flow.

equals: Boolean

Performs an equality test between Device objects.

device2: Device

The Device object associated with one of two devices in the flow; the other device is represented by device1. The device represented by device2 remains consistent for the flow. For example, Flow.device2.hwaddr accesses the MAC addresses of this device in the flow.

equals: Boolean

Performs an equality test between Device objects.

dscp1: Number

The number representing the last Differentiated Services Code Point (DSCP) value transmitted by one of two devices in the flow; the other device is represented by dscp2. The device represented by dscp1 remains consistent for the flow.

dscp2: Number

The lnumber representing the last Differentiated Services Code Point (DSCP) value transmitted by one of two devices in the flow; the other device is represented by dscp1. The device represented by dscp2 remains consistent for the flow.

dscpBytes1: Array

An array that contains the number of L2 bytes for a specific Differentiated Services Code Point (DSCP) value transmitted by one of two devices in the flow; the other device is represented by dscpBytes2. The device represented by dscpBytes1 remains consistent for the flow.

The value is zero for each entry that has no bytes of the specific DSCP since the last FLOW_TICK event.

Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.

dscpBytes2: Array

An array that contains the number of L2 bytes for a specific Differentiated Services Code Point (DSCP) value transmitted by one of two devices in the flow; the other device is represented by dscpBytes1. The device represented by dscpBytes2 remains consistent for the flow.

The value is zero for each entry that has no bytes of the specific DSCP since the last FLOW_TICK event.

Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.

dcspName1: String

The name associated with the DSCP value transmitted by one of two devices in the flow; the other device is represented by dscpName2. The device represented by dscpName1 remains consistent for the flow.

See the dscpName property in the Endpoints section for a list of supported DSCP code names.

dcspName2: String

The name associated with the DSCP value transmitted by one of two devices in the flow; the other device is represented by dscpName1. The device represented by dscpName2 remains consistent for the flow.

See the dscpName property in the Endpoints section for a list of supported DSCP code names.

dscpPkts1: Array

An array that contains the number of L2 packets for a given Differentiated Services Code Point (DSCP) value transmitted by one of two devices in the flow; the other device is represented by dscpPkts2. The device represented by dscpPkts1 remains consistent for the flow.

The value is zero for each entry that has no packets of the specific DSCP since the last FLOW_TICK event.

Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.

dscpPkts2: Array

An array that contains the number of L2 packets for a given Differentiated Services Code Point (DSCP) value transmitted by one of two devices in the flow; the other device is represented by dscpPkts1. The device represented by dscpPkts2 remains consistent for the flow.

The value is zero for each entry that has no packets of the specific DSCP since the last FLOW_TICK event.

Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.

fragPkts1: Number

The number of packets resulting from IP fragmentation transmitted by one of two devices in the flow; the other device is represented by fragPkts2. The device represented by fragPkts1 remains consistent for the flow.

Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.

fragPkts2: Number

The number of packets resulting from IP fragmentation transmitted by one of two devices in the flow; the other device is represented by fragPkts1. The device represented by fragPkts2 remains consistent for the flow.

Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.

id: String

The unique identifier of a Flow record.

ipaddr: IPAddress

TheIPAddress object associated with a device in the flow. Specify the device role in the syntax—for example, Flow.client.ipaddr or Flow.receiver.ipaddr.

equals: Boolean

Performs an equality test between IPAddress objects.

ipproto: String

The IP protocol associated with the flow, such as TCP or UDP.

ipver: String

The IP version associated with the flow, such as IPv4 or IPv6.

isAborted: Boolean

The value is true if a TCP flow has been aborted through a TCP reset (RST). The flow can be aborted by a device. If applicable, specify the device role in the syntax—for example, Flow.client.isAborted or Flow.receiver.isAborted.

This condition may be detected in the TCP_CLOSE event and in any impacted L7 events (for example, HTTP_REQUEST or DB_RESPONSE).

Note:

An L4 abort occurs when a TCP connection is closed with a RST instead of a graceful shutdown. An L7 response abort occurs when a connection closes while in the middle of a response. This can be due to a RST, a graceful FIN shutdown, or an expiration. An L7 request abort occurs when a connection closes in the middle of a request. This can also be due to a RST, a graceful FIN shutdown, or an expiration.

isExpired: Boolean

The value is true if the flow expired at the time of the event.

isShutdown: Boolean

The value is true if the device initiated the shutdown of the TCP connection. Specify the device role in the syntax—for example, Flow.client.isShutdown or Flow.receiver.isShutdown.

l2Bytes1: Number

The number of L2 bytes, including the ethernet headers, transmitted by one of two devices in the flow; the other device is represented by l2Bytes2. The device represented by l2Bytes1 remains consistent for the flow.

Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.

l2Bytes2: Number

The number of L2 bytes, including the ethernet headers, transmitted by one of two devices in the flow; the other device is represented by l2Bytes1. The device represented by l2Bytes2 remains consistent for the flow.

Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.

l7proto: String

The L7 protocol associated with the flow. For known protocols, the property returns a string representing the protocol name, such as HTTP, DHCP, Memcache. For lesser-known protocols, the property returns a string formatted as ipproto:port—tcp:13724 or udp:11258 For custom protocol names, the property returns a string representing the name set through the Protocol Classification section in the Administration settings.

This property is not valid during TCP_OPEN events.

nagleDelay1: Number

The number of Nagle delays associated with one of two devices in the flow; the other device is represented by nagleDelay2. The device represented by nagleDelay1 remains consistent for the flow.

Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.

nagleDelay2: Number

The number of Nagle delays associated with one of two devices in the flow; the other device is represented by nagleDelay1. The device represented by nagleDelay2 remains consistent for the flow.

Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.

overlapFragPkts1: Number

The number of non-identical IP fragment packets transmitted by one of two devices in the flow; the other device is represented by overlapFragPkts2. The device represented by overlapFragPkts1 remains consistent for the flow.

Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.

overlapFragPkts2: Number

The number of non-identical IP fragment packets transmitted by one of two devices in the flow; the other device is represented by overlapFragPkts1. The device represented by overlapFragPkts2 remains consistent for the flow.

Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.

overlapSegments1: Number

The number of non-identical TCP segments where two or more segments contain data for the same part of the flow. The TCP segments are transmitted by one of two devices in the flow; the other device is represented by overlapSegments2. The device represented by overlapSegments1 remains consistent for the flow.

Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.

overlapSegments2: Number

The number of non-identical TCP segments where two or more segments contain data for the same part of the flow. The TCP segments are transmitted by one of two devices in the flow; the other device is represented by overlapSegments1. The device represented by overlapSegments2 remains consistent for the flow.

Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.

payload1: Buffer

The payload Buffer associated with one of two devices in the flow; the other device is represented by payload2. The device represented by payload1 remains consistent for the flow.

Access only on TCP_PAYLOAD, UDP_PAYLOAD, and SSL_PAYLOAD events; otherwise, an error will occur.

payload2: Buffer

The payload Buffer associated with one of two devices in the flow; the other device is represented by payload1. The device represented by payload2 remains consistent for the flow.

Access only on TCP_PAYLOAD, UDP_PAYLOAD, or SSL_PAYLOAD events; otherwise, an error will occur.

pkts1: Number

The number of packets transmitted by one of two devices in the flow; the other device is represented by pkts2. The device represented by pkts1 remains consistent for the flow.

Access only on FLOW_TICK, FLOW_TURN, or FLOW_RECORD events; otherwise, an error will occur.

pkts2: Number

The number of packets transmitted by one of two devices in the flow; the other device is represented by pkts1. The device represented by pkts2 remains consistent for the flow.

Access only on FLOW_TICK, FLOW_TURN, or FLOW_RECORD events; otherwise, an error will occur.

port1: Number

The port number associated with one of two devices in a flow; the other device is represented by port2. The device represented by port1 remains consistent for the flow.

port2: Number

The port number associated with one of two devices in a flow; the other device is represented by port1. The device represented by port2 remains consistent for the flow.

rcvWndThrottle1: Number

The number of receive window throttles sent from one of two devices in the flow; the other device is represented by rcvWndThrottle2. The device represented by rcvWndThrottle1 remains consistent for the flow.

Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.

rcvWndThrottle2: Number

The number of receive window throttles sent from one of two devices in the flow; the other device is represented by rcvWndThrottle1. The device represented by rcvWndThrottle2 remains consistent for the flow.

Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.

record1: Object

The record object that can be sent to the configured recordstore through a call to Flow.commitRecord1() on a FLOW_RECORD event.

The object represents traffic sent in a single direction from one of two devices in the flow; the other device is represented by the record2 property. The device represented by the record1 property remains consistent for the flow.

Access the record object only on FLOW_RECORD events; otherwise, an error will occur.

The default record object can contain the following properties:

• age
• bytes (L3)
• clientIsExternal
• dscpName
• first
• last
• pkts
• proto
• receiverAddr
• receiverIsExternal
• receiverPort
• roundTripTime

  The most recent round trip time (RTT) in this flow. An RTT is the time it took for a device to send a packet and receive an immediate acknowledgment (ACK).

• senderAddr
• senderIsExternal
• senderPort
• serverIsExternal
• tcpOrigin

  This record field is included only if the record represents traffic sent from a client or sender device.

• tcpFlags

record2: Object

The record object that can be sent to the configured recordstore through a call to Flow.commitRecord2() on a FLOW_RECORD event.

The object represents traffic sent in a single direction from one of two devices in the flow; the other device is represented by the record1 property. The device represented by the record2 property remains consistent for the flow.

Access the record object only on FLOW_RECORD events; otherwise, an error will occur.

The default record object can contain the following properties:

• age
• bytes (L3)
• clientIsExternal
• dscpName
• first
• last
• pkts
• proto
• receiverAddr
• receiverIsExternal
• receiverPort
• roundTripTime

  The most recent round trip time (RTT) in this flow. An RTT is the time it took for a device to send a packet and receive an immediate acknowledgment (ACK).

• senderAddr
• senderIsExternal
• senderPort
• serverIsExternal
• tcpOrigin

  This record field is included only if the record represents traffic sent from a client or sender device.

• tcpFlags

roundTripTime: Number

The median round trip time (RTT) for the duration of the event, expressed in milliseconds. The value is NaN if there are no RTT samples.

Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.

rto1: Number

The number of retransmission timeouts (RTOs) associated with one of two devices in the flow; the other device is represented by rto2. The device represented by rto1 remains consistent for the flow.

Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.

rto2: Number

The number of retransmission timeouts (RTOs) associated with one of two devices in the flow; the other device is represented by rto1. The device represented by rto2 remains consistent for the flow.

Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.

store: Object

The flow store is designed to pass objects from request to response on the same flow. The store object is an instance of an empty JavaScript object. Objects can be attached to the store as properties by defining the property key and property value. For example:

Flow.store.myobject = "myvalue";

Copy

For events that occur on the same flow, you can apply the flow store instead of the session table to share information. For example:

// request 
Flow.store.userAgent = HTTP.userAgent;  

// response 
var userAgent = Flow.store.userAgent;

Copy

Important:

Flow store values persist across all requests and responses carried on that flow. When working with the flow store, it is a best practice to set the flow store variable to null when its value should not be conveyed to the next request or response. This practice has the added benefit of conserving flow store memory.

Most flow store triggers should have a structure similar to the following example:

if (event === 'DB_REQUEST') {
                 if (DB.statement) {
                 Flow.store.stmt = DB.statement; 
} else {
                 Flow.store.stmt = null; 
} 
} 
else if (event === 'DB_RESPONSE') {
        var stmt = Flow.store.stmt;
        Flow.store.stmt = null;
        if (stmt) {
                 // Do something with 'stmt';   
                 // for example, commit a metric  
        } 
}

Copy

Note:

Because DHCP requests often occur on different flows than corresponding DHCP responses, we recommend that you combine DHCP request and response information by storing DHCP transaction IDs in the session table. For example, the following trigger code creates a metric that tracks how many DHCP discover messages received a corresponding DHCP offer message: if (event === 'DHCP_REQUEST'){ var opts = { expire: 30 }; Session.add(DHCP.txId.toString(), DHCP.msgType, opts); } else if (event === 'DHCP_RESPONSE'){ var reqMsgType = Session.lookup(DHCP.txId.toString()); if (reqMsgType && DHCP.msgType === 'DHCPOFFER') { Device.metricAddCount('dhcp-discover-offer', 1); } } Copy

tcpOrigin: IPAddress | Null

The original IP address of the client or sender if specified by a network proxy in TCP option 28.

vlan: Number

The VLAN number associated with the flow. If no VLAN tag is present, this value is set to 0.

vxlanVNI: Number

The VXLAN Network Identifier number associated with the flow. If no VXLAN tag is present, this value is set to NaN.

zeroWnd1: Number

The number of zero windows associated with one of two devices in the flow; the other device is represented by zeroWnd2. The device represented by zeroWnd1 remains consistent for the flow.

Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.

zeroWnd2: Number

The number of zero windows associated with one of two devices in the flow; the other device is represented by zeroWnd1. The device represented by zeroWnd2 remains consistent for the flow.

Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.

Trigger Examples

• Example: Monitor CIFS actions on devices
• Example: Track 500-level HTTP responses by customer ID and URI
• Example: Parse custom PoS messages with universal payload analysis
• Example: Parse syslog over TCP with universal payload analysis
• Example: Parse NTP with universal payload analysis
• Example: Track SOAP requests

Methods

FlowInterface(id: string)

A constructor for the FlowInterface object that accepts a flow interface ID. An error occurs if the flow interface ID does not exist on the ExtraHop system.

Instance methods

The methods in this section enable you to create custom metrics on a flow interface. The methods are present only on instances of the NetFlow class. For example, the following statement collects metrics from NetFlow traffic on the ingress interface:

NetFlow.ingressInterface.metricAddCount("slow_rsp", 1);

However, you can call the FlowInterface method as a static method on NETFLOW_RECORD events. For example, the following statement collects metrics from NetFlow traffic on both the ingress and egress interfaces:

FlowInterface.metricAddCount("slow_rsp", 1);

metricAddCount(metric_name: String, count: Number, options: Object):void

Creates a custom top-level count metric. Commits the metric data to the specified flow interface.

metric_name: String

The name of the top-level count metric.

count: Number

The increment value. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following property:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailCount(metric_name: String, key: String | IPAddress, count: Number, options: Object):void

Creates a custom detail count metric by which you can drill down. Commits the metric data to the specified flow interface.

metric_name: String

The name of the detail count metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

count: Number

The increment value. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following property:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDataset(metric_name: String, val: Number, options: Object):void

Creates a custom top-level dataset metric. Commits the metric data to the specified flow interface.

metric_name: String

The name of the top-level dataset metric.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

freq: Number

An option that enables you to simultaneously record multiple occurrences of particular values in the dataset when set to the number of occurrences specified by the val parameter. If no value is specified, the default value is 1.

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailDataset(metric_name: String, key: String | IPAddress, val: Number, options: Object):void

Creates a custom detail dataset metric by which you can drill down. Commits the metric data to the specified flow interface.

metric_name: String

The name of the detail count metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

freq: Number

An option that enables you to simultaneously record multiple occurrences of particular values in the dataset when set to the number of occurrences specified by the val parameter. If no value is specified, the default value is 1.

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDistinct(metric_name: String, item: Number | String | IPAddress:void

Creates a custom top-level distinct count metric. Commits the metric data to the specified flow interface.

metric_name: String

The name of the top-level distinct count metric.

item: Number | String | IPAddress

The value to be placed into the set. The value is converted to a string before it is placed in the set.

metricAddDetailDistinct(metric_name: String, key: String | IPAddress, item: Number | String | IPAddress:void

Creates a custom detail distinct count metric by which you can drill down. Commits the metric data to the specified flow interface.

metric_name: String

The name of the detail distinct count metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

item: Number | String | IPAddress

The value to be placed into the set. The value is converted to a string before it is placed in the set.

metricAddMax(metric_name: String, val: Number, options: Object):void

Creates a custom top-level maximum metric. Commits the metric data to the specified flow interface.

metric_name: String

The name of the top-level maximum metric.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailMax(metric_name: String, key: String | IPAddress, val: Number, options: Object):void

Creates a custom detail maximum metric by which you can drill down. Commits the metric data to the specified flow interface.

metric_name: String

The name of the detail maximum metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddSampleset(metric_name: String, val: Number, options: Object):void

Creates a custom top-level sampleset metric. Commits the metric data to the specified flow interface.

metric_name: String

The name of the top-level sampleset metric.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailSampleset(metric_name: String, key: String | IPAddress, val: Number, options: Object):void

Creates a custom detail sampleset metric by which you can drill down. Commits the metric data to the specified flow interface.

metric_name: String

The name of the detail sampleset metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddSnap(metric_name: String, count: Number, options: Object):void

Creates a custom top-level snapshot metric. Commits the metric data to the specified flow interface.

metric_name: String

The name of the top-level snapshot metric.

count: Number

The observed value, such as current established connections. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailSnap(metric_name: String, key: String | IPAddress, count: Number, options: Object):void

Creates a custom detail snapshot metric by which you can drill down. Commits the metric data to the specified flow interface.

metric_name: String

The name of the detail sampleset metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

count: Number

The observed value, such as current established connections. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

Instance properties

id: String

A string that uniquely identifies the flow interface.

number: Number

The flow interface number reported by the NetFlow record.

Methods

FlowNetwork(id: string)

A constructor for the FlowNetwork object that accepts a flow network ID. An error occurs if the flow network ID does not exist on the ExtraHop system.

Instance methods

The methods in this section enable you to create custom metrics on a flow network. The methods are present only on instances of the NetFlow class. For example, the following statement collects metrics from NetFlow traffic on an individual network:

NetFlow.network.metricAddCount("slow_rsp", 1);

However, you can call the FlowNetwork method as a static method on NETFLOW_RECORD events. For example, the following statement collects metrics from NetFlow traffic on both devices on the flow network:

FlowNetwork.metricAddCount("slow_rsp", 1);

metricAddCount(metric_name: String, count: Number, options: Object):void

Creates a custom top-level count metric. Commits the metric data to the specified flow network.

metric_name: String

The name of the top-level count metric.

count: Number

The increment value. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following property:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailCount(metric_name: String, key: String | IPAddress, count: Number, options: Object):void

Creates a custom detail count metric by which you can drill down. Commits the metric data to the specified flow network.

metric_name: String

The name of the detail count metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

count: Number

The increment value. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following property:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDataset(metric_name: String, val: Number, options: Object):void

Creates a custom top-level dataset metric. Commits the metric data to the specified flow network.

metric_name: String

The name of the top-level dataset metric.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

freq: Number

An option that enables you to simultaneously record multiple occurrences of particular values in the dataset when set to the number of occurrences specified by the val parameter. If no value is specified, the default value is 1.

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailDataset(metric_name: String, key: String | IPAddress, val: Number, options: Object):void

Creates a custom detail dataset metric by which you can drill down. Commits the metric data to the specified flow network.

metric_name: String

The name of the detail count metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

freq: Number

An option that enables you to simultaneously record multiple occurrences of particular values in the dataset when set to the number of occurrences specified by the val parameter. If no value is specified, the default value is 1.

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDistinct(metric_name: String, item: Number | String | IPAddress:void

Creates a custom top-level distinct count metric. Commits the metric data to the specified flow network.

metric_name: String

The name of the top-level distinct count metric.

item: Number | String | IPAddress

The value to be placed into the set. The value is converted to a string before it is placed in the set.

metricAddDetailDistinct(metric_name: String, key: String | IPAddress, item: Number | String | IPAddress:void

Creates a custom detail distinct count metric by which you can drill down. Commits the metric data to the specified flow network.

metric_name: String

The name of the detail distinct count metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

item: Number | String | IPAddress

The value to be placed into the set. The value is converted to a string before it is placed in the set.

metricAddMax(metric_name: String, val: Number, options: Object):void

Creates a custom top-level maximum metric. Commits the metric data to the specified flow network.

metric_name: String

The name of the top-level maximum metric.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailMax(metric_name: String, key: String | IPAddress, val: Number, options: Object):void

Creates a custom detail maximum metric by which you can drill down. Commits the metric data to the specified flow network.

metric_name: String

The name of the detail maximum metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddSampleset(metric_name: String, val: Number, options: Object):void

Creates a custom top-level sampleset metric. Commits the metric data to the specified flow network.

metric_name: String

The name of the top-level sampleset metric.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailSampleset(metric_name: String, key: String | IPAddress, val: Number, options: Object):void

Creates a custom detail sampleset metric by which you can drill down. Commits the metric data to the specified flow network.

metric_name: String

The name of the detail sampleset metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddSnap(metric_name: String, count: Number, options: Object):void

Creates a custom top-level snapshot metric. Commits the metric data to the specified flow network.

metric_name: String

The name of the top-level snapshot metric.

count: Number

The observed value, such as current established connections. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailSnap(metric_name: String, key: String | IPAddress, count: Number, options: Object):void

Creates a custom detail snapshot metric by which you can drill down. Commits the metric data to the specified flow network.

metric_name: String

The name of the detail sampleset metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

count: Number

The observed value, such as current established connections. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

Instance properties

id: String

A string that uniquely identifies the flow network.

ipaddr: IPAddress

The IP address of the management interface on the flow network.

Methods

Values returned by GeoIP methods are obtained from the MaxMind GeoLite2 Country database or the MaxMind GeoLite2 City database unless configured otherwise by the Geomap Data Source settings in the Administration settings.

From the Geomap Data Source settings, you can upload custom databases and specify which database to reference by default for city or country lookups.

We recommend uploading only a custom city-level database if you intend to call both GeoIP.getCountry() and GeoIP.getPreciseLocation() methods in triggers. If both types of custom databases are uploaded, the ExtraHop system retrieves values for both methods from the city-level database and ignores the country-level database, which is considered to be a subset of the city-level database.

getCountry(ipaddr: IPAddress): Object

Returns country-level detail for the specified IPAddress in an object that contains the following fields:

continentName: String

The name of the continent, such as Europe, that is associated with the country from which the specified IP address originates. The value is the same as the continentName field returned by the getPreciseLocation() method.

continentCode: Number

The code of the continent, such as EU, that is associated with the value of the countryCode field, according to ISO 3166. The value is the same as the continentCode field returned by the getPreciseLocation() method.

countryName: String

The name of the country from which the specified IP address originates, such as United States. The value is the same as the countryName field returned by the getPreciseLocation() method.

countryCode: String

The code associated with the country, according to ISO 3166, such as US. The value is the same as the countryCode field returned by the getPreciseLocation() method.

Returns null in any field for which no data is available, or returns a null object if all field data is unavailable.

Note:

The getCountry() method requires 20 MB of total RAM on the ExtraHop system, which might affect system performance. The first time this method is called in any trigger, the ExtraHop system reserves the required amount of RAM unless the getPreciseLocation() method has already been called. The getPreciseLocation() method requires 100 MB of RAM, so adequate RAM will already be available to call the getCountry() method. The required amount of RAM is not per trigger or per method call; the ExtraHop system only reserves the required amount of RAM one time.

In the following code example, the getCountry() method is called on each specified event and retrieves rough location data for each client IP address:

// ignore if the IP address is non-routable
if (Flow.client.ipaddr.isRFC1918) return;
var results=GeoIP.getCountry(Flow.client.ipaddr);
if (results) {
    countryCode=results.countryCode;
    // log the 2-letter country code of each IP address 
    debug ("Country Code is " + results.countryCode);
}

Copy

getPreciseLocation(ipaddr: IPAddress): Object

Returns city-level detail for the specified IPAddress in an object that contains the following fields:

continentName: String

The name of the continent, such as Europe, that is associated with the country from which the specified IP address originates. The value is the same as the continentName field returned by the getCountry() method.

continentCode: Number

The code of the continent, such as EU, that is associated with the value of the countryCode field, according to ISO 3166. The value is the same as the continentCode field returned by the getCountry() method.

countryName: String

The name of the country from which the specified IP address originates, such as United States. The value is the same as the countryName field returned by the getCountry() method.

countryCode: String

The code associated with the country, according to ISO 3166, such as US. The value is the same as the countryCode field returned by the getCountry() method.

region: String

The region, such as a state or province, such as Washington.

city: String

The city from which the IP address originates, such as Seattle.

latitude: Number

The latitude of the IP address location.

longitude: Number

The longitude of the of the IP address location.

radius: Number

The radius, expressed in kilometers, around the longitude and latitude coordinates of the IP address location.

Returns null in any field for which no data is available, or returns a null object if all field data is unavailable.

Note:

The getPreciseLocation() method requires 100 MB of total RAM on the ExtraHop system, which might affect system performance. The first time this method is called in any trigger, the ExtraHop system reserves the required amount of RAM unless the getCountry() method has already been called. The getCountry() method requires 20 MB of RAM, so the ExtraHop system reserves an additional 80 MB of RAM. The required amount of RAM is not per trigger or per method call; the ExtraHop system only reserves the required amount of RAM one time.

Methods

IPAddress(ip: String | Number, mask: Number)

Constructor for the IPAddress class that takes two parameters:

ip: String

The IP address string in CIDR format.

mask: Number

The optional subnet mask in a numerical format, representing the number of leftmost '1' bits in the mask (optional).

Instance methods

equals(equals: IPAddress): Boolean

Performs an equality test between IPAddress objects as shown in the following example:

if (Flow.client.ipaddr.toString() === "10.10.10.10")
{ // perform a task }

Copy

mask(mask: Number): IPAddress

Sets the subnet mask of the IPAddress object as shown in the following example:

if ((Flow.ipaddr1.mask(24).toString() === "173.194.33.0")||
(Flow.ipaddr2.mask(24).toString() === "173.194.33.0"))
{Flow.setApplication("My L4 App");}

Copy

The mask parameter specifies the subnet mask in a numerical format, representing the number of leftmost '1' bits in the mask (optional).

toJSON(): String

Converts the IPAddress object to JSON format.

toString(): String

Converts the IPAddress object to a printable string.

Properties

hostNames: Array of Strings

An array of hostnames associated with the IPAddress.

isBroadcast: Boolean

The value is true if the IP address is a broadcast address.

isExternal: Boolean

The value is true if the IP address is external to your network.

isLinkLocal: Boolean

The value is true if the IP address is a link local address such as (169.254.0.0/16).

isMulticast: Boolean

The value is true if the IP address is a multicast address.

isRFC1918: Boolean

The value is true if the IP address belongs to one of the RFC1918 private IP ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16). The value is always false for IPv6 addresses.

isV4: Boolean

The value is true if the IP address is an IPv4 address.

isV6: Boolean

The value is true if the IP address is an IPv6 address.

localityName: String | null

The name of the network locality that the IP address is in. If the IP address is not in any network locality, the value is null.

Methods

metricAddCount(metric_name: String, count: Number, options: Object):void

Creates a custom top-level count metric. Commits the metric data to the specified network.

metric_name: String

The name of the top-level count metric.

count: Number

The increment value. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following property:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailCount(metric_name: String, key: String | IPAddress, count: Number, options: Object):void

Creates a custom detail count metric by which you can drill down. Commits the metric data to the specified network.

metric_name: String

The name of the detail count metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

count: Number

The increment value. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following property:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDataset(metric_name: String, val: Number, options: Object):void

Creates a custom top-level dataset metric. Commits the metric data to the specified network.

metric_name: String

The name of the top-level dataset metric.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

freq: Number

An option that enables you to simultaneously record multiple occurrences of particular values in the dataset when set to the number of occurrences specified by the val parameter. If no value is specified, the default value is 1.

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailDataset(metric_name: String, key: String | IPAddress, val: Number, options: Object):void

Creates a custom detail dataset metric by which you can drill down. Commits the metric data to the specified network.

metric_name: String

The name of the detail count metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

freq: Number

An option that enables you to simultaneously record multiple occurrences of particular values in the dataset when set to the number of occurrences specified by the val parameter. If no value is specified, the default value is 1.

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDistinct(metric_name: String, item: Number | String | IPAddress:void

Creates a custom top-level distinct count metric. Commits the metric data to the specified network.

metric_name: String

The name of the top-level distinct count metric.

item: Number | String | IPAddress

The value to be placed into the set. The value is converted to a string before it is placed in the set.

metricAddDetailDistinct (metric_name: String, key: String | IPAddress, item: Number | String | IPAddress:void

Creates a custom detail distinct count metric by which you can drill down. Commits the metric data to the specified network.

metric_name: String

The name of the detail distinct count metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

item: Number | String | IPAddress

The value to be placed into the set. The value is converted to a string before it is placed in the set.

metricAddMax(metric_name: String, val: Number, options: Object):void

Creates a custom top-level maximum metric. Commits the metric data to the specified network.

metric_name: String

The name of the top-level maximum metric.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailMax(metric_name: String, key: String | IPAddress, val: Number, options: Object):void

Creates a custom detail maximum metric by which you can drill down. Commits the metric data to the specified network.

metric_name: String

The name of the detail maximum metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddSampleset(metric_name: String, val: Number, options: Object):void

Creates a custom top-level sampleset metric. Commits the metric data to the specified network.

metric_name: String

The name of the top-level sampleset metric.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailSampleset(metric_name: String, key: String | IPAddress, val: Number, options: Object):void

Creates a custom detail sampleset metric by which you can drill down. Commits the metric data to the specified network.

metric_name: String

The name of the detail sampleset metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

val: Number

The observed value, such as a processing time. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddSnap(metric_name: String, count: Number, options: Object):void

Creates a custom top-level snapshot metric. Commits the metric data to the specified network.

metric_name: String

The name of the top-level snapshot metric.

count: Number

The observed value, such as current established connections. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

metricAddDetailSnap(metric_name: String, key: String | IPAddress, count: Number, options: Object):void

Creates a custom detail snapshot metric by which you can drill down. Commits the metric data to the specified network.

metric_name: String

The name of the detail sampleset metric.

key: String | IPAddress

The key specified for the detail metric. A null value is silently discarded.

count: Number

The observed value, such as current established connections. Must be a non-zero, positive signed 64-bit integer. A NaN value is silently discarded.

options: Object

An optional object that can contain the following properties:

highPrecision: Boolean

A flag that enables one-second granularity for the custom metric when set to true.

Trigger Examples

• Example: Parse syslog over TCP with universal payload analysis
• Example: Record data to a session table
• Example: Track SOAP requests

Here are some important things to know about session tables:

• The session table supports ordinary JavaScript values, enabling you to add JS objects to the table.
• Session table entries can be evicted when the table grows too large or when the configured expiration is reached.
• Because the session table on a sensor is not shared with the console, the values in the session table are not shared with other connected sensors.
• The ExtraHop Open Data Context API exposes the session table via the management network, enabling coordination with external processes through the memcache protocol.

Events

The Session class is not limited only to the SESSION_EXPIRE event. You can apply the Session class to any ExtraHop event.

SESSION_EXPIRE

Runs periodically (in approximately 30 second increments) as long as the session table is in use. When the SESSION_EXPIRE event fires, keys that have expired in the previous 30 second interval are available through the Session.expiredKeys property.

The SESSION_EXPIRE event is not associated with any particular flow, so triggers on SESSION_EXPIRE events cannot commit device metrics through Device.metricAdd*() methods or Flow.client.device.metricAdd*() methods. To commit device metrics on this event, you must add Device objects to the session table through the Device() instance method.

Note:

You cannot assign triggers that run only on this event to specific devices or device groups. Triggers that run on this event will run whenever this event occurs.

TIMER_30SEC

Runs exactly every 30 seconds. This event enables you to perform periodic processing, such as regularly accessing session table entries added through the Open Data Context API.

Note:

You can apply any trigger class to the TIMER_30SEC event.

Note:

You cannot assign triggers that run only on this event to specific devices or device groups. Triggers that run on this event will run whenever this event occurs.

Methods

add(key: String, value*, options: Object): *

Adds the specified key in the session table. If the key is present, the corresponding value is returned without modifying the key entry in the table. If the key is not present, a new entry is created for the key and value, and the new value is returned.

You can configure an optional Options object for the specified key.

getOptions(key: String): Object

Returns the Options object for the specified key. You configure options during calls to Session.add(), Session.modify(), or Session.replace().

increment(key: String, count: Number): Number | null

Looks up the specified key and increments the key value by the specified number. The default value of the optional count parameter is 1. Returns the new key value if the call is successful. Returns null if the lookup fails. Returns an error if the key value is not a number.

lookup(key: String): *

Looks up the specified key in the session table and returns the corresponding value. Returns null if the key is not present.

modify(key: String, value: *, options: Object): *

Modifies the specified key value, if the key is present in the session table, and returns the previous value. If the key is not present, no new entry is created.

If changes to the optional Options object are included, the key options are updated. and old options are merged with new ones. If the expire option is modified, the expiration timer is reset.

remove(key: String): *

Removes the entry for the given key and returns the associated value.

replace(key: String, value: *, options: Object): *

Updates the entry associated with the given key. If the key is present, update the value and return the previous value. If the key is not present, add the entry and return the previous value (null).

If changes to the optional Options object are included, the key options are updated, and old options are merged with new ones. If the expire option is provided, the expiration timer is reset.

Constants

PRIORITY_LOW: Number

The numeric representation of the lowest priority level. The value is 0. Priority levels determine the order that entries are removed from the session table if the table grows too large.

PRIORITY_NORMAL: Number

The numeric representation of the default priority level. The value is 1. Priority levels determine the order that entries are removed from the session table if the table grows too large.

PRIORITY_HIGH: Number

The numeric representation of the highest priority level. The value is 2. Priority levels determine the order that entries are removed from the session table if the table grows too large.

Properties

expiredKeys: Array

An array of objects with the following properties:

age: Number

The age of the expired object, expressed in milliseconds. Age is the amount of time elapsed between when the object in the session table was added or the expire option of the object was modified, and the SESSION_EXPIRE event. The age determines whether the key was evicted or expired.

name: String

The key of the expired object.

value: Number | String | IPAddress | Boolean | Device

The value of the entry in the session table.

Expired keys include keys that were evicted because the table grew too large.

The expiredKeys property can be accessed only on SESSION_EXPIRE events; otherwise, an error will occur.

Trigger Examples

• Example: Record data to a session table

Properties

uuid: String

The universally unique identifier (UUID) of the sensor or console.

ipaddr: IPAddress

The IPAddress object of the primary management interface (Interface 1) on the sensor.

hostname: String

The hostname for the sensor or console configured in the Administration settings.

version: String

The firmware version running on the sensor or console.

Methods

hasIP(address: IPAddress): boolean

The value is true if the threats have been found for the specified IP address. If no intelligence information is available on the ExtraHop system, the value is null.

hasDomain(domain: String): boolean

The value is true if the threats have been found for the specified domain. If no intelligence information is available on the ExtraHop system, the value is null.

hasURI(uri: String): boolean

The value is true if the threats have been found for the specified URI. If no intelligence information is available on the ExtraHop system, the value is null.

Properties

isAvailable: boolean

The value is true if threat intelligence information is available on the ExtraHop system.

Properties

isDebugEnabled: boolean

The value is true if debugging is enabled for the trigger. The value is determined by the state of the Enable debug log checkbox in the Edit Trigger pane in the ExtraHop system.

Instance properties

id: Number

The numerical ID for a VLAN.

Events

AAA_REQUEST

Runs when the ExtraHop system finishes processing an AAA request .

AAA_RESPONSE

Runs on every AAA response processed by the device.

Methods

commitRecord(): void

Sends a record to the configured recordstore on either an AAA_REQUEST or AAA_RESPONSE event.

The event determines which properties are committed to the record object. To view the default properties committed on each event, see the record property below.

For built-in records, each unique record is committed only once, even if the commitRecord() method is called multiple times for the same unique record.

Properties

authenticator: String

The value of the authenticator field (RADIUS only).

avps: Array

An array of AVP objects with the following properties:

avpLength: Number

The size of the AVP, expressed in bytes. This value includes the AVP header data, as well as the value.

id: Number

The numeric ID of the attribute represented as an integer.

isGrouped: Boolean

The value is true if this is a grouped AVP (Diameter only).

name: String

The name for the given AVP.

vendor: String

The vendor name for vendor AVPs (Diameter only).

value: String | Array | Number

For single AVPs, a string or numeric value. For grouped AVPs (Diameter only), an array of objects.

isDiameter: Boolean

The value is true if the request or response is Diameter.

isError: Boolean

The value is true if the response is an error. To retrieve the error details in Diameter, check AAA.statusCode. To retrieve the error details in RADIUS, check the AVP with code 18 (Reply-Message).

Access only on AAA_RESPONSE events; otherwise, an error will occur.

isRadius: Boolean

The value is true if the request or response is RADIUS.

isRspAborted: Boolean

The value is true if the AAA_RESPONSE event is aborted.

Access only on AAA_RESPONSE events; otherwise, an error will occur.

method: Number

The method that corresponds to the command code in either RADIUS or Diameter.

The following table contains valid Diameter command codes:

Command name	Abbr.	Code
AA-Request	AAR	265
AA-Answer	AAA	265
Diameter-EAP-Request	DER	268
Diameter-EAP-Answer	DEA	268
Abort-Session-Request	ASR	274
Abort-Session-Answer	ASA	274
Accounting-Request	ACR	271
Credit-Control-Request	CCR	272
Credit-Control-Answer	CCA	272
Capabilities-Exchange-Request	CER	257
Capabilities-Exchange-Answer	CEA	257
Device-Watchdog-Request	DWR	280
Device-Watchdog-Answer	DWA	280
Disconnect-Peer-Request	DPR	282
Disconnect-Peer-Answer	DPA	282
Re-Auth-Answer	RAA	258
Re-Auth-Request	RAR	258
Session-Termination-Request	STR	275
Session-Termination-Answer	STA	275
User-Authorization-Request	UAR	300
User-Authorization-Answer	UAA	300
Server-Assignment-Request	SAR	301
Server-Assignment-Answer	SAA	301
Location-Info-Request	LIR	302
Location-Info-Answer	LIA	302
Multimedia-Auth-Request	MAR	303
Multimedia-Auth-Answer	MAA	303
Registration-Termination-Request	RTR	304
Registration-Termination-Answer	RTA	304
Push-Profile-Request	PPR	305
Push-Profile-Answer	PPA	305
User-Data-Request	UDR	306
User-Data-Answer	UDA	306
Profile-Update-Request	PUR	307
Profile-Update-Answer	PUA	307
Subscribe-Notifications-Request	SNR	308
Subscribe-Notifications-Answer	SNA	308
Push-Notification-Request	PNR	309
Push-Notification-Answer	PNA	309
Bootstrapping-Info-Request	BIR	310
Bootstrapping-Info-Answer	BIA	310
Message-Process-Request	MPR	311
Message-Process-Answer	MPA	311
Update-Location-Request	ULR	316
Update-Location-Answer	ULA	316
Authentication-Information-Request	AIR	318
Authentication-Information-Answer	AIA	318
Notify-Request	NR	323
Notify-Answer	NA	323

The following table contains valid RADIUS command codes:

Command name	Code
Access-Request	1
Access-Accept	2
Access-Reject	3
Accounting-Request	4
Accounting-Response	5
Access-Challenge	11
Status-Server (experimental)	12
Status-Client (experimental)	13
Reserved	255

processingTime: Number

The server processing time, expressed in milliseconds. The value is NaN if the timing is invalid.

Access only on AAA_RESPONSE events; otherwise, an error will occur.

record: Object

The record object that can be sent to the configured recordstore through a call to AAA.commitRecord() on either an AAA_REQUEST or AAA_RESPONSE event.

The event on which the method was called determines which properties the default record object can contain as displayed in the following table:

AAA_REQUEST	AAA_RESPONSE
authenticator	authenticator
clientIsExternal	clientIsExternal
clientZeroWnd	clientZeroWnd
method	isError
receiverIsExternal	isRspAborted
reqBytes	method
reqL2Bytes	processingTime
reqPkts	receiverIsExternal
reqRTO	roundTripTime
senderIsExternal	rspBytes
serverIsExternal	rspL2Bytes
serverZeroWnd	rspPkts
txId	rspRTO
	statusCode
	senderIsExternal
	serverIsExternal
	serverZeroWnd
	txId

reqBytes: Number

The number of L4 request bytes, excluding L4 headers.

reqL2Bytes: Number

The number of L2 request bytes, including L2 headers.

reqPkts: Number

The number of request packets.

reqRTO: Number

The number of request retransmission timeouts (RTOs).

Access only on AAA_REQUEST events; otherwise, an error will occur.

reqZeroWnd: Number

The number of zero windows in the request.

roundTripTime: Number

The median round trip time (RTT), expressed in milliseconds. The value is NaN if there are no RTT samples.

rspBytes: Number

The number of L4 response bytes, excluding L4 protocol overhead, such as ACKs, headers, and retransmissions.

rspL2Bytes: Number

The number of L2 response bytes, including protocol overhead, such as headers.

rspPkts: Number

The number of response packets.

rspRTO: Number

The number of response retransmission timeouts (RTOs).

Access only on AAA_RESPONSE events; otherwise, an error will occur.

rspZeroWnd: Number

The number of zero windows in the response.

statusCode: String

A string representation of the AVP identifier 268 (Result-Code).

Access only on AAA_RESPONSE events; otherwise, an error will occur.

txId: Number

A value that corresponds to the hop-by-hop identifier in Diameter and msg-id in RADIUS.