Trigger API Reference
Overview
Application Inspection triggers are composed of user-defined code that automatically executes on system events through the ExtraHop trigger API. By writing triggers, you can collect custom metric data about the activities on your network. In addition, triggers can perform operations on protocol messages (such as an HTTP request) before the packet is discarded.
The ExtraHop system monitors, extracts, and records a core set of Layer 7 (L7) metrics for devices on the network, such as response counts, error counts, and processing times. After these metrics are recorded for a given L7 protocol, the packets are discarded, freeing resources for continued processing.
Triggers enable you to:
- Generate and store custom metrics to the internal datastore of the ExtraHop system. For example, while the ExtraHop system does not collect information about which user agent generated an HTTP request, you can generate and collect that level of detail by writing a trigger and committing the data to the datastore. You can also view custom data that is stored in the datastore by creating custom metrics pages and displaying those metrics through the Metric Explorer and dashboards.
- Generate and send records for long-term storage and retrieval to a recordstore.
- Create a user-defined application that collects metrics across multiple types of network traffic to capture information with cross-tier impact. For example, to gain a unified view of all the network traffic associated with a website—from web transactions to DNS requests and responses to database transactions—you can create an application that contains all of these website-related metrics.
- Generate custom metrics and send the information to syslog consumers such as Splunk, or to third party databases such as MongoDB or Kafka.
- Initiate a packet capture to record individual flows based on user-specified criteria. You can download captured flows and process them through third-party tools. Your ExtraHop system must be licensed for packet capture to access this feature.
The purpose of this guide is to provide reference material when writing the blocks of JavaScript code that run when trigger conditions are met. The Trigger API resources section contains a list of topics that provide a comprehensive overview of trigger concepts and procedures.
Trigger API resources
This section contains a list of topics that will help familiarize you with trigger concepts, building a trigger, and best practices.
- Triggers
- Build a trigger
- Monitor trigger performance
- Triggers Best Practices Guide
- Triggers FAQ
- Walkthrough: Build a trigger to collect custom metrics for HTTP 404 errors
- Walkthrough: Initiate precision packet captures to analyze zero window conditions
- Walkthrough: Build a trigger to monitor responses to NTP monlist requests
Data types for custom metrics
The ExtraHop Trigger API enables you to create custom metrics that collect data about your environment, beyond what is provided by built-in protocol metrics.
You can create custom metrics of the following data types:
- count
-
The number of metric events that occurred over a specific time range. For example, to record information about the number of HTTP requests over time, select a top-level count metric. You could also select a detail count metric to record information about the number of times clients accessed a server, with the IPAddress key and an integer representing the number of accesses as a value.
- snapshot
- A special type of count metric that, when queried over time, returns the most recent value (such as TCP established connections).
- distinct
- The estimated number of unique items observed over time, such as the number of unique ports that received SYN packets, where a high number might indicate port scanning.
- dataset
- A statistical summary of timing information, such as 5-number summary: min, 25th-percentile, median, 75th-percentile, max. For example, to record information about HTTP processing time over time, select a top-level dataset metric.
- sampleset
- A statistical summary of timing information, such as mean and standard deviation. For example, to record information about the length of time it took the server to process each URI, select a detail sampleset with the URI string key and an integer representing processing time as a value.
- max
- A special type of count metric that preserves the maximum. For example, to record the slowest HTTP statements over time without relying on a session table, select a top-level and a detail max metric.
Custom metrics are supported for the following source types:
For more information about the differences between top-level and detail metrics, see the Metrics FAQ.
Global functions
Global functions can be called on any event.
- cache (key: String, valueFn: () => Any): Any
- Caches the specified parameters in a table to enable efficient lookup and return of
large data sets.
- key: String
- An identifier that indicates the location of the cached value. A key must be unique within a trigger.
- valueFn: () => Any
- A zero-argument function that returns a non-null value.
In the following example, the cache method is called with large amounts of data hard-coded into the trigger script:
let storeLookup = cache("storesByNumber", () => ({ 1 : "Newark", 2 : "Paul", 3 : "Newark", 4 : "St Paul"// 620 lines omitted })); var storeCity; var query = HTTP.parseQuery(HTTP.query); if (query.storeCode) { storeCity = storeLookup[parseInt(query.storeCode)]; }
In the following example, a list of known user agents in a JBoss trigger is normalized before it is compared with the observed user agent. The trigger converts the list to lowercase and trims excess whitespace, and then caches the entries.
function jbossUserAgents() { return [ // Add your own user agents here, followed by a comma "Gecko-like (Edge 14.0; Windows 10; Silverlight or similar)", "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.79 Safari/537.36", "Mozilla/5.0 (Android)" ].map(ua => ua.trim().toLowerCase()); } var badUserAgents = cache("badUserAgents", jbossUserAgents);
- commitDetection (type: String, options: Object)
- Generates a detection on the ExtraHop system.
- type: String
- A user-defined type for the definition, such as brute_force_attack. You can tune detections to hide multiple detections with the same type. The string can only contain letters, numbers, and underscores.
- options: Object
- An object that specifies the following properties for the detection:
- title: String
- A user-defined title that identifies the detection.
- description: String
- A description of the detection.
- riskScore: Number | null
- An optional number between 1 and 99 that represents the risk score of the detection.
- participants: Array of Objects
- An optional array of participant objects associated with the detection. A
participant object must contain the following properties:
- object: Object
- The Device, Application, or IP address object associated with the participant.
- role: String
- The role of the participant in the detection. The following values
are valid:
- offender
- victim
- identityKey: String | null
- A unique identifier that enables ongoing detections. If multiple
detections with the same identity key and detection type are generated
within the time period specified by the identityTtl
property, the detections are consolidated into a single ongoing
detection.
Note: If the ExtraHop system is generating a large number of detections with unique identity keys, the system might fail to consolidate some ongoing detections. However, the system will not generate more than 250 individual detections for a trigger in a day. - identityTtl: String
- The amount of time after a detection is generated that duplicate
detections are consolidated into an ongoing detection.
After a detection is generated, if another detection with the same identity key and detection type is generated within the specified time period, the two detections are consolidated into a single ongoing detection. Each time a detection is consolidated into an ongoing detection, the time period is reset, and the detection does not end until the time period expires. For example, if identityTtl is set to day, and four duplicate detections are each generated 12 hours apart, the ongoing detection spans three days. The following time periods are valid:
- hour
- day
- week
The default time period is hour.
- commitRecord (id: String, record: Object): void
- Sends a custom record object to the configured recordstore.
- id: String
- The ID of the record type to be created. The ID cannot begin with a tilde (~).
- record: Object
- An object containing a list of property and value pairs to be sent to the
configured recordstore as a custom record.
The following properties are automatically added to records and are not represented on the objects returned by the built-in record accessors, such as HTTP.record:
- ex
- flowID
- client
- clientAddr
- clientPort
- receiver
- receiverAddr
- receiverPort
- sender
- senderAddr
- senderPort
- server
- serverAddr
- serverPort
- timestamp
- vlan
For example, to access the flowID property in an HTTP record, you would include HTTP.record.Flow.id in your statement.
Important: To avoid unexpected data in the record or an exception when the method is called, the property names listed above cannot be specified as a property name in custom records. In addition, a property name in custom records cannot contain any of the following characters:
- .
- Period
- :
- Colon
- [
- Square bracket
- ]
- Square bracket
In the following example, the two property and value pairs that have been added to the record variable are committed to a custom record by the commitRecord function:
var record = { 'field1': myfield1, 'field2': myfield2 }; commitRecord('record_type_id', record);
On most events, you can commit a built-in record that contains default properties. For example, a built-in record such as the HTTP.record object can be the basis for a custom record.
The following example code commits a custom record that includes all of the built-in metrics from the HTTP.record object and an additional metric from the HTTP.headers property:
var record = Object.assign( {'server': HTTP.headers.server}, HTTP.record ); commitRecord('custom-http-record', record);
You can access a built-in record object on the following events:
Class Events AAA AAA_REQUEST AAA_RESPONSE
ActiveMQ ACTIVEMQ_MESSAGE AJP AJP_RESPONSE CIFS CIFS_RESPONSE DB DB_RESPONSE DHCP DHCP_REQUEST DHCP_RESPONSE
DICOM DICOM_REQUEST DICOM_RESPONSE
DNS DNS_REQUEST DNS_RESPONSE
FIX FIX_REQUEST FIX_RESPONSE
Flow FLOW_RECORD FTP FTP_RESPONSE HL7 HL7_RESPONSE HTTP HTTP_RESPONSE IBMMQ IBMMQ_REQUEST IBMMQ_RESPONSE
ICA ICA_OPEN ICA_CLOSE
ICA_TICK
ICMP ICMP_MESSAGE Kerberos KERBEROS_REQUEST KERBEROS_RESPONSE
LDAP LDAP_REQUEST LDAP_RESPONSE
Memcache MEMCACHE_REQUEST MEMCACHE_RESPONSE
Modbus MODBUS_RESPONSE MongoDB MONGODB_REQUEST MONGODB_RESPONSE
MSMQ MSMQ_MESSAGE NetFlow NETFLOW_RECORD NFS NFS_RESPONSE NTLM NTLM_MESSAGE POP3 POP3_RESPONSE RDP RDP_OPEN RDP_CLOSE
RDP_TICK
Redis REDIS_REQUEST REDIS_RESPONSE
RTCP RTCP_MESSAGE RTP RTP_TICK SCCP SCCP_MESSAGE SFlow SFLOW_RECORD SIP SIP_REQUEST SIP_RESPONSE
SMPP SMPP_RESPONSE SMTP SMTP_RESPONSE SSH SSH_OPEN SSH_CLOSE
SSH_TICK
SSL SSL_ALERT SSL_OPEN
SSL_CLOSE
SSL_HEARTBEAT
SSL_RENEGOTIATE
Telnet TELNET_MESSAGE - debug (message: String): void
- Writes to the debug log if debugging is enabled.
- getTimestamp(): Number
- Returns the timestamp from the packet that caused the trigger event to run, expressed in milliseconds with microseconds as the fractional segment after the decimal.
- log (message: String): void
- Writes to the debug log regardless of whether debugging is enabled.
Multiple calls to debug and log statements in which the message is the same value will display once every 30 seconds.
The limit for debug log entries is 2048 bytes. To log larger entries, see Remote.Syslog.
- md5 (message: String|Buffer): String
- Hashes the UTF-8 representation of the specified message Buffer object or string and returns the MD5 sum of the string.
- sha1 (message: String|Buffer): String
- Hashes the UTF-8 representation of the specified message Buffer object or string and returns the SHA-1 sum of the string.
- sha256 (message: String|Buffer): String
- Hashes the UTF-8 representation of the specified message Buffer object or string and returns the SHA-256 sum of the string.
- sha512 (message: String|Buffer): String
- Hashes the UTF-8 representation of the specified message Buffer object or string and returns the SHA-512 sum of the string.
- uuid(): String
- Returns a random version 4 Universally Unique Identifier (UUID).
General purpose classes
The Trigger API classes in this section provide functionality that is broadly applicable across all events.
Class | Description |
---|---|
Application | Enables you to create new applications and adds custom metrics at the application level. |
Buffer | Enables you to access buffer content. |
Detection | Enables you to retrieve information about detections on the ExtraHop system. |
Device | Enables you to retrieve device attributes and add custom metrics at the device level. |
Discover | Enables you to access newly discovered devices and applications. |
Flow | Flow refers to a conversation between two endpoints over a protocol such as TCP, UDP or ICMP. The Flow class provides access to elements of these conversations, such as endpoint IP addresses and age of the flow. The Flow class also contains a flow store designed to pass objects from request to response on the same flow. |
FlowInterface | Enables you to retrieve flow interface attributes and add custom metrics at the interface level. |
FlowNetwork | Enables you to retrieve flow network attributes and add custom metrics at the flow network level. |
GeoIP | Enables you to retrieve the approximate country-level or city-level location of a specific IP address. |
IPAddress | Enables you to retrieve IP address attributes. |
Network | Enables you to add custom metrics at the global level. |
Session | Enables you to access the session table,which supports coordination across multiple independently executing triggers. |
System | Enables you to access properties that identify the ExtraHop system on which a trigger is running. |
ThreatIntel | Enables you to see whether an IP address, hostname, or URI is suspect. |
Trigger | Enables you to access details about a running trigger. |
VLAN | Enables you to access information about a VLAN on the network. |
Application
The Application class enables you collect metrics across multiple types of network traffic to capture information with cross-tier impact. For example, if you want a unified view of all the network traffic associated with a website—from web transactions to DNS requests and responses to database transactions—you can write a trigger to create a custom application that contains all of these related metrics. The Application class also enables you to create custom metrics and commit the metric data to applications. Applications can only be created and defined through triggers.
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();
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);
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>]
Instance properties
- id: String
- The unique ID of the application, as shown in the ExtraHop system on the page for that application.
Buffer
The Buffer class provides access to binary data.
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.
Methods
- Buffer (string: String | format: String)
- Constructor for the Buffer class that decodes an encoded string into a Buffer object.
The following parameters are required:
- string: String
- The encoded string.
- format: String
- The format that the string argument is encoded with. The following encoding
formats are valid:
- base64
- base64url
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 Â
Detection
The Detection class enables you to retrieve information about detections on the ExtraHop system.
Note: | Machine learning detections require a connection to ExtraHop Cloud Services. |
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.
The following values are valid:
Value Category sec Security sec.action Actions on Objective sec.botnet Botnet sec.caution Caution sec.command Command & Control sec.cryptomining Cryptomining sec.dos Denial of Service sec.exfil Exfiltration sec.exploit Exploitation sec.hardening Hardening sec.lateral Lateral Movement sec.ransomware Ransomware sec.recon Reconnaissance perf Performance perf.auth Authorization & Access Control perf.db Database perf.network Network Infrastructure perf.service Service Degradation perf.storage Storage perf.virtual Desktop & App Virtualization perf.web Web Application - 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 (#) 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. * First example * Second example Ordered lists Place a single number and period (1.) before your text. 1. First example 2. 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
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 }
- 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.
Device
The Device class enables you to retrieve device attributes and add custom metrics at the device level.
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);
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>]
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);
Note: | A device might sometimes act as a client and sometimes as a server on a flow.
|
- 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 }
- 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
Discover
The Discover class enables you to retrieve information about newly discovered devices and applications.
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.
ExternalData
The ExternalData class enables you to retrieve data sent from external sources to the Trigger API through the ExtraHop REST API.
Events
- EXTERNAL_DATA
- Runs every time data is sent to the ExtraHop system through the POST triggers/externaldata operation.
Flow
Flow refers to a conversation between two endpoints over a protocol such as TCP, UDP or ICMP. The Flow class provides access to elements of these conversations, such as endpoint IP addresses and age of the flow. The Flow class also contains a flow store designed to pass objects from request to response on the same flow.
Note: | You can apply the Flow class on most L7 protocol events, but it is not supported on session or datastore events. |
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"); }
- 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);
- 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.
Endpoints
Flow refers to a conversation between two endpoints over a protocol; an endpoint can be one of the following components:
- client
- server
- sender
- receiver
The methods and properties described in this section are called or accessed for a specified endpoint on the flow. For example, to access the device property from an HTTP client, the syntax is Flow.client.device.
The endpoint that you specify depends on the events associated with the trigger. For example, the ACTIVEMQ_MESSAGE event only supports sender and receiver endpoints. The following table displays a list of events that can be associated with a flow and the endpoints supported for each event:
Event | Client / Server | Sender / Receiver |
---|---|---|
AAA_REQUEST | yes | yes |
AAA_RESPONSE | yes | yes |
AJP_REQUEST | yes | yes |
AJP_RESPONSE | yes | yes |
ACTIVEMQ_MESSAGE | no | yes |
CIFS_REQUEST | yes | yes |
CIFS_RESPONSE | yes | yes |
DB_REQUEST | yes | yes |
DB_RESPONSE | yes | yes |
DHCP_REQUEST | yes | yes |
DHCP_RESPONSE | yes | yes |
DICOM_REQUEST | yes | yes |
DICOM_RESPONSE | yes | yes |
DNS_REQUEST | yes | yes |
DNS_RESPONSE | yes | yes |
FIX_REQUEST | yes | yes |
FIX_RESPONSE | yes | yes |
FLOW_CLASSIFY | yes | no |
FLOW_DETACH | yes | no |
FLOW_RECORD | yes | no |
FLOW_TICK | yes | no |
FLOW_TURN | yes | no |
FTP_REQUEST | yes | yes |
FTP_RESPONSE | yes | yes |
HL7_REQUEST | yes | yes |
HL7_RESPONSE | yes | yes |
HTTP_REQUEST | yes | yes |
HTTP_RESPONSE | yes | yes |
IBMMQ_REQUEST | yes | yes |
IBMMQ_RESPONSE | yes | yes |
ICA_AUTH | yes | no |
ICA_CLOSE | yes | no |
ICA_OPEN | yes | no |
ICA_TICK | yes | no |
ICMP_MESSAGE | no | yes |
KERBEROS_REQUEST | yes | yes |
KERBEROS_RESPONSE | yes | yes |
LDAP_REQUEST | yes | yes |
LDAP_RESPONSE | yes | yes |
MEMCACHE_REQUEST | yes | yes |
MEMCACHE_RESPONSE | yes | yes |
MOBUS_REQUEST | yes | yes |
MODBUS_RESPONSE | yes | yes |
MONGODB_REQUEST | yes | yes |
MONGODB_RESPONSE | yes | yes |
MSMQ_MESSAGE | no | yes |
NFS_REQUEST | yes | yes |
NFS_RESPONSE | yes | yes |
POP3_REQUEST | yes | yes |
POP3_RESPONSE | yes | yes |
REDIS_REQUEST | yes | yes |
REDIS_RESPONSE | yes | yes |
RDP_CLOSE | yes | no |
RDP_OPEN | yes | no |
RDP_TICK | yes | no |
RTCP_MESSAGE | no | yes |
RTP_CLOSE | no | yes |
RTP_OPEN | no | yes |
RTP_TICK | no | yes |
SCCP_MESSAGE | no | yes |
SIP_REQUEST | yes | yes |
SIP_RESPONSE | yes | yes |
SMPP_REQUEST | yes | yes |
SMPP_RESPONSE | yes | yes |
SMTP_REQUEST | yes | yes |
SMTP_RESPONSE | yes | yes |
SSL_ALERT | yes | yes |
SSL_CLOSE | yes | no |
SSL_HEARTBEAT | yes | yes |
SSL_OPEN | yes | no |
SSL_PAYLOAD | yes | yes |
SSL_RECORD | yes | yes |
SSL_RENEGOTIATE | yes | no |
TCP_CLOSE | yes | no |
TCP_OPEN | yes | no |
TCP_PAYLOAD | yes | yes |
UDP_PAYLOAD | yes | yes |
TELNET_MESSAGE | yes | yes |
WEBSOCKET_OPEN | yes | no |
WEBSOCKET_CLOSE | yes | no |
WEBSOCKET_MESSAGE | yes | yes |
- Endpoint methods
-
- commitRecord(): void
- Sends a record to the configured recordstore on a
FLOW_RECORD event. Record commits are not supported on
FLOW_CLASSIFY, FLOW_DETACH,
FLOW_TICK, or FLOW_TURN events.
On a flow, traffic moves in each direction between two endpoints. The commitRecord() method only records flow details in one direction, such as from the client to the server. To record details about the entire flow you must call commitRecord() twice, once for each direction, and specify the endpoint in the syntax—for example, Flow.client.commitRecord() and Flow.server.commitRecord().
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.
To view the default properties committed to the record object, see the record property below.
- Endpoint properties
-
- bytes: Number
- The number of L4 payload bytes transmitted by a
device. Specify the device role in the syntax—for example,
Flow.client.bytes or
Flow.receiver.bytes.
Access only on FLOW_TICK, FLOW_TURN, or FLOW_RECORD events; otherwise, an error will occur.
- customDevices: Array
- An array of custom devices in the flow. Specify the device role in the syntax—for example, Flow.client.customDevices or Flow.receiver.customDevices.
- device: Device
- The Device object associated with a device.
Specify the device role in the syntax. For example, to access the MAC address of
the client device, specify
Flow.client.device.hwaddr.
- equals: Boolean
- Performs an equality test between Device objects.
- dscp: Number
- The number representing the last differentiated services code point (DSCP) value
of the flow packet.
Specify the device role in the syntax—for example, Flow.client.dscp or Flow.server.dscp.
- dscpBytes: Array
- An array that contains the number of L2 bytes for a
specific Differentiated Services Code Point (DSCP) value transmitted by a device
in the flow. Specify the device role in the syntax—for example,
Flow.client.dscpBytes or
Flow.server.dscpBytes.
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.
- dscpName1: String
- The name associated with the DSCP value transmitted by device1 in the flow. The
following table displays well-known DSCP names:
Number Name 8 CS1 10 AF11 12 AF12 14 AF13 16 CS2 18 AF21 20 AF22 22 AF23 24 CS3 26 AF31 28 AF32 30 AF33 32 CS4 34 AF41 36 AF42 38 AF43 40 CS5 44 VA 46 EF 48 CS6 56 CS7 - dscpName2: String
- The name associated with the DSCP value transmitted by device2 in the flow. The
following table displays well-known DSCP names:
Number Name 8 CS1 10 AF11 12 AF12 14 AF13 16 CS2 18 AF21 20 AF22 22 AF23 24 CS3 26 AF31 28 AF32 30 AF33 32 CS4 34 AF41 36 AF42 38 AF43 40 CS5 44 VA 46 EF 48 CS6 56 CS7 - dscpPkts: Array
- An array that contains the number of L2 packets for a
given Differentiated Services Code Point (DSCP) value transmitted by a device in
the flow. Specify the device role in the syntax—for example,
Flow.client.dscpPkts or
Flow.server.dscpPkts.
The value is zero for each entry that has no packets of the specific DSCP since the last FLOW_TICK event.
Applies only to FLOW_TICK or FLOW_TURN events.
- fragPkts: Number
- The number of packets resulting from IP fragmentation transmitted by a client or
server device in the flow. Specify the device role in the syntax—for example,
Flow.client.fragPkts or
Flow.server.fragPkts.
Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.
- ipaddr1: IPAddress
- The IPAddress object associated with device1
in the flow.
- equals: Boolean
- Performs an equality test between IPAddress objects.
- ipaddr2: IPAddress
- The IPAddress object associated with device2
in the flow.
- equals: Boolean
- Performs an equality test between IPAddress objects.
- 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.
- 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.
- l2Bytes: Number
- The number of L2 bytes, including the ethernet headers,
transmitted by a device in the flow. Specify the device role in the syntax—for
example, Flow.client.l2Bytes or
Flow.server.l2Bytes.
Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.
- nagleDelay: Number
- The number of Nagle delays associated with a device in the flow. Specify the
device role in the syntax—for example, Flow.client.nagleDelay or
Flow.server.nagleDelay.
Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.
- overlapFragPkts: Number
- The number of non-identical IP fragment packets with overlapping data
transmitted by a device in the flow. Specify the device role in the syntax—for
example, Flow.client.overlapFragPkts or
Flow.server.overlapFragPkts.
Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.
- overlapSegments: Number
- The number of non-identical TCP segments, transmitted by a device in the flow,
where two or more TCP segments contain data for the same part of the flow. Specify
the device role in the syntax—for example,
Flow.client.overlapSegments or
Flow.server.overlapSegments.
Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.
- payload: Buffer
- The payload Buffer associated with a device
in the flow. Specify the device role in the syntax—for example,
Flow.client.payload or
Flow.receiver.payload.
Access only on TCP_PAYLOAD, UDP_PAYLOAD, or SSL_PAYLOAD events; otherwise, an error will occur.
- pkts: Number
- The number of packets transmitted by a device in the flow. Specify the device
role in the syntax—for example, Flow.client.pkts or
Flow.server.pkts.
Access only on FLOW_TICK, FLOW_TURN, or FLOW_RECORD events; otherwise, an error will occur.
- port: Number
- The port number associated with a device in the flow. Specify the device role in the syntax—for example, Flow.client.port or Flow.receiver.port.
- rcvWndThrottle: Number
- The number of receive window throttles sent from a device in the flow. Specify
the device role in the syntax—for example,
Flow.client.rcvWndThrottle or
Flow.server.rcvWndThrottle.
Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.
- record: Object
- The record object that can be sent to the configured recordstore through a call to
Flow.commitRecord() on a FLOW_RECORD event.
The record object represents data from a single direction on the flow.
The default record object can contain the following properties:
- age
- bytes (L3)
Note: This property represents the total number of bytes that were transmitted by the flow at the time that the FLOW_RECORD event ran. The FLOW_RECORD event runs several times over the course of each flow, so the value will increase every time the event runs. - 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
- tcpFlags
Specify the device role in the syntax—for example, Flow.client.record or Flow.server.record.
Access the record object only on FLOW_RECORD events; otherwise, an error will occur.
- rto: Number
- The number of retransmission
timeouts (RTOs) associated with a device in the flow. Specify the device
role in the syntax—for example, Flow.client.rto or
Flow.server.rto.
Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.
- totalL2Bytes
- The number of L2 bytes sent by a device during the flow. Specify the device role in the syntax—for example, Flow.client.totalL2Bytes or Flow.server.totalL2Bytes.
- totalL2Bytes1: Number
- The number of L2 bytes sent during the flow by device1.
- totalL2Bytes2: Number
- The number of L2 bytes sent during the flow by device2.
- zeroWnd: Number
- The number of zero windows sent from a device in the flow. Specify the device
role in the syntax—for example, Flow.client.zeroWnd or
Flow.server.zeroWnd.
Access only on FLOW_TICK or FLOW_TURN events; otherwise, an error will occur.
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); }
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";
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;
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 } }
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); } }
- 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
FlowInterface
The FlowInterface class enables you to retrieve flow interface attributes and to add custom metrics at the interface level.
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.
FlowNetwork
The FlowNetwork class enables you to retrieve flow network attributes and to add custom metrics at the flow network level.
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.
GeoIP
The GeoIP class enables you to retrieve the approximate country-level or city-level location of a specific address.
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); }
- 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.
IPAddress
The IPAddress class enables you to retrieve IP address attributes. The IPAddress class is also available as a property for the Flow class.
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 }
- 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");}
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.
Network
The Network class enables you to add custom metrics at the global level.
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.
Session
The Session class provides access to the session table. It is designed to support coordination across multiple independently executing triggers. The session table's global state means any changes by a trigger or external process become visible to all other users of the session table. Because the session table is in-memory, changes are not saved when you restart the ExtraHop system or the capture process.
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.
Options
- expire: Number
- The duration after which eviction occurrs, expressed in seconds. If the value is null or undefined, the entry is evicted only when the session table grows too large.
- notify: Boolean
- Indicates whether the key is available on SESSION_EXPIRE events. The default value is false.
- priority: String
- Priority level that determines which entries to evict if the session table grows too large. Valid values are PRIORITY_LOW, PRIORITY_NORMAL, and PRIORITY_HIGH. The default value is PRIORITY_NORMAL.
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.
System
The System class enables you to retrieve information about the sensor or console on which a trigger is running. This information in useful in environments with multiple sensors.
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.
ThreatIntel
The ThreatIntel class enables you to see whether threats have been found for IP addresses, hostnames, or URIs. (ExtraHop Reveal(x) Premium and Ultra only)
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.
Protocol and network data classes
The Trigger API classes in this section enable you to access properties and record metrics from protocol, message, and flow activity that occurs on the ExtraHop ExtraHop system.
Class | Description |
---|---|
AAA | Enables you to store metrics and access properties on AAA_REQUEST or AAA_RESPONSE events. |
ActiveMQ | Enables you to store metrics and access properties on ACTIVEMQ_MESSAGE events. |
AJP | The AJP class enables you to store metrics and access properties on AJP_REQUEST and AJP_RESPONSE events. |
CDP | The CDP class enables you to store metrics and access properties on CDP_FRAME events. |
CIFS | Enables you to store metrics and access properties on CIFS_REQUEST and CIFS_RESPONSE events. |
DB | Enables you to store metrics and access properties on DB_REQUEST and DB_RESPONSE events. |
DHCP | Enables you to store metrics and access properties on DHCP_REQUEST and DHCP_RESPONSE events. |
DICOM | Enables you to store metrics and access properties on DICOM_REQUEST and DICOM_RESPONSE events. |
DNS | Enables you to store metrics and access properties on DNS_REQUEST and DNS_RESPONSE events. |
FIX | Enables you to store metrics and access properties on FIX_REQUEST and FIX_RESPONSE events. |
FTP | Enables you to store metrics and access properties on FTP_REQUEST and FTP_RESPONSE events. |
HL7 | Enables you to store metrics and access properties on HL7_REQUEST and HL7_RESPONSE events. |
HTTP | Enables you to store metrics and access properties on HTTP_REQUEST and HTTP_RESPONSE events. |
IBMMQ | Enables you to store metrics and access properties on IBMMQ_REQUEST and IBMMQ_RESPONSE events. |
ICA | Enables you to store metrics and access properties on ICA_OPEN, ICA_AUTH, ICA_TICK, and ICA_CLOSE events. |
ICMP | Enables you to store metrics and access properties on ICMP_MESSAGE events. |
Kerberos | Enables you to store metrics and access properties on KERBEROS_REQUEST and KERBEROS_RESPONSE events. |
LDAP | Enables you to store metrics and access properties on LDAP_REQUEST and LDAP_RESPONSE events. |
LLDP | Enables you to access properties on LLDP_FRAME events. |
Memcache | Enables you to store metrics and access properties on MEMCACHE_REQUEST and MEMCACHE_RESPONSE events. |
Modbus | Enables you to store metrics and access properties on MODBUS_REQUEST and MODBUS_RESPONSE events. |
MongoDB | The MongoDB class enables you to store metrics and access properties on MONGODB_REQUEST and MONGODB_RESPONSE events. |
MSMQ | The MSMQ class enables you to store metrics and access properties on MSMQ_MESSAGE event. |
NetFlow | Enables you to store metrics and access properties on NETFLOW_RECORD events. |
NFS | Enables you to store metrics and access properties on NFS_REQUEST and NFS_RESPONSE events. |
NTLM | Enables you to store metrics and access properties on NTLM_MESSAGE events. |
POP3 | Enables you to store metrics and access properties on POP3_REQUEST and POP3_RESPONSE events. |
RDP | Enables you to store metrics and access properties on RDP_OPEN, RDP_CLOSE, and RDP_TICK events. |
Redis | Enables you to store metrics and access properties on REDIS_REQUEST and REDIS_RESPONSE events. |
RPC | Enables you to store metrics and access properties on RPC_REQUEST and RPC_RESPONSE events. |
RTCP | Enables you to store metrics and access properties on RTCP_MESSAGE events. |
RTP | Enables you to store metrics and access properties on RTP_OPEN, RTP_CLOSE, and RTP_TICK events. |
SCCP | Enables you to store metrics and access properties on SCCP_MESSAGE events. |
SDP | Enables you to access properties on SIP_REQUEST and SIP_RESPONSE events. |
SFlow | Enables you to store metrics and access properties on SFLOW_RECORD events. |
SIP | Enables you to store metrics and access properties on SIP_REQUEST and SIP_RESPONSE events. |
SMPP | Enables you to store metrics and access properties on SMPP_REQUEST and SMPP_RESPONSE events. |
SMTP | Enables you to store metrics and access properties on SMTP_REQUEST and SMTP_RESPONSE events. |
SSH | Enables you to store metrics and access properties on SSH_CLOSE, SSH_OPEN and SSH_TICK events. |
SSL | Enables you to store metrics and access properties on SSL_OPEN, SSL_CLOSE, SSL_ALERT, SSL_RECORD, SSL_HEARTBEAT, and SSL_RENEGOTIATE events. |
TCP | Enables you to access properties and retrieve metrics from TCP events and on FLOW_TICK and FLOW_TURN events. |
Telnet | Enables you to store metrics and access properties on TELNET_MESSAGE events. |
Turn | Enables you to store metrics and access properties on FLOW_TURN events. |
UDP | Enables you to access properties and retrieve metrics from UDP events and on FLOW_TICK and FLOW_TURN events. |
WebSocket | Enables you to access properties on WEBSOCKET_OPEN, WEBSOCKET_CLOSE, and WEBSOCKET_MESSAGE events. |
AAA
The AAA (Authentication, Authorization, and Accounting) class enables you to store metrics and access properties on AAA_REQUEST or AAA_RESPONSE events.
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.
ActiveMQ
The ActiveMQ class enables you to store metrics and access properties on ACTIVEMQ_MESSAGE events. ActiveMQ is an implementation of the Java Messaging Service (JMS).
Methods
- commitRecord(): void
- Sends a record to the configured recordstore on an
ACTIVEMQ_MESSAGE event.
To view the default properties committed to the record object, 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
- correlationId: String
- The JMSCorrelationID field of the message.
- expiration: Number
- The JMSExpiration field of the message.
- msg: Buffer
- The message body. For TEXT_MESSAGE format messages, this returns the body of the message as a UTF-8 string. For all other message formats, this returns the raw bytes.
- msgFormat: String
- The message format. Possible values are:
- BYTES_MESSAGE
- MAP_MESSAGE
- MESSAGE
- OBJECT_MESSAGE
- STREAM_MESSAGE
- TEXT_MESSAGE
- BLOG_MESSAGE
- msgId: String
- The JMSMessageID field of the message.
- persistent: Boolean
- The value is true if the JMSDeliveryMode is PERSISTENT.
- priority: Number
- The JMSPriority field of the message.
- 0 is the lowest priority.
- 9 is the highest priority.
- 0-4 are gradations of normal priority.
- 5-9 are gradations of expedited priority.
- properties: Object
- Zero or more properties attached to the message. The keys are arbitrary strings and the values may be booleans, numbers, or strings.
- queue: String
- The JMSDestination field of the message.
- receiverBytes: Number
- The number of application-level bytes from the receiver.
- receiverIsBroker: Boolean
- The value is true if the flow-level receiver of the message is a broker.
- receiverL2Bytes: Number
- The number of L2 bytes from the receiver.
- receiverPkts: Number
- The number of packets from the receiver.
- receiverRTO: Number
- The number of RTOs from the receiver.
- receiverZeroWnd: Number
- The number of zero windows sent by the receiver.
- record: Object
- The record object that can be sent to the configured recordstore through a call
to ActiveMQ.commitRecord() on an ACTIVEMQ_MESSAGE
event.
The default record object can contain the following properties:
- clientIsExternal
- correlationId
- expiration
- msgFormat
- msgId
- persistent
- priority
- queue
- receiverBytes
- receiverIsBroker
- receiverIsExternal
- receiverL2Bytes
- receiverPkts
- receiverRTO
- receiverZeroWnd
- redeliveryCount
- replyTo
- roundTripTime
- senderBytes
- senderIsBroker
- senderIsExternal
- senderL2Bytes
- senderPkts
- senderRTO
- senderZeroWnd
- serverIsExternal
- timeStamp
- totalMsgLength
- redeliveryCount: Number
- The number of redeliveries.
- replyTo: String
- The JMSReplyTo field of the message, converted to a string.
- roundTripTime: Number
- The median round trip time (RTT), expressed in milliseconds. The value is NaN if there are no RTT samples.
- senderBytes: Number
- The number of application-level bytes from the sender.
- senderIsBroker: Boolean
- The value is true if the flow-level sender of the message is a broker.
- senderL2Bytes: Number
- The number of L2 bytes from the sender.
- senderPkts: Number
- The number of packets from the sender.
- senderRTO: Number
- The number of RTOs from the sender.
- senderZeroWnd: Number
- The number of zero windows sent by the sender.
- timestamp: Number
- The time when the message was handed off to a provider to be sent, expressed in GMT. This is the JMSTimestamp field of the message.
- totalMsgLength: Number
- The length of the message, expressed in bytes.
AJP
Apache JServ Protocol (AJP) proxies inbound requests from a web server to an application server and is often applied to load-balanced environments where one or more front-end web servers feed requests into one or more application servers. The AJP class enables you to store metrics and access properties on AJP_REQUEST and AJP_RESPONSE events.
Events
- AJP_REQUEST
- Runs after the web server sends an AJP Forward Request message to a servlet container, and then transfers any subsequent request body.
- AJP_RESPONSE
- Runs after a servlet container sends an AJP End Response message to signal that the servlet container has finished processing an AJP Forward Request and has sent back the requested information.
Methods
- commitRecord(): Void
- Sends a record to the configured recordstore on an
AJP_RESPONSE event. Record commits on AJP_REQUEST
events are not supported.
To view the default properties committed to the record object, 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.
- findHeaders(name: String): Array
- Accesses AJP header values and returns an array of header objects (with name and value properties) where the names match the prefix of the specified string. Accesses request headers on AJP_REQUEST events and response headers on AJP_RESPONSE requests.
Properties
- attributes: Object
- An array of optional AJP attributes sent with the request, such as remote_user,
auth_type, query_string, jvm_route, ssl_cert, ssl_cipher, and ssl_session.
Access only on AJP_REQUEST events; otherwise, an error will occur.
- fwdReqClientAddr: IPAddress
- The IPAddress of the HTTP client that made the original request to the server. The value is null if the available information cannot be parsed to an IP address.
- fwdReqHost: String
- The HTTP host specified by the HTTP client that made the original request to the server.
- fwdReqIsEncrypted: Boolean
- The value is true if SSL encryption was applied by the HTTP client that made the original request to the server.
- fwdReqServerName: String
- The name of the server to which the HTTP client made the original request.
- fwdReqServerPort: Number
- The TCP port on the server to which the HTTP client made the original request.
- headers: Object
- When accessed on AJP_REQUEST events, an array of header names and
values sent with the request.
When accessed on AJP_RESPONSE events, an array of headers conveyed in the AJP Send Headers message by the server to the end user browser.
- method: String
- The HTTP method of the request, such as POST or GET, from the server to the servlet container.
- processingTime: Number
- The time between the last byte of the request received and the first byte of the
response payload sent, expressed in milliseconds. The value is NaN on malformed and aborted responses or if the timing
is invalid.
Access only on AJP_RESPONSE events; otherwise, an error will occur.
- protocol: String
- The protocol of the request from the server to the servlet container. Not set for other message types.
- record: Object
- The record object that can be sent to the configured recordstore through a call
to AJP.commitRecord() on an AJP_RESPONSE event.
The default record object can contain the following properties:
- clientIsExternal
- fwdReqClientAddr
- fwdReqHost
- fwdReqIsEncrypted
- fwdReqServerName
- fwdReqServerPort
- method
- processingTime
- protocol
- receiverIsExternal
- reqSize
- rspSize
- statusCode
- senderIsExternal
- serverIsExternal
- uri
Access only on AJP_RESPONSE events; otherwise, an error will occur.
- reqBytes: Number
- The number of L4 request bytes, excluding L4
headers.
Access only on AJP_RESPONSE events; otherwise, an error will occur.
- 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).
- reqSize: Number
- The number of L7 request bytes, excluding AJP headers.
- rspBytes: Number
- The number of L4 response bytes, excluding L4 protocol
overhead, such as ACKs, headers, and retransmissions.
Access only on AJP_RESPONSE events; otherwise, an error will occur.
- rspL2Bytes: Number
- The number of L2 response bytes, including protocol overhead,
such as headers.
Access only on AJP_RESPONSE events; otherwise, an error will occur.
- rspPkts: Number
- The number of response packets.
Access only on AJP_RESPONSE events; otherwise, an error will occur.
- rspRTO: Number
- The number of response retransmission
timeouts (RTOs).
Access only on AJP_RESPONSE events; otherwise, an error will occur.
- rspSize: Number
- The number of L7 response bytes, excluding AJP headers.
Access only on AJP_RESPONSE events; otherwise, an error will occur.
- statusCode: Number
- The HTTP status code returned by the servlet container for responses to AJP Forward
Request messages.
Access only on AJP_RESPONSE events; otherwise, an error will occur.
- uri: String
- The URI for the request from the server to the servlet container. Not set for non-AJP message types.
CDP
Cisco Discovery Protocol (CDP) is a proprietary protocol that enables connected Cisco devices to send information to each other. The CDP class enables you to access properties on CDP_FRAME events.
Properties
- destination: String
- The destination MAC address. The most common destination is 01:00:0c:cc:cc:cc, indicating a multicast address.
- checksum: Number
- The CDP checksum.
- source: Device
- The device sending the CDP frame.
- ttl: Number
- The time to live, expressed in seconds. This is the length of time during which the information in this frame is valid, starting with when the information is received.
- tlvs: Array of Objects
- An array containing each type, length, value (TLV) field. A TLV field
contains information such as the device ID, address, and platform. Each
field is an object with the following properties:
- type: Number
- The type of TLV.
- value: Buffer
- The value of the TLV.
- version: Number
- The CDP protocol version.
CIFS
The CIFS class enables you to store metrics and access properties on CIFS_REQUEST and CIFS_RESPONSE events.
Events
- CIFS_REQUEST
- Runs on every CIFS request processed by the device.
- CIFS_RESPONSE
- Runs on every CIFS response processed by the device.
Note: The CIFS_RESPONSE event runs after every CIFS_REQUEST event, even if the corresponding response is never observed by the ExtraHop system.
Methods
- commitRecord(): void
- Sends a record to the configured recordstore on a
CIFS_RESPONSE event. Record commits on CIFS_REQUEST
events are not supported.
To view the default properties committed to the record object, 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
Important: | Access time is the time it takes for a CIFS server to receive a
requested block. There is no access time for operations that do not access actual block data
within a file. Processing time is the time it takes for a CIFS server to respond to the
operation requested by the client, such as a metadata retrieval request. There are no access times for SMB2_CREATE commands, which create a file that is referenced in the response by an SMB2_FILEID command. The referenced file blocks are then read from or written to the NAS-storage device. These file read and write operations are calculated as access times. |
- accessTime: Number
- The amount of time taken by the server to access a file on disk, expressed in
milliseconds. For CIFS, this is the time from the first READ command in a CIFS flow
until the first byte of the response payload. The value is NaN if the measurement or timing is invalid.
Access only on CIFS_RESPONSE events; otherwise, an error will occur.
- dialect: String
- The dialect of SMB negotiated between the client and the server.
- encryptedBytes: Number
- The number of encrypted bytes in the request or response.
- encryptionProtocol: String
- The protocol that the transaction is encrypted with.
- error: String
- The detailed error message recorded by the ExtraHop system.
Access only on CIFS_RESPONSE events; otherwise, an error will occur.
- isCommandCreate: Boolean
- The value is true if the message contains an SMB file creation command.
- isCommandDelete: Boolean
- The value is true if the message contains an SMB DELETE command.
- isCommandFileInfo: Boolean
- The value is true if the message contains an SMB file info command.
- isCommandLock: Boolean
- The value is true if the message contains an SMB locking command.
- isCommandRead: Boolean
- The value is true if the message contains an SMB READ command.
- isCommandRename: Boolean
- The value is true if the message contains an SMB RENAME command.
- isCommandWrite: Boolean
- The value is true if the message contains an SMB WRITE command.
- isDecrypted: Boolean
- The value is true if the ExtraHop system securely decrypted and analyzed the transaction. Decrypted traffic analysis can expose advanced threats that hide within encrypted traffic.
- isEncrypted: Boolean
- The value is true if the transaction is encrypted.
- isRspAborted: Boolean
- The value is true if the connection is closed before the CIFS response was
complete.
Access only on CIFS_RESPONSE events; otherwise, an error will occur.
- isRspSigned: Boolean
- The value is true if the response is signed by the CIFS server.
- method: String
- The CIFS method. Correlates to the methods listed under the CIFS metric in the ExtraHop system.
- msgID: Number
- The SMB transaction identifier.
- payload: Buffer
- The Buffer object containing the payload bytes
starting from the READ or WRITE command in the CIFS message.
The buffer contains the N first bytes of the payload, where N is the number of payload bytes specified by the L7 Payload Bytes to Buffer option when the trigger was configured through the ExtraHop WebUI. The default number of bytes is 2048. For more information, see Advanced trigger options.
Note: The buffer cannot contain more than 4 KB, even if the L7 Payload Bytes to Buffer option is set to a higher value. For larger volumes of payload bytes, the payload might be spread across a series of READ or WRITE commands so that no single trigger event contains the entire requested payload. You can reassemble the payload into a single, consolidated buffer through the Flow.store and payloadOffset properties.
- payloadOffset: Number
- The file offset, expressed in bytes, within the resource property. The payload property is obtained from the resource property at the offset.
- processingTime: Number
- The server processing time, expressed in milliseconds. The value is NaN on malformed and aborted responses or if the timing
is invalid.
Access only on CIFS_RESPONSE events; otherwise, an error will occur.
- record: Object
- The record object that can be sent to the configured recordstore through a call to
CIFS.commitRecord on a CIFS_RESPONSE event.
The default record object can contain the following properties:
- accessTime
- clientIsExternal
- clientZeroWnd
- error
- isCommandCreate
- isCommandDelete
- isCommandFileInfo
- isCommandLock
- isCommandRead
- isCommandRename
- isCommandWrite
- method
- processingTime
- receiverIsExternal
- reqSize
- reqXfer
- resource
- rspBytes
- rspXfer
- senderIsExternal
- serverIsExternal
- serverZeroWnd
- share
- statusCode
- user
- warning
Access only on CIFS_RESPONSE events; otherwise, an error will occur.
- reqBytes: Number
- The number of L4 request bytes, excluding L4
headers.
Access only on CIFS_RESPONSE events; otherwise, an error will occur.
- reqL2Bytes: Number
- The number of L2 request bytes, including L2
headers.
Access only on CIFS_RESPONSE events; otherwise, an error will occur.
- reqPkts: Number
- The number of request packets.
Access only on CIFS_RESPONSE events; otherwise, an error will occur.
- reqRTO: Number
- The number of request retransmission
timeouts (RTOs).
Access only on CIFS_RESPONSE events; otherwise, an error will occur.
- reqSize: Number
- The number of L7 request bytes, excluding CIFS headers.
- reqTransferTime: Number
- The request transfer time, expressed in milliseconds. If the request is contained in a
single packet, the transfer time is zero. If the request spans multiple packets, the
value is the amount of time between detection of the first CIFS request packet and
detection of the last packet by the ExtraHop system. A high value might indicate a large
CIFS request or a network delay. The value is NaN if there is no valid measurement, or if the timing is
invalid.
Access only on CIFS_REQUEST events; otherwise, an error will occur.
- reqVersion: String
- The version of SMB running on the request.
- reqZeroWnd: Number
- The number of zero windows in the request.
- resource: String
- The share, path, and filename, concatenated together.
- roundTripTime: Number
- The median round trip time (RTT), expressed in milliseconds. The value is
NaN if there are no RTT samples.
Access only on CIFS_RESPONSE events; otherwise, an error will occur.
- rspBytes: Number
- The number of L4 response bytes, excluding L4 protocol
overhead, such as ACKs, headers, and retransmissions.
Access only on CIFS_RESPONSE events; otherwise, an error will occur.
- rspL2Bytes: Number
- The number of L2 response bytes, including protocol overhead,
such as headers.
Access only on CIFS_RESPONSE events; otherwise, an error will occur.
- rspPkts: Number
- The number of response packets.
Access only on CIFS_RESPONSE events; otherwise, an error will occur.
- rspRTO: Number
- The number of response retransmission
timeouts (RTOs).
Access only on CIFS_RESPONSE events; otherwise, an error will occur.
- rspSize: Number
- The number of L7 response bytes, excluding CIFS headers.
Access only on CIFS_RESPONSE events; otherwise, an error will occur.
- rspTransferTime: Number
- The response transfer time, expressed in milliseconds. If the response is contained in
a single packet, the transfer time is zero. If the response spans multiple packets, the
value is the amount of time between detection of the first CIFS response packet and
detection of the last packet by the ExtraHop system. A high value might indicate a large
CIFS response or a network delay. The value is NaN if there is no valid measurement, or if the timing is
invalid.
Access only on CIFS_RESPONSE events; otherwise, an error will occur.
- rspVersion: String
- The version of SMB running on the response.
Access only on CIFS_RESPONSE events; otherwise, an error will occur.
- rspZeroWnd: Number
- The number of zero windows in the response.
- share: String
- The name of the share the user is connected to.
- statusCode: Number
- The numeric status code of the response (SMB1 and SMB2 only).
Access only on CIFS_RESPONSE events; otherwise, an error will occur.
- user: String
- The username, if available. In some cases, such as when the login event was not visible or the access was anonymous, the username is not available.
- warning: String
- The detailed warning message recorded by the ExtraHop system.
Access only on CIFS_RESPONSE events; otherwise, an error will occur.
DB
The DB, or database, class enables you to store metrics and access properties on DB_REQUEST and DB_RESPONSE events.
Events
- DB_REQUEST
- Runs on every database request processed by the device.
- DB_RESPONSE
- Runs on every database response processed by the device.
Methods
- commitRecord(): void
- Sends a record to the configured recordstore on a
DB_RESPONSE event. Record commits on DB_REQUEST
events are not supported.
To view the default properties committed to the record object, 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
- appName: String
- The client application name, which is extracted only for MS SQL connections.
- correlationId: Number
- The correlation ID for DB2 applications. The value is null for non-DB2 applications.
- database: String
- The database instance. In some cases, such as when login events are encrypted, the database name is not available.
- encryptionProtocol: String
- The protocol that the transaction is encrypted with.
- error: String
- The detailed error messages recorded by the ExtraHop system in string format. If there
are multiple errors in one response, the errors are concatenated into one
string.
Access only on DB_RESPONSE events; otherwise, an error will occur.
- errors: Array of strings
- The detailed error messages recorded by the ExtraHop system in array format. If there
is only a single error in the response, the error is returned as an array containing one
string.
Access only on DB_RESPONSE events; otherwise, an error will occur.
- isDecrypted: Boolean
- The value is true if the ExtraHop system securely decrypted and analyzed the transaction. Decrypted traffic analysis can expose advanced threats that hide within encrypted traffic.
- isEncrypted: Boolean
- The value is true if the transaction is encrypted.
- isReqAborted: Boolean
- The value is true if the connection is closed before the DB request is complete.
- isRspAborted: Boolean
- The value is true if the connection is closed before the DB response
is complete.
Access only on DB_RESPONSE events; otherwise, an error will occur.
- method: String
- The database method that correlates to the methods listed under the Database metric in the ExtraHop system.
- params: Array
- An array of remote procedure call (RPC) parameters that are
only available for Microsoft SQL, PostgreSQL, and DB2 databases.
The array contains each of the following parameters:
- name: String
- The optional name of the supplied RPC parameter.
- value: String | Number
- A text, integer, or time and date field. If the value is not a text, integer, or time and date field, the value is converted into HEX/ASCII form.
The value of the params property is the same when accessed on either the DB_REQUEST or the DB_RESPONSE event.
- procedure: String
- The stored procedure name. Correlates to the procedures listed under the Database methods in the ExtraHop system.
- processingTime: Number
- The server processing time, expressed in milliseconds (equivalent to
rspTimeToFirstByte - reqTimeToLastByte). The value
is NaN on malformed and aborted responses or
if the timing is invalid.
Access only on DB_RESPONSE events; otherwise, an error will occur.
- record: Object
- The record object that can be sent to the configured recordstore through a call to
DB.commitRecord on a DB_RESPONSE event.
The default record object can contain the following properties:
- appName
- clientIsExternal
- clientZeroWnd
- correlationId
- database
- error
- isReqAborted
- isRspAborted
- method
- procedure
- receiverIsExternal
- reqSize
- reqTimeToLastByte
- rspSize
- rspTimeToFirstByte
- rspTimeToLastByte
- processingTime
- senderIsExternal
- serverIsExternal
- serverZeroWnd
- statement
- table
- user
Access only on DB_RESPONSE events; otherwise, an error will occur.
- reqBytes: Number
- The number of L4 request bytes, excluding L4
headers.
Access only on DB_RESPONSE events; otherwise, an error will occur.
- reqL2Bytes: Number
- The number of L2 request bytes, including L2
headers.
Access only on DB_RESPONSE events; otherwise, an error will occur.
- reqPkts: Number
- The number of request packets.
Access only on DB_RESPONSE events; otherwise, an error will occur.
- reqRTO: Number
- The number of request retransmission
timeouts (RTOs).
Access only on DB_RESPONSE events; otherwise, an error will occur.
- reqSize: Number
- The number of L7 request bytes, excluding database protocol headers.
- reqTimeToLastByte: Number
- The time from the first byte of the request until the last byte of the request, expressed in milliseconds. Returns NaN on malformed and aborted requests or if the timing is invalid.
- 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.
Access only on DB_RESPONSE events; otherwise, an error will occur.
- rspBytes: Number
- The number of L4 response bytes, excluding L4 protocol
overhead, such as ACKs, headers, and retransmissions.
Access only on DB_RESPONSE events; otherwise, an error will occur.
- rspL2Bytes: Number
- The number of L2 response bytes, including protocol overhead,
such as headers.
Access only on DB_RESPONSE events; otherwise, an error will occur.
- rspPkts: Number
- The number of response packets.
Access only on DB_RESPONSE events; otherwise, an error will occur.
- rspRTO: Number
- The number of response retransmission
timeouts (RTOs).
Access only on DB_RESPONSE events; otherwise, an error will occur.
- rspSize: Number
- The number of L7 response bytes, excluding database protocol headers.
Access only on DB_RESPONSE events; otherwise, an error will occur.
- rspTimeToFirstByte: Number
- The time from the first byte of the request until the first byte of the response,
expressed in milliseconds. The value is NaN
on malformed and aborted responses or if the timing is invalid.
Access only on DB_RESPONSE events; otherwise, an error will occur.
- rspTimeToLastByte: Number
- The time from the first byte of the request until the last byte of the response,
expressed in milliseconds. The value is NaN
on malformed and aborted responses or if the timing is invalid.
Access only on DB_RESPONSE events; otherwise, an error will occur.
- rspZeroWnd: Number
- The number of zero windows in the response.
- serverVersion: String
- The MS SQL server version.
- statement: String
- The full SQL statement, which might not be available for all database methods.
- table: String
- The name of the database table specified in the current statement. The following
databases are supported:
- Sybase
- Sybase IQ
- MySQL
- PostgreSQL
- IBM Informix
- MS SQL TDS
- Oracle TNS
- DB2
Returns an empty field if there is no table name in the request.
- user: String
- The username, if available. In some cases, such as when login events are encrypted, the username is unavailable.
DHCP
The DHCP class enables you to store metrics and access properties on DHCP_REQUEST and DHCP_RESPONSE events.
Events
- DHCP_REQUEST
- Runs on every DHCP request processed by the device.
- DHCP_RESPONSE
- Runs on every DHCP response processed by the device.
Methods
- commitRecord(): void
- Sends a record to the configured recordstore on either a
DHCP_REQUEST or DHCP_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.
- getOption(optionCode: Number): Object
- Accepts a DHCP option code integer as input and returns an object containing the
following fields:
- code: Number
- The DHCP option code.
- name: String
- The DHCP option name.
- payload: Number | String
- The type of payload returned will be whatever the type is for that specific option such as an IP address, an array of IP addresses, or a buffer object.
Returns null if the specified option code is not present in the message.
Properties
- chaddr: String
- The client hardware address of the DHCP client.
- clientReqDelay: Number
- The time elapsed before the client attempts to acquire or
renew a DHCP lease, expressed in seconds.
Access only on DHCP_REQUEST events; otherwise, an error will occur.
- error: String
- The error message associated with option code 56. The value is null
if there is no error.
Access only on DHCP_RESPONSE events; otherwise, an error will occur.
- gwAddr: IPAddress
- The IP address through which routers relay request and response messages.
- htype: Number
- The hardware type code.
- msgType: String
- The DHCP message type. Supported message types are:
- DHCPDISCOVER
- DHCPOFFER
- DHCPREQUEST
- DHCPDECLINE
- DHCPACK
- DHCPNAK
- DHCPRELEASE
- DHCPINFORM
- DHCPFORCERENEW
- DHCPLEASEQUERY
- DHCPLEASEUNASSIGNED
- DHCPLEASEUNKNOWN
- DHCPLEASEACTIVE
- DHCPBULKLEASEQUERY
- DHCPLEASEQUERYDONE
- offeredAddr: IPAddress
- The IP address the DHCP server is offering or assigning to the client.
Access only on DHCP_RESPONSE events; otherwise, an error will occur.
- options: Array of Objects
- An array of objects with each object containing the following fields:
- code: Number
- The DHCP option code.
- name: String
- The DHCP option name.
- payload: Number | String
- The type of payload returned will be whatever the type is for that specific option such as an IP address, an array of IP addresses, or a buffer object. IP addresses will be parsed into an array but if the number of bytes is not divisible by 4, it will instead be returned as a buffer.
- paramReqList: String
- A comma-separated list of numbers that represents the DHCP options requested from the server by the client. For a complete list of DHCP options, see https://www.iana.org/assignments/bootp-dhcp-parameters/bootp-dhcp-parameters.xhtml.
- processingTime: Number
- The process time, expressed in milliseconds. The value is NaN on malformed and aborted responses or if the timing is
invalid.
Access only on DHCP_RESPONSE events; otherwise, an error will occur.
- record: Object
- The record object that can be sent to the configured recordstore through a call to
DHCP.commitRecord on either a DHCP_REQUEST or
DHCP_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:
DHCP_REQUEST DHCP_RESPONSE clientIsExternal clientIsExternal clientReqDelay error gwAddr gwAddr htype htype msgType msgType receiverIsExternal offeredAddr reqBytes processingTime reqL2Bytes rspBytes reqPkts rspL2Bytes senderIsExternal rspPkts serverIsExternal receiverIsExternal txId senderIsExternal  serverIsExternal  txId - reqBytes: Number
- The number of L4 request bytes, excluding L4
headers.
Access only on DHCP_RESPONSE events; otherwise, an error will occur.
- reqL2Bytes: Number
- The number of L2 request bytes, including L2
headers.
Access only on DHCP_RESPONSE events; otherwise, an error will occur.
- reqPkts: Number
- The number of request packets.
Access only on DHCP_RESPONSE events; otherwise, an error will occur.
- rspBytes: Number
- The number of L4 response bytes, excluding L4 protocol
overhead, such as ACKs, headers, and retransmissions.
Access only on DHCP_RESPONSE events; otherwise, an error will occur.
- rspL2Bytes: Number
- The number of L2 response bytes, including protocol overhead,
such as headers.
Access only on DHCP_RESPONSE events; otherwise, an error will occur.
- rspPkts: Number
- The number of response packets.
Access only on DHCP_RESPONSE events; otherwise, an error will occur.
- txId: Number
- The transaction ID.
- vendor: String
- The Vendor Class Identifier (VCI) that specifies the vendor running on the client or server.
DICOM
The DICOM (Digital Imaging and Communications in Medicine) class enables you to store metrics and access properties on DICOM_REQUEST and DICOM_RESPONSE events.
Events
- DICOM_REQUEST
- Runs on every DICOM request processed by the device.
- DICOM_RESPONSE
- Runs on every DICOM response processed by the device.
Methods
- commitRecord(): void
- Sends a record to the configured recordstore on a
DICOM_REQUEST or DICOM_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.
- findElement(groupTag: Number, elementTag: Number): Buffer
- Returns a buffer that contains the DICOM data element specified by the passed group
and element tag numbers.
The data element is represented by a unique ordered pair of integers that represent the group tag and element tag numbers. For example, the ordered pair "0008, 0008" represents the "image type" element. A Registry of DICOM Data Elements and defined tags is available at dicom.nema.org.
- groupTag: Number
- The first number in the unique ordered pair of integers that represent a specific data element.
- elementTag: Number
- The second number in the unique ordered pair or integers that represent a specific data element.
Properties
- calledAETitle: String
- The application entity (AE) title of the destination device or program.
- callingAETitle: String
- The application entity (AE) title of the source device or program.
- elements: Array
- An array of presentation data values (PDV) command elements and data elements that comprise a DICOM message.
- error: String
- The detailed error message recorded by the ExtraHop system.
- isReqAborted: Boolean
- The value is true if the connection is closed before the DICOM
request is complete.
Access only on DICOM_REQUEST events; otherwise, an error will occur.
- isRspAborted: Boolean
- The value is true if the connection is closed before the DICOM
response is complete.
Access only on DICOM_RESPONSE events; otherwise, an error will occur.
- isSubOperation: Boolean
- The value is true if the timing metric on an L7 protocol message is not available because the primary request or response is not complete.
- methods: Array of Strings
- An array of command fields in the message. Each command field specifies a DIMSE operation name, such as N-CREATE-RSP.
- processingTime: Number
- The server processing time, expressed in milliseconds. The value is NaN on malformed and aborted responses or if the timing
is invalid.
Access only on DICOM_RESPONSE events; otherwise, an error will occur.
- record: Object
- The record object that can be sent to the configured recordstore through a call to
DICOM.commitRecord on either a DICOM_REQUEST or
DICOM_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:
DICOM_REQUEST DICOM_RESPONSE calledAETitle calledAETitle callingAETitle callingAETitle clientIsExternal clientIsExternal clientZeroWnd clientZeroWnd error error isReqAborted isRspAborted isSubOperation isSubOperation method method receiverIsExternal processingTime reqPDU receiverIsExternal reqSize rspPDU reqTransferTime rspSize senderIsExternal rspTransferTime serverIsExternal senderIsExternal serverZeroWnd serverIsExternal version serverZeroWnd  version - reqBytes: Number
- The number of L4 request bytes, excluding L4
headers.
Access only on DICOM_REQUEST events; otherwise, an error will occur.
- reqL2Bytes: Number
- The number of L2 request bytes, including L2 headers.
- reqPDU: String
- The Protocol Data Unit (PDU), or message format, of the request.
- reqPkts: Number
- The number of request packets.
- reqRTO: Number
- The number of request retransmission timeouts (RTOs).
- reqSize: Number
- The number of L7 request bytes.
Access only on DICOM_REQUEST events; otherwise, an error will occur.
- reqTransferTime: Number
- The request transfer time, expressed in milliseconds.
Access only on DICOM_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.
Access only on DICOM_RESPONSE events; otherwise, an error will occur.
- rspBytes: Number
- The number of L4 response bytes, excluding L4 protocol
overhead, such as ACKs, headers, and retransmissions.
Access only on DICOM_RESPONSE events; otherwise, an error will occur.
- rspL2Bytes: Number
- The number of L2 response bytes, including protocol overhead, such as headers.
- rspPDU: String
- The Protocol Data Unit (PDU), or message format, of the response.
Access only on DICOM_RESPONSE events; otherwise, an error will occur.
- rspPkts: Number
- The number of response packets.
- rspRTO: Number
- The number of response retransmission timeouts (RTOs).
- rspSize: Number
- The number of L7 response bytes.
Access only on DICOM_RESPONSE events; otherwise, an error will occur.
- rspTransferTime: Number
- The response transfer time, expressed in milliseconds.
Access only on DICOM_RESPONSE events; otherwise, an error will occur.
- rspZeroWnd: Number
- The number of zero windows in the response.
- version: Number
- The DICOM version number.
DNS
The DNS class enables you to store metrics and access properties on DNS_REQUEST and DNS_RESPONSE events.
Events
- DNS_REQUEST
- Runs on every DNS request processed by the device.
- DNS_RESPONSE
- Runs on every DNS response processed by the device.
Methods
- answersInclude(term: String | IPAddress): Boolean
- Returns true if the specified term is present in a DNS response. For
string terms, the method checks both the name and data record in the answer section of
the response. For IPAddress terms, the method checks
only the data record in the answer section.
Can be called only on DNS_RESPONSE events.
- commitRecord(): void
- Sends a record to the configured recordstore on a
DNS_REQUEST or DNS_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
- answers: Array
- An array of objects that correspond to answer resource records.
Access only on DNS_RESPONSE events; otherwise, an error will occur.
The objects contain the following properties:
- data: String | IPAddress
- The value of data depends on the type. The value is null for
unsupported record types. Supported record types include:
- A
- AAAA
- NS
- PTR
- CNAME
- MX
- SRV
- SOA
- TXT
- name: String
- The record name.
- ttl: Number
- The time-to-live value.
- type: String
- The DNS record type.
- typeNum: Number
- The numeric representation of the DNS record type.
- error: String
- The name of the DNS error code, in accordance with IANA DNS parameters.
Returns OTHER for error codes that are unrecognized by the system; however, errorNum specifies the numeric code value.
Access only on DNS_RESPONSE events; otherwise, an error will occur.
- errorNum: Number
- The numeric representation of the DNS error code in accordance with IANA DNS
parameters.
Access only on DNS_RESPONSE events; otherwise, an error will occur.
- isAuthenticData: Boolean
- The value is true if the response was validated through
DNSSEC.
Access only on DNS_RESPONSE events; otherwise, an error will occur.
- isAuthoritative: Boolean
- The value is true if the authoritative answer is set in the
response.
Access only on DNS_RESPONSE events; otherwise, an error will occur.
- isCheckingDisabled: Boolean
- The value is true if a response should be returned even though the
request could not be authenticated.
Access only on DNS_REQUEST events; otherwise, an error will occur.
- isDGADomain: Boolean
- The value is true if the domain of the server might have been generated by a domain generation algorithm (DGA). Some forms of malware produce large numbers of domain names with DGAs to hide command and control servers. The value is null if the domain was not suspicious.
- isRecursionAvailable: Boolean
- The value is true if the name server supports recursive
queries.
Access only on DNS_RESPONSE events; otherwise, an error will occur.
- isRecursionDesired: Boolean
- The value is true if the name server should perform the query
recursively.
Access only on DNS_REQUEST events; otherwise, an error will occur.
- isReqTimeout: Boolean
- The value is true if the request timed out.
Access only on DNS_REQUEST events; otherwise, an error will occur.
- isRspTruncated: Boolean
- The value is true if the response is truncated.
Access only on DNS_RESPONSE events; otherwise, an error will occur.
- opcode: String
- The name of the DNS operation code in accordance with IANA DNS parameters. The
following codes are recognized by the ExtraHop system:
OpCode Name 0 Query 1 IQuery (Inverse Query - Obsolete) 2 Status 3 Unassigned 4 Notify 5 Update 6-15 Unassigned Returns OTHER for codes that are unrecognized by the system; however, the opcodeNum property specifies the numeric code value.
- opcodeNum: Number
- The numeric representation of the DNS operation code in accordance with IANA DNS parameters.
- payload: Buffer
- The Buffer object containing the raw payload bytes of the event transaction.
- processingTime: Number
- The server processing time, expressed in bytes. The value is NaN on malformed and aborted responses or if the timing
is invalid.
Access only on DNS_RESPONSE events; otherwise, an error will occur.
- qname: String | null
- The hostname queried.
This value is null if the opcode property is UPDATE.
- qtype: String | null
- The name of the DNS request record type in accordance with IANA DNS parameters.
Returns OTHER for types that are unrecognized by the system; however, the qtypeNum property specifies the numeric type value.
This value is null if the opcode property is UPDATE.
- qtypeNum: Number | null
- The numeric representation of the DNS request record type in accordance with IANA DNS
parameters.
This value is null if the opcode property is UPDATE.
- record: Object
- The record object that can be sent to the configured recordstore through a call to
DNS.commitRecord() on either a DNS_REQUEST or
DNS_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:
DNS_REQUEST DNS_RESPONSE clientIsExternal answers clientZeroWnd clientIsExternal isCheckingDisabled clientZeroWnd isDGADomain error isRecursionDesired isAuthoritative isReqTimeout isCheckingDisabled opcode isDGADomain qname isRecursionAvailable qtype isRspTruncated receiverIsExternal opcode reqBytes processingTime reqL2Bytes receiverIsExternal reqPkts qname senderIsExternal qtype serverIsExternal rspBytes serverZeroWnd rspL2Bytes  rspPkts  senderIsExternal  serverIsExternal  serverZeroWnd - reqBytes: Number
- The number of L4 request bytes, excluding L4
headers.
Access only on DNS_REQUEST events; otherwise, an error will occur.
- reqL2Bytes: Number
- The number of L2 request bytes, including L2
headers.
Access only on DNS_REQUEST events; otherwise, an error will occur.
- reqPkts: Number
- The number of request packets.
Access only on DNS_REQUEST events; otherwise, an error will occur.
- rspBytes: Number
- The number of L4 response bytes, excluding L4 protocol
overhead, such as ACKs, headers, and retransmissions.
Access only on DNS_RESPONSE events; otherwise, an error will occur.
- reqZeroWnd: Number
- The number of zero windows in the request.
- rspL2Bytes: Number
- The number of L2 response bytes, including protocol overhead,
such as headers.
Access only on DNS_RESPONSE events; otherwise, an error will occur.
- rspPkts: Number
- The number of application-level response bytes.
Access only on DNS_RESPONSE events; otherwise, an error will occur.
- rspZeroWnd: Number
- The number of zero windows in the response.
- txId: Number
- The transaction ID of the DNS request or response.
- zname: String | null
- The DNS zone being updated.
This value is null if the opcode property is not UPDATE.
- ztype: String | null
- The type of DNS zone being updated. Returns OTHER for types that are
unrecognized by the system.
This value is null if the opcode property is not UPDATE.
- ztypeNum: Number | null
- The numeric representation of the DNS zone type.
This value is null if the opcode property is not UPDATE.
FIX
The FIX class enables you to store metrics and access properties on FIX_REQUEST and FIX_RESPONSE events.
Events
- FIX_REQUEST
- Runs on every FIX request processed by the device.
- FIX_RESPONSE
- Runs on every FIX response processed by the device.
Note: | The FIX_RESPONSE event is matched with a request based on order ID. There is no one-to-one correlation between request and response. There might be requests without a response, and sometimes data is pushed to the client, which limits request data availability on response event. However, you can invoke the session table to solve complex scenarios such as submission order id. |
Methods
- commitRecord(): void
- Sends a record to the configured recordstore on either a
FIX_REQUEST or FIX_RESPONSE event.
The event determines which properties are committed to the record object. To view the default properties committed for 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
- fields: Array
- A list of FIX fields. Because they are text-based, the key-value protocol fields are
exposed as an array of objects with name and value properties containing strings. For
example:
8=FIX.4.2<SOH>9=233<SOH>35=G<SOH>34=206657...
translates to:
{"BeginString": "FIX.4.2", "BodyLength": "233", "MsgType": "G", "MsgSeqNum": "206657"}
Key string representation is translated, if possible. With extensions, a numeric representation is used. For example, it is not possible to determine 9178=0 (as seen in actual captures). The key is instead translated to "9178". Fields are extracted after message length and version fields are extracted all the way to the checksum (last field). The checksum is not extracted.
In the following example, the trigger debug(JSON.stringify(FIX.fields)); shows the following fields:
[ {"name":"MsgType","value":"0"}, {"name":"MsgSeqNum","value":"2"}, {"name":"SenderCompID","value":"AA"}, {"name":"SendingTime","value":"20140904-03:49:58.600"}, {"name":"TargetCompID","value":"GG"} ]
To debug and print all FIX fields, enable debugging on the trigger and enter the following code:
var fields = ''; for (var i = 0; i < FIX.fields.length; i++) { fields += '"' + FIX.fields[i].name + '" : "' + FIX.fields[i].value + '"\n'; } debug(fields);
The following output is display in the trigger's Debug Log:
"MsgType" : "5" "MsgSeqNum" : "3" "SenderCompID" : "GRAPE" "SendingTime" : "20140905-00:10:23.814" "TargetCompID" : "APPLE"
- msgType: String
- The value of the MessageCompID key.
- processingTime: Number
- The server processing time, expressed in milliseconds. The value is
NaN if the timing is invalid.
Access only on FIX_RESPONSE events; otherwise, an error will occur.
- record: Object
- The record object that can be sent to the configured recordstore through a call to
FIX.commitRecord on either a FIX_REQUEST or
FIX_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:
FIX_REQUEST FIX_RESPONSE clientIsExternal clientIsExternal clientZeroWnd clientZeroWnd msgType msgType receiverIsExternal receiverIsExternal reqBytes rspBytes reqL2Bytes rspL2Bytes reqPkts rspPkts reqRTO rspRTO sender sender senderIsExternal senderIsExternal serverIsExternal serverIsExternal serverZeroWnd serverZeroWnd target target version version - 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).
- reqZeroWnd: Number
- The number of zero windows in the request.
- 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).
- rspZeroWnd: Number
- The number of zero windows in the response.
- sender: String
- The value of the SenderCompID key.
- target: String
- The value of the TargetCompID key.
- version: String
- The protocol version.
FTP
The FTP class enables you to store metrics and access properties on FTP_REQUEST and FTP_RESPONSE events.
Events
- FTP_REQUEST
- Runs on every FTP request processed by the device.
- FTP_RESPONSE
- Runs on every FTP response processed by the device.
Methods
- commitRecord(): void
- Sends a record to the configured recordstore on an
FTP_RESPONSE event. Record commits on FTP_REQUEST
events are not supported.
To view the default properties committed to the record object, 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
- args: String
- The arguments to the command.
Access only on FTP_RESPONSE events; otherwise, an error will occur.
- cwd: String
- In the case of a user at /, when the client sends "CWD subdir":
- The value is / when method == "CWD".
- The value is /subdir for subsequent commands (rather than CWD becoming the changed to directory as part of the CWD response trigger).
Includes "..." at the beginning of the path in the event of a resync or the path is truncated.
Includes "..." at the end of the path if the path is too long. Path truncates at 4096 characters.
Access only on FTP_RESPONSE events; otherwise, an error will occur.
- error: string
- The detailed error message recorded by the ExtraHop system.
Access only on FTP_RESPONSE events; otherwise, an error will occur.
- isReqAborted: Boolean
- The value is true the connection is closed before the FTP request was complete.
- isRspAborted: Boolean
- The value is true if the connection is closed before the FTP response
was complete.
Access only on FTP_RESPONSE events; otherwise, an error will occur.
- method: String
- The FTP method.
- path: String
- The path for FTP commands. Includes "..." at the beginning of the path in the event of
a resync or the path is truncated. Includes "..." at the end of the path if the path is
too long. Path truncates at 4096 characters.
Access only on FTP_RESPONSE events; otherwise, an error will occur.
- processingTime: Number
- The server processing time, expressed in milliseconds (equivalent to
rspTimeToFirstPayload - reqTimeToLastByte). The
value is NaN on malformed and aborted
responses or if the timing is invalid.
Access only on FTP_RESPONSE events; otherwise, an error will occur.
- record: Object
- The record object that can be sent to the configured recordstore through a call to
FTP.commitRecord() on an FTP_RESPONSE event.
The default record object can contain the following properties:
- args
- clientIsExternal
- clientZeroWnd
- cwd
- error
- isReqAborted
- isRspAborted
- method
- path
- processingTime
- receiverIsExternal
- reqBytes
- reqL2Bytes
- reqPkts
- reqRTO
- roundTripTime
- rspBytes
- rspL2Bytes
- rspPkts
- rspRTO
- senderIsExternal
- serverIsExternal
- serverZeroWnd
- statusCode
- transferBytes
- user
Access the record object only on FTP_RESPONSE events; otherwise, an error will occur.
- reqBytes: Number
- The number of L4 request bytes, excluding L4
headers.
Access only on FTP_RESPONSE events; otherwise, an error will occur.
- reqL2Bytes: Number
- The number of L2 request bytes, including L2
headers.
Access only on FTP_RESPONSE events; otherwise, an error will occur.
- reqPkts: Number
- The number of request packets.
Access only on FTP_RESPONSE events; otherwise, an error will occur.
- reqRTO: Number
- The number of request retransmission
timeouts (RTOs).
Access only on FTP_RESPONSE 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.
Access only on FTP_RESPONSE events; otherwise, an error will occur.
- rspBytes: Number
- The number of L4 response bytes, excluding L4 protocol
overhead, such as ACKs, headers, and retransmissions.
Access only on FTP_RESPONSE events; otherwise, an error will occur.
- rspL2Bytes: Number
- The number of L2 response bytes, including protocol overhead,
such as headers.
Access only on FTP_RESPONSE events; otherwise, an error will occur.
- rspPkts: Number
- The number of response packets.
Access only on FTP_RESPONSE events; otherwise, an error will occur.
- rspRTO: Number
- The number of response retransmission
timeouts (RTOs).
Access only on FTP_RESPONSE events; otherwise, an error will occur.
- rspZeroWnd: Number
- The number of zero windows in the response.
- statusCode: Number
- The FTP status code of the response.
Access only on FTP_RESPONSE events; otherwise, an error will occur.
The following codes are valid:
Code Description 110 Restart marker replay. 120 Service ready in nnn minutes. 125 Data connection already open; transfer starting. 150 File status okay; about to open data connection. 202 Command not implemented, superfluous at this site. 211 System status, or system help reply. 212 Directory status. 213 File status. 214 Help message. 215 NAME system type. 220 Service ready for new user. 221 Service closing control connection. 225 Data connection open; no transfer in progress. 226 Closing data connection. Requested file action successful. 227 Entering Passive Mode. 228 Entering Long Passive Mode. 229 Entering Extended Passive Mode. 230 User logged in, proceed. Logged out if appropriate. 231 User logged out; service terminated. 232 Logout command noted, will complete when transfer done 250 Requested file action okay, completed. 257 "PATHNAME" created. 331 User name okay, need password. 332 Need account for login. 350 Requested file action pending further information. 421 Service not available, closing control connection. 425 Can't open data connection. 426 Connection closed; transfer aborted. 430 Invalid username or password. 434 Requested host unavailable. 450 Requested file action not taken. 451 Requested action aborted. Local error in processing. 452 Requested action not taken. 501 Syntax error in parameters or arguments. 502 Command not implemented. 503 Bad sequence of commands. 504 Command not implemented for that parameter. 530 Not logged in. 532 Need account for storing files. 550 Requested action not taken. File unavailable. 551 Requested action aborted. Page type unknown. 552 Requested file action aborted. Exceeded storage allocation. 553 Requested action not taken. File name not allowed. 631 Integrity protected reply. 632 Confidentiality and integrity protected reply. 633 Confidentiality protected reply. 10054 Connection reset by peer. 10060 Cannot connect to remote server. 10061 Cannot connect to remote server. The connection is active refused. 10066 Directory not empty. 10068 Too many users, server is full. - transferBytes: Number
- The number of bytes transferred over the data channel during an
FTP_RESPONSE event.
Access only on FTP_RESPONSE events; otherwise, an error will occur.
- user: String
- The user name, if available. In some cases, such as when login events are encrypted, the user name is not available.
HL7
The HL7 class enables you to store metrics and access properties on HL7_REQUEST and HL7_RESPONSE events.
Events
- HL7_REQUEST
- Runs on every HL7 request processed by the device.
- HL7_RESPONSE
- Runs on every HL7 response processed by the device.
Methods
- commitRecord(): void
- Sends a record to the configured recordstore on an
HL7_RESPONSE event. Record commits on HL7_REQUEST
events are not supported.
To view the default properties committed to the record object, 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
- ackCode: String
- The two character acknowledgment code.
Access only on HL7_RESPONSE events; otherwise, an error will occur.
- ackId: String
- The identifier for the message being acknowledged.
Access only on HL7_RESPONSE events; otherwise, an error will occur.
- msgId: String
- The unique identifier for this message.
- msgType: String
- The entire message type field, including the msgId subfield.
- processingTime: Number
- The server processing time, expressed in milliseconds. The value is NaN on malformed and aborted responses or if the timing
is invalid.
Access only on HL7_RESPONSE events; otherwise, an error will occur.
- record: Object
- The record object that can be sent to the configured recordstore through a call to
HL7.commitRecord() on an HL7_RESPONSE event.
The default record object can contain the following properties:
- ackCode
- ackId
- clientIsExternal
- clientZeroWnd
- msgId
- msgType
- receiverIsExternal
- roundTripTime
- processingTime
- senderIsExternal
- serverIsExternal
- serverZeroWnd
- version
Access the record object only on HL7_RESPONSE 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.
Access only on HL7_RESPONSE events; otherwise, an error will occur.
- rspZeroWnd: Number
- The number of zero windows in the response.
- segments: Array
- An array of segment objects with the following fields:
- name: String
- The name of the segment.
- fields: Array of Strings
- The segment field values. Because the indices of the array start at 0, and HL7
field numbers start at 1, the index is the HL7 field number minus 1. For example,
to select field 16 of a PRT segment (the participation device ID), specify 15, as
shown in the following example
code:
HL7.segments[5].fields[15]
Note: If a segment is blank, the array contains an empty string at the segment index.
- subfieldDelimiter: String
- Supports non-standard field delimiters.
- version: String
- The version advertised in the MSH segment.
Note: | The amount of buffered data is limited by the following capture option: ("message_length_max": number) |
HTTP
The HTTP class enables you to store metrics and access properties on HTTP_REQUEST and HTTP_RESPONSE events.
Events
- HTTP_REQUEST
- Runs on every HTTP request processed by the device.
- HTTP_RESPONSE
- Runs on every HTTP response processed by the device.
Additional payload options are available when you create a trigger that runs on either of these events. See Advanced trigger options for more information.
Methods
- commitRecord(): void
- Sends a record to the configured recordstore on an HTTP_REQUEST or
HTTP_RESPONSE event. To view the default properties committed to the
record object, see the record property below.
If the commitRecord() method is called on an HTTP_REQUEST event, the record is not created until the HTTP_RESPONSE event runs. If the commitRecord() method is called on both the HTTP_REQUEST and the corresponding HTTP_RESPONSE, only one record is created for request and response, even if the commitRecord() method is called multiple times on the same trigger events.
- findHeaders(name: String): Array
- Enables access to HTTP header values and returns an array of header objects (with name and value properties) where the names match the prefix of the string value. See Example: Access HTTP header attributes for more information.
- parseQuery(String): Object
- Accepts a query string and returns an object with names and values corresponding to
those in the query string as shown in the following
example:
var query = HTTP.parseQuery(HTTP.query); debug("user id: " + query.userid);
Note: If the query string contains repeated keys, the corresponding values are returned in an array. For example, the query string event_type=status_update_event&event_type=api_post_event returns the following object: { "event_type": ["status_update_event", "api_post_event"] }
Properties
- age: Number
- For HTTP_REQUEST events, the time from the first byte of the request until the last seen byte of the request. For HTTP_RESPONSE events, the time from the first byte of the request until the last seen byte of the response. The time is expressed in milliseconds. Specifies a valid value on malformed and aborted requests. The value is NaN on expired requests and responses, or if the timing is invalid.
- contentType: String
- The value of the content-type HTTP header.
- cookies: Array
- An array of objects that represents cookies and contains properties such as "domain"
and "expires." The properties correspond to the attributes of each cookie as shown in
the following
example:
var cookies = HTTP.cookies, cookie, i; for (i = 0; i < cookies.length; i++) { cookie = cookies[i]; if (cookie.domain) { debug("domain: " + cookie.domain); } }
- encryptionProtocol: String
- The protocol that the transaction is encrypted with.
- headers: Object
- An array-like object that enables access to HTTP header names and values. Header
information is available through one of the following properties:
- length: Number
- The number of headers.
- string property:
- The name of the header, accessible in a dictionary-like fashion, as shown in the
following
example:
var headers = HTTP.headers; session = headers["X-Session-Id"]; accept = headers.accept;
- numeric property:
- Corresponds to the order in which the headers appear on the wire. The returned
object has a name and a value property. Numeric properties are useful for
iterating over all the headers and disambiguating headers with duplicate names as
shown in the following
example:
var headers = HTTP.headers; for (i = 0; i < headers.length; i++) { hdr = headers[i]; debug("headers[" + i + "].name: " + hdr.name); debug("headers[" + i + "].value: " + hdr.value); }
Note: Saving HTTP.headers to the Flow store does not save all of the individual header values. It is a best practice to save the individual header values to the Flow store. Refer to the Flow class section for details.
- headersRaw: String
- The unmodified block of HTTP headers, expressed as a string.
- host: String
- The value in the HTTP host header.
- isDesync: Boolean
- The value is true if the protocol parser became desynchronized due to missing packets.
- isEncrypted: Boolean
- The value is true if the transaction is over secure HTTP.
- isDecrypted: Boolean
- The value is true if the ExtraHop system securely decrypted and analyzed the transaction. Decrypted traffic analysis can expose advanced threats that hide within encrypted traffic.
- isPipelined: Boolean
- The value is true if the transaction is pipelined.
- isReqAborted: Boolean
- The value is true if the connection is closed before the HTTP request was complete.
- isRspAborted: Boolean
- The value is true if the connection is closed before the HTTP
response was complete.
Access only on HTTP_RESPONSE events; otherwise, an error will occur.
- isRspChunked: Boolean
- The value is true if the response is chunked.
Access only on HTTP_RESPONSE events; otherwise, an error will occur.
- isRspCompressed: Boolean
- The value is true if the response is compressed.
Access only on HTTP_RESPONSE events; otherwise, an error will occur.
- isServerPush: Boolean
- The value is true if the transaction is the result of a server push.
- isSQLi: Boolean
- The value is true if the request included one or more suspicious SQL fragments. These fragments indicate a potential SQL injection (SQLi). SQLi is a technique where an attacker can access and tamper with data by inserting malicious SQL statements into a SQL query.
- isXSS: Boolean
- The value is true if the HTTP request included potential cross-site scripting (XSS) attempts. A successful XSS attempt can inject a malicious client-side script or payload into a trusted website or application. When a victim visits the website, the malicious script is then injected into the victim's browser.
- method: String
- The HTTP method of the transaction such as POST and GET.
- origin: IPAddress | String
- The value in the X-Forwarded-For or the true-client-ip header.
- path: String
- The path portion of the URI: /path/.
- payload: Buffer | null
- The Buffer object containing the raw payload bytes
of the event transaction. If the payload was compressed, the decompressed content is
returned.
The buffer contains the N first bytes of the payload, where N is the number of payload bytes specified by the Bytes to Buffer field when the trigger was configured through the ExtraHop WebUI. The default number of bytes is 2048. For more information, see Advanced trigger options.
The following script is an example of HTTP payload analysis:
// Extract the user name based on a pattern "user=*&" from payload // of a login URI that has "auth/login" as a URI substring. if (HTTP.payload && /auth\/login/i.test(HTTP.uri)) { var user = /user=(.*?)\&/i.exec(HTTP.payload); if (user !== null) { debug("user: " + user[1]); } }
Note: If two HTTP payload buffering triggers are assigned to the same device, the higher value is selected and the value of HTTP.payload is the same for both triggers. - processingTime: Number
- The server processing time, expressed in milliseconds (equivalent to
rspTimeToFirstPayload - reqTimeToLastByte). The
value is NaN on malformed and aborted
responses or if the timing is invalid.
Access only on HTTP_RESPONSE events; otherwise, an error will occur.
- query: String
- The query string portion of the URI: query=string. This typically follows the URL and is separated from it by a question mark. Multiple query strings are separated by an ampersand (&) or semicolon (;) delimiter.
- record: Object
- The record object that can be sent to the configured recordstore through a call to
HTTP.commitRecord().
The default record object can contain the following properties:
- clientIsExternal
- clientZeroWnd
- contentType
- host
- isPipelined
- isReqAborted
- isRspAborted
- isRspChunked
- isRspCompressed
- method
- origin
- query
- receiverIsExternal
- referer
- reqBytes
- reqL2Bytes
- reqPkts
- reqRTO
- reqSize
- reqTimeToLastByte
- roundTripTime
- rspBytes
- rspL2Bytes
- rspPkts
- rspRTO
- rspSize
- rspTimeToFirstHeader
- rspTimeToFirstPayload
- rspTimeToLastByte
- rspVersion
- senderIsExternal
- serverIsExternal
- serverZeroWnd
- statusCode
- thinkTime
- title
- processingTime
- uri
- userAgent
Access the record object only on HTTP_RESPONSE events; otherwise, an error will occur.
- referer: String
- The value in the HTTP referrer header.
- reqBytes: Number
- The number of L4 request bytes, excluding L4
headers.
Access only on HTTP_RESPONSE events; otherwise, an error will occur.
- reqL2Bytes: Number
- The number of L2 request bytes, including L2
headers.
Access only on HTTP_RESPONSE events; otherwise, an error will occur.
- reqPkts: Number
- The number of request packets.
Access only on HTTP_RESPONSE events; otherwise, an error will occur.
- reqRTO: Number
- The number of request retransmission
timeouts (RTOs).
Access only on HTTP_RESPONSE events; otherwise, an error will occur.
- reqSize: Number
- The number of L7 request bytes, excluding HTTP headers.
- reqTimeToLastByte: Number
- The time from the first byte of the request until the last byte of the request, expressed in milliseconds. The value is NaN on expired requests and responses, or if the timing is invalid.
- reqZeroWnd: Number
- The number of zero windows in the request.
- roundTripTime: Number
- The median TCP round trip time (RTT), expressed in milliseconds. The value is
NaN if there are no RTT samples.
Access only on HTTP_RESPONSE events; otherwise, an error will occur.
- rspBytes: Number
- The number of L4 response bytes, excluding L4 protocol
overhead, such as ACKs, headers, and retransmissions.
Access only on HTTP_RESPONSE events; otherwise, an error will occur.
- rspL2Bytes: Number
- The number of L2 response bytes, including protocol overhead,
such as headers.
Access only on HTTP_RESPONSE events; otherwise, an error will occur.
- rspPkts: Number
- The number of response packets.
Access only on HTTP_RESPONSE events; otherwise, an error will occur.
- rspRTO: Number
- The number of response retransmission
timeouts (RTOs).
Access only on HTTP_RESPONSE events; otherwise, an error will occur.
- rspSize: Number
Thank you for your feedback. Can we contact you to ask follow up questions?