ExtraHop v2.0.0

About the connector

ExtraHop Reveal(x) network detection and response automatically discovers and classifies every transaction, session, device, and asset in your enterprise. ExtraHop helps organizations understand and secure their environments by analyzing all network interactions in real-time and leveraging machine learning to identify threats, deliver critical applications, and secure investments in the hybrid cloud.

This document provides information about the ExtraHop Connector, which facilitates automated interactions, with an ExtraHop server using FortiSOAR™ playbooks. Add the ExtraHop Connector as a step in FortiSOAR™ playbooks and perform automated operations such as retrieving alerts from ExtraHop, querying log records in ExtraHop, updating watchlists in ExtraHop, etc.

Version information

Connector Version: 2.0.0

FortiSOAR™ Version Tested on: 7.4.1-3167

ExtraHop Reveal(x) Version tested on: 9.4.2.1625

Authored By: Fortinet

Contributor: Parag Khatavkar

Certified: Yes

Release Notes for version 2.0.0

The following enhancements have been made to the ExtraHop connector in version 2.0.0:

• Certified this version of the connector.
• Added the following actions and playbooks:
  • Get Detections
  • Get Detection By ID
  • Get Detection Formats
  • Create New Detection Format
  • Update Detection Format
  • Delete Detection Format
  • Update Associated Ticket
  • Get Detection Hiding Rules
• Enhanced the 'Create Alert' action as follows:
  • Made the following input parameters mandatory: Statistic Name, Field OP, Operator, Operand, Field Name, Param, Field Name2, Param2, Interval Length, Units, Object Type, and CC.
  • Changed the field type of Param and Param2 input parameters from 'text' to 'JSON'.
• Enhanced the 'Update Alert' action by changing the field type of Param and Param2 input parameters from 'text' to 'JSON'.
• Enhanced the 'Query Records' action as follows:
  • Added a new parameter named "Filter" in which you can choose between the "Filter" or "Conditional Filter" options.
    • The Field, Operator, and Operand are now mandatory input parameters and have been moved under "Filter".
    • The Conditional Operator and Condition are now mandatory input parameters and have been moved under "Conditional Filter".
  • Made the "Order" parameter mandatory, when the "Sort" input parameter is selected.
  • Removed the "Use Conditional Filters" input parameter.
• Enhanced the 'Search Devices' action as follows:
  • Added a new parameter named "Filter" in which you can choose between the "Filter" or "Conditional Filter" options.
    • The Field, Operator, and Operand are now mandatory input parameters and have been moved under "Filter". Additionally, new options are added under the 'Field' and 'Operator' input parameters.
    • The Conditional Operator and Condition are now mandatory input parameters and have been moved under "Conditional Filter".
  • Removed the "Use Conditional Filters" input parameter.
• Made the "Resolution" input parameter mandatory in the "Update Detection" action.
• Made the "From" input parameter mandatory in the "Get Peers Devices" action.
• Made the "From" input parameter mandatory in the "Get Protocols" action. Additionally, renamed the "Device IDs" input parameter to "Device ID".
• Enhanced the 'Search Packet' action as follows:
  • Added new parameters named "From" and "Until".
  • Added a new option named “pcapng” to the "File Format" input parameter.
• Updated the output schema for the "Get Watchlist" action.
• Updated the annotation for the "Create Tag" action from 'tag_tag' to 'create_tag'.
• Fixed the 'The JSON payload specified in the request is invalid' issue that caused failure of multiple actions.

Installing the connector

Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.

You can also use the yum command as a root user to install the connector:
yum install cyops-connector-extrahop

Prerequisites to configuring the connector

• You must have the URL of the ExtraHop server to which you will connect and perform automated operations, and the API key used to access the ExtraHop Reveal(x) APIs.
• The FortiSOAR™ server should have outbound connectivity to port 443 on the ExtraHop server.

Minimum Permissions Required

• Not Applicable

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Content Hub page, click the Manage tab, and then click the ExtraHop connector card. On the connector popup, click the Configurations tab to enter the required configuration details:

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations from FortiSOAR™ onwards:

operation: Get Alerts

Input parameters

None.

Output

The output contains the following populated JSON schema:

[
    {
        "apply_all": "",
        "author": "",
        "categories": [],
        "cc": [],
        "description": "",
        "disabled": "",
        "field_name": "",
        "field_name2": "",
        "field_op": "",
        "id": "",
        "interval_length": "",
        "mod_time": "",
        "name": "",
        "notify_snmp": "",
        "object_type": "",
        "operand": "",
        "operator": "",
        "param": {},
        "param2": {},
        "protocols": [],
        "refire_interval": "",
        "severity": "",
        "stat_name": "",
        "type": "",
        "units": ""
    }
]

operation: Get Alert Details

Input parameters

Output

The output contains the following populated JSON schema:

{
    "apply_all": "",
    "author": "",
    "categories": [],
    "cc": [],
    "description": "",
    "disabled": "",
    "field_name": "",
    "field_name2": "",
    "field_op": "",
    "id": "",
    "interval_length": "",
    "mod_time": "",
    "name": "",
    "notify_snmp": "",
    "object_type": "",
    "operand": "",
    "operator": "",
    "param": {},
    "param2": {},
    "protocols": [],
    "refire_interval": "",
    "severity": "",
    "stat_name": "",
    "type": "",
    "units": ""
}

operation: Create Alert

Input parameters

Output

The output contains the following populated JSON schema:

{
    "success": "",
    "result": ""
}

operation: Update Alert

Input parameters

Output

The output contains the following populated JSON schema:

{
    "success": "",
    "result": ""
}

operation: Query Records

Input parameters

Output

The output contains the following populated JSON schema:

{
    "apply_all": "",
    "author": "",
    "categories": [],
    "cc": [],
    "description": "",
    "disabled": "",
    "field_name": "",
    "field_name2": "",
    "field_op": "",
    "id": "",
    "interval_length": "",
    "mod_time": "",
    "name": "",
    "notify_snmp": "",
    "object_type": "",
    "operand": "",
    "operator": "",
    "param": {},
    "param2": {},
    "protocols": [],
    "refire_interval": "",
    "severity": "",
    "stat_name": "",
    "type": "",
    "units": ""
}

operation: Search Devices

Input parameters

Output

The output contains the following populated JSON schema:

{
    "activity": [],
    "analysis": "",
    "analysis_level": "",
    "auto_role": "",
    "cdp_name": "",
    "cloud_account": "",
    "cloud_instance_id": "",
    "cloud_instance_name": "",
    "cloud_instance_type": "",
    "critical": "",
    "custom_criticality": "",
    "custom_name": "",
    "custom_type": "",
    "default_name": "",
    "description": "",
    "device_class": "",
    "dhcp_name": "",
    "discover_time": "",
    "discovery_id": "",
    "display_name": "",
    "dns_name": "",
    "extrahop_id": "",
    "id": "",
    "ipaddr4": "",
    "ipaddr6": "",
    "is_l3": "",
    "last_seen_time": "",
    "macaddr": "",
    "mod_time": "",
    "model": "",
    "netbios_name": "",
    "node_id": "",
    "on_watchlist": "",
    "parent_id": "",
    "role": "",
    "subnet_id": "",
    "user_mod_time": "",
    "vendor": "",
    "vlanid": "",
    "vpc_id": ""
}

operation: Get Watchlist

Input parameters

None.

Output

The output contains the following populated JSON schema:

[
    {
        "activity": [],
        "analysis": "",
        "analysis_level": "",
        "auto_role": "",
        "cdp_name": "",
        "cloud_account": "",
        "cloud_instance_description": "",
        "cloud_instance_id": "",
        "cloud_instance_name": "",
        "cloud_instance_type": "",
        "critical": "",
        "custom_criticality": "",
        "custom_make": "",
        "custom_model": "",
        "custom_name": "",
        "custom_type": "",
        "default_name": "",
        "description": "",
        "device_class": "",
        "dhcp_name": "",
        "discover_time": "",
        "discovery_id": "",
        "display_name": "",
        "dns_name": "",
        "extrahop_id": "",
        "id": "",
        "ipaddr4": "",
        "ipaddr6": "",
        "is_l3": "",
        "last_seen_time": "",
        "macaddr": "",
        "mod_time": "",
        "model": "",
        "model_override": "",
        "netbios_name": "",
        "node_id": "",
        "on_watchlist": "",
        "parent_id": "",
        "role": "",
        "subnet_id": "",
        "user_mod_time": "",
        "vendor": "",
        "vlanid": "",
        "vpc_id": ""
    }
]

operation: Update Watchlist

Input parameters

Output

The output contains the following populated JSON schema:

{
    "status": "",
    "result": ""
}

operation: Update Detection

Input parameters

Output

The output contains the following populated JSON schema:

{
    "status": "",
    "result": ""
}

operation: Get Peers Devices

Input parameters

Output

The output contains the following populated JSON schema:

[
    {
        "analysis": "",
        "analysis_level": "",
        "auto_role": "",
        "client_protocols": [],
        "default_name": "",
        "device_class": "",
        "dhcp_name": "",
        "discover_time": "",
        "discovery_id": "",
        "display_name": "",
        "dns_name": "",
        "extrahop_id": "",
        "id": "",
        "ppaddr4": "",
        "is_l3": "",
        "macaddr": "",
        "mod_time": "",
        "on_watchlist": "",
        "parent_id": "",
        "role": "",
        "server_protocols": [],
        "url": "",
        "user_mod_time": "",
        "vendor": "",
        "vlanid": ""
    }
]

operation: Get Protocols

Input parameters

Output

The output contains the following populated JSON schema:

