ExtraHop REST API Guide

Activity groups classify devices automatically based on their network traffic.

You can retrieve IDs for all activity groups and then perform additional operations on a group that is associated with a single ID.

For example, activity group IDs can be added to Metric queries to retrieve metrics simultaneously for a group of devices.

For more information, see Activity groups.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

An activity map is a dynamic visual representation of the L4-L7 protocol activity between devices in your network. Create a 2D or 3D layout of device connections in real-time to learn about the traffic flow and relationships between devices.

Here are some important considerations about activity maps:

• Any device, including custom devices, can appear in an activity map. However, L2 devices, custom devices, and devices in limited analysis cannot be the origin of an activity map. You can only create activity maps for active devices with L4-L7 protocol metrics associated with them. This protocol activity is the basis for creating the first step of the connection.
• Active L3 devices without any protocol activity for the selected time interval cannot be viewed in an activity map. Change the time interval or your device selections and try again.
• You can create an activity map in a Command appliance to view device connections across all of your Discover appliances. However, connected Discover appliances must be upgraded to firmware version 7.0.

To learn about configuring and navigating activity maps, see Activity maps concepts.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Alerts are system notifications that are generated upon specified alert criteria. Default alerts are available in the system, or you can create a custom alert.

Anomaly and threshold alerts can be set to alert you if a metric crosses the value defined in the alert. Trend alerts cannot be configured through the REST API.

For more information, see Alerts concepts.

The following table displays all of the operations you can perform this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

An API key enables a user to perform operations through the ExtraHop REST API.

You can generate the initial API key for the setup user account through the REST API. All other API keys are generated through the API Access page in the ExtraHop Admin UI.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

The ExtraHop system consists of a network of connected appliances that perform tasks such as monitoring traffic, analyzing data, storing data, and detecting anomalies.

You can retrieve information about ExtraHop appliances connected to the local appliance and establish new connections to remote ExtraHop appliances.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Applications are user-defined groups that collect metrics identified through triggers across multiple types of traffic.

The default All Activity application contains all collected metrics.

The following table displays all of the operations you can perform on the application resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

The audit log displays a record of all recorded system administration and configuration activity, such as the time of the activity, the user who performed the activity, the operation, operation details, and system component..

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Bundles are JSON-formatted documents that contain information about selected system configuration, such as triggers, dashboards, applications, or alerts.

You can create a bundle and then transfer those configurations to another ExtraHop appliance, or save the bundle as a backup. Bundles can also be downloaded from ExtraHop Solution Bundles and applied through the REST API.

For more information, see Bundles concepts.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

You can create a custom device by defining a set of rules.

For example, you can create a custom device that has an IP address on a specified VLAN. By default, all IP addresses outside of the locally-monitored broadcast domains are aggregated behind a router. To identify devices that are behind that router, you can create a custom device, and then collect metrics from the device.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

The Customization resource enables you to manage backups files on the ExtraHop Discover or Command appliance. You must have full system privileges to perform operations on this resource.

Backup files contain both customizations and systems resources. Customizations are user-defined objects, such as alerts, dashboards, triggers, and custom metrics. System resources are items such as bundles, local users and groups, and the appliance SSL certificate. For more information, see Backup and Restore.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Dashboards are built-in or customized views of your ExtraHop metrics information.

For more information, see Dashboards concepts.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Devices are objects on your network that have been identified and classified by your ExtraHop appliance.

For more information, see Devices.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Device groups can be either static or dynamic.

A static device group is user-defined; you create a device group and then manually identify and assign each device to that group. A dynamic device group is defined and automatically managed by a set of configured rules.

For example, you can create a device group and then set a rule to classify all devices within a certain IP address range to be added to that group automatically.

For more information, see Device groups.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

You can add individual or group email addresses to an email group and assign them to a system alert. When that alert is triggered, the system sends an email to all of the addresses in the email group.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

An exclusion interval can be created to set a time period to suppress an alert.

For example, if you do not want to be notified about alerts after hours or on the weekends, an exclusion interval can create a rule to suppress the alert during that time period.

For more information, see Alerts concepts.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

This resource provides metadata about the ExtraHop appliance, such as the firmware version or if the appliance is a Command appliance.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

A Flex Grid provides a table view of metrics information about devices.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Geomaps display metrics across a global map, which indicates where metrics activity has occurred.

For more information, see Geomaps concepts.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

This resource enables you to retrieve and set product keys or to retrieve and set a license.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Metrics information is collected about every object identified by the ExtraHop appliance.