[
    {
        "analysis": "",
        "analysis_level": "",
        "auto_role": "",
        "client_protocols": [],
        "default_name": "",
        "device_class": "",
        "dhcp_name": "",
        "discover_time": "",
        "discovery_id": "",
        "display_name": "",
        "dns_name": "",
        "extrahop_id": "",
        "id": "",
        "ppaddr4": "",
        "is_l3": "",
        "macaddr": "",
        "mod_time": "",
        "on_watchlist": "",
        "parent_id": "",
        "role": "",
        "server_protocols": [],
        "url": "",
        "user_mod_time": "",
        "vendor": "",
        "vlanid": ""
    }
]

operation: Tag Devices

Input parameters

Output

The output contains the following populated JSON schema:

{
    "apply_all": "",
    "author": "",
    "categories": [],
    "cc": [],
    "description": "",
    "disabled": "",
    "field_name": "",
    "field_name2": "",
    "field_op": "",
    "id": "",
    "interval_length": "",
    "mod_time": "",
    "name": "",
    "notify_snmp": "",
    "object_type": "",
    "operand": "",
    "operator": "",
    "param": {},
    "param2": {},
    "protocols": [],
    "refire_interval": "",
    "severity": "",
    "stat_name": "",
    "type": "",
    "units": ""
}

operation: Create Tag

Input parameters

Output

The output contains the following populated JSON schema:

{
    "status": "",
    "result": ""
}

operation: Search Packet

Input parameters

Output

The output contains a non-dictionary value.

operation: Get Detections

Input parameters

None.

Output

The output contains the following populated JSON schema:

{
    "appliance_id": "",
    "assignee": "",
    "categories": [
        ""
    ],
    "description": "",
    "end_time": "",
    "id": "",
    "is_user_created": "",
    "mitre_tactics": [],
    "mitre_techniques": [],
    "mod_time": "",
    "participants": [],
    "properties": "",
    "resolution": "",
    "risk_score": "",
    "start_time": "",
    "status": "",
    "ticket_id": "",
    "ticket_url": "",
    "title": "",
    "type": "",
    "update_time": ""
}

operation: Get Detection By ID

Input parameters

Output

The output contains the following populated JSON schema:

{
    "appliance_id": "",
    "assignee": "",
    "categories": [],
    "description": "",
    "end_time": "",
    "id": "",
    "is_user_created": "",
    "mitre_tactics": [],
    "mitre_techniques": [],
    "mod_time": "",
    "participants": [],
    "properties": "",
    "resolution": "",
    "risk_score": "",
    "start_time": "",
    "status": "",
    "ticket_id": "",
    "ticket_url": "",
    "title": "",
    "type": "",
    "update_time": ""
}

operation: Get Detection Formats

Input parameters

None.

Output

The output contains the following populated JSON schema:

{
    "author": "",
    "categories": [],
    "display_name": "",
    "is_user_created": "",
    "mitre_categories": [],
    "properties": "",
    "type": ""
}

operation: Create New Detection Format

Input parameters

Output

The output contains the following populated JSON schema:

{
    "author": "",
    "categories": [],
    "display_name": "",
    "is_user_created": "",
    "mitre_categories": [],
    "properties": "",
    "type": ""
}

operation: Delete Detection Format

Input parameters

Output

The output contains the following populated JSON schema:

{
    "status": "",
    "result": ""
}

operation: Get Detection Hiding Rules

Input parameters

None.

Output

The output contains the following populated JSON schema:

{
    "author": "",
    "create_time": "",
    "description": "",
    "detection_type": "",
    "detections_hidden": "",
    "enabled": "",
    "expiration": "",
    "hide_past_detections": "",
    "id": "",
    "offender": "",
    "participants_hidden": "",
    "properties": [],
    "victim": ""
}

operation: Update Detection Format

Input parameters

Output

The output contains the following populated JSON schema:

{
    "status": "",
    "result": ""
}

operation: Update Associated Ticket

Input parameters

Output

The output contains the following populated JSON schema:

{
    "author": "",
    "categories": [],
    "display_name": "",
    "is_user_created": "",
    "mitre_categories": [],
    "properties": "",
    "type": ""
}

Included playbooks

The Sample - ExtraHop - 2.0.0 playbook collection comes bundled with the ExtraHop connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the ExtraHop connector.

• Create Alert
• Create New Detection Format
• Create Tag
• Delete Detection Format
• Get Alert Details
• Get Alerts
• Get Detection By ID
• Get Detection Formats
• Get Detection Hiding Rules
• Get Detections
• Get Peers Devices
• Get Protocols
• Get Watchlist
• Query Records
• Search Devices
• Search Packet
• Tag Devices
• Update Alert
• Update Associated Ticket
• Update Detection
• Update Detection Format
• Update Watchlist

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets overwritten during the connector upgrade and gets deleted during connector uninstall.