Note that metrics are retrieved through the POST method, which creates a query to collect the requested information through the API.

For more information, see Metrics concepts.

The following table displays all of the operations you can perform on this resource:

For example, if you want to see all HTTP responses that occurred on the network in the last 30 seconds, enter the following request schema into the POST /metrics operation:

{
  "cycle": "auto",
  "from": -1800000,
  "metric_category": "http",
  "metric_specs": [
    {
      "name": "rsp"
    }
  ],
  "object_ids": [
    0
  ],
  "object_type": "application",
  "until": 0
}

The response body returns a list of HTTP responses and the time of each event, similar to the following output:

{   
  "stats": [     
    {       
      "oid": 0,
      "time": 1494539640000,
      "duration": 30000,
      "values": [
        354
      ]
    },
    {       
      "oid": 0,
      "time": 1494539640000,
      "duration": 30000,
      "values": [
        354
      ]
    },

    {       
      "oid": 0,
      "time": 1494539640000,
      "duration": 30000,
      "values": [
        354
      ]
    },
  ],
  "cycle": "30sec", 
  "node_id": 0,
  "clock": 1494541440000, 
  "from": 1494539640000,
  "until": 1494541440000 
}

Enter the same request schema into the POST /metrics/total operation to retrieve a count of all HTTP responses that occurred on the network in the last 30 seconds. The response body is similar to the following output:

{   
  "stats": [
    {
      "oid": -1,
      "time": 1494541380000,
      "duration": 1800000,
      "values": [
        33357
      ]
    }
  ],
  "cycle": "30sec", 
  "node_id": 0,
  "clock": 1494541440000, 
  "from": 1494539640000,
  "until": 1494541440000 
}

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Networks are correlated to the network interface card that receives input from all of the objects identified by the ExtraHop appliance.

On an ExtraHop Command appliance, each connected appliance is identified as a network capture that is looking at the traffic for each ExtraHop Discover appliance that is connected to the Command appliance.

For more information, see Networks.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

You can manage a list that specifies the network locality of IP addresses.

For example, you can create an entry in the network locality list that specifies that an IP address or CIDR block is internal or external.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

A node is defined by its relationship to an ExtraHop Command appliance. The environment which contains Discover nodes and a Command appliance is called a Command cluster.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Packet captures store packets from a network traffic flow.

You must write a trigger to identify the information you want to generate. For example, you can write a trigger to collect all of the packets going to a particular device that is generating a high volume of errors. Then, you can download or delete that information.

For more information, see Packets concepts.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Pages provide a template for creating a customized view of built-in metrics or metrics collected from triggers.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Records are structured flow and transaction information about events on your network. After you connect an ExtraHop Discover appliance to an ExtraHop Explore appliance, you can generate and send record information to the Explore appliance for storage, and you can query records to retrieve stored information about any object on your network.

For more information, see Records concepts.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

A report is a PDF file of a dashboard that you can schedule for email delivery to one or more recipients. You can specify how often the report email is delivered and the time interval for dashboard data included in the PDF file.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

The running configuration file is a JSON document that contains core system configuration information for the ExtraHop appliance.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

This resource enables you to add a decryption key for your network traffic.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

A support pack is a file that contains configuration adjustments provided by ExtraHop Support.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Device tags enable you to associate a device or group of devices by some characteristic. For example, you might tag all of your HTTP servers or tag all of the devices that are in a common subnet.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Triggers are custom scripts that perform an action upon a pre-defined event.

For example, you can write a trigger to record a custom metric every time an HTTP request occurs, or classify traffic for a particular server as an Application server. For more information, see the Trigger API Reference. For supplemental implementation notes about advanced options, see Advanced trigger options.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

The user resource enables you to create and manage the list of users who have access to the ExtraHop appliance and the permission levels for those users.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

The user group resource enables you to manage and update groups of users and their dashboard sharing associations.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

Virtual LANs are logical groupings of traffic or devices on the network.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

A whitelist prioritizes devices that are added after the device limit is reached. When the device limit is reached, any new devices that are added are placed in limited analysis mode.

If you want to prioritize a device, you can add that device to the whitelist. Devices are removed from the ExtraHop device list based on seniority; the latest devices are removed first.

The following table displays all of the operations you can perform on this resource:

Implementation information and instructions for each operation are documented in the ExtraHop API Explorer. You can click on any operation in the ExtraHop API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.