ExtraHop REST API Guide

Objects on the ExtraHop system can be identified by any unique value, such as the IP address, MAC address, name, or system ID. However, to perform API operations on a specific object, you must locate the object ID. You can easily locate the object ID through the following methods in the REST API Explorer.

• The object ID is provided in the headers returned from a POST request. For example, if you send a POST request to create a page, the response headers display a location URL.

  The following request returned the location for the newly created page as /api/v1/pages/221 and the ID for the page as 221.

  {
   "date": "Wed, 25 Nov 2015 17:39:06 GMT",
   "via": "1.1 localhost",
   "server": "Apache",
   "content-type": "text/plain; charset=utf-8",
   "location": "/api/v1/pages/221",
   "cache-control": "private, max-age=0",
   "connection": "Keep-Alive",
   "keep-alive": "timeout=45, max=89",
   "content-length": "0"
  }

• The object ID is provided for all objects returned from a GET request. For example, if you perform a GET request on all devices, the response body contains information for each device, including the ID.

  The following response body displays an entry for a single device, with an ID of 10212:

  {
   "mod_time": 1448474346504,
   "node_id": null,
   "id": 10212,
   "extrahop_id": "test0001",
   "description": null,
   "user_mod_time": 1448474253809,
   "discover_time": 1448474250000,
   "vlanid": 0,
   "parent_id": 9352,
   "macaddr": "00:05:G3:FF:FC:28",
   "vendor": "Cisco",
   "is_l3": true,
   "ipaddr4": "10.10.10.5",
   "ipaddr6": null,
   "device_class": "node",
   "default_name": "Cisco5",
   "custom_name": null,
   "cdp_name": "",
   "dhcp_name": "",
   "netbios_name": "",
   "dns_name": "",
   "custom_type": "",
   "analysis_level": 1
  },

• The object ID is provided in the URL for most objects. For example, in the ExtraHop system, click on Assets, and then Devices. Select any device and view the URL. In the following example, the URL for the device page shows Oid=10180.

  https://10.10.10.205/extrahop/#/Devices?details=true&device
  Oid=10180&from=6&interval_type=HR&until=0&view=l2stats

  To perform specific requests for that device, add 10180 to the id field in the REST API Explorer or to the body parameter in your request.

  The URL for dashboards displays a short_code, which appears after /Dashboard. When you add the short_code to the REST API Explorer or to your request, you must prepend a tilde to the short code.

  In the following example, kmC9Y is the short_code. To perform requests for this dashboard, add ~kmC9Y as the value for the short_code field.

  https://10.10.10.205/extrahop/#/Dashboard/kmC9Y/?from=6&interval_
  type=HR&until=0

  You can also find the short_code and dashboard ID in the Dashboard Properties for any dashboard, which can be accessed from the command menu . Some API operations, such as DELETE, require the dashboard ID.

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:

• You can only create activity maps for devices in Standard Analysis and Advanced Analysis. Discovery Mode devices are not included in activity maps. For more information, see Analysis levels.
• If you create an activity map for a device, activity group, or device group with no protocol activity in the selected time interval, the map appears without any data. Change the time interval or your origin selection and try again.
• You can create an activity map in a Command appliance or in Reveal(x) 360 to view device connections across all of your sensors.

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

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 REST API Explorer. You can click on any operation in the REST 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.

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

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

The ExtraHop system analyzes and classifies traffic for every device it discovers. Your license reserves capacity for the ExtraHop system to collect metrics for high-value devices. This capacity is associated with two analysis levels: Advanced Analysis and Standard Analysis.

You can specify which devices receive Advanced Analysis and Standard Analysis levels by configuring analysis priority rules. Analysis priorities help inform the ExtraHop system about which devices are important in your environment. A third analysis level, Discovery Mode, is available for devices that are not in Advanced or Standard Analysis.

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 REST API Explorer. You can click on any operation in the REST 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 Administration settings.

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 REST API Explorer. You can click on any operation in the REST 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 identifying detections.

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 REST API Explorer. You can click on any operation in the REST 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 REST API Explorer. You can click on any operation in the REST 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 REST API Explorer. You can click on any operation in the REST 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 system, 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.

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 REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

This resource enables you to connect your on-premises sensors to Reveal(x) 360 For more information, see Connect to Reveal(x) 360 from self-managed sensors.

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 REST API Explorer. You can click on any operation in the REST 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. For more information, see Create custom devices through the REST API.

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 REST API Explorer. You can click on any operation in the REST 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 system. You must have unlimited 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 SSL certificate. For more information, see Back up and restore a Discover or 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 REST API Explorer. You can click on any operation in the REST 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.

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 REST API Explorer. You can click on any operation in the REST 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 system. 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 REST API Explorer. You can click on any operation in the REST 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 REST API Explorer. You can click on any operation in the REST 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 REST API Explorer. You can click on any operation in the REST 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.

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 REST API Explorer. You can click on any operation in the REST 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 system.

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 REST API Explorer. You can click on any operation in the REST 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 REST API Explorer. You can click on any operation in the REST 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 system.

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 Extract metrics through the REST API.

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 minutes, 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 REST API Explorer. You can click on any operation in the REST 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 system.

On an ExtraHop Command appliance, each connected sensor (Discover appliance) is identified as a network capture. 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 REST API Explorer. You can click on any operation in the REST 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 REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

A node is a sensor (Discover appliance) that is connected to 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 REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

An observation associates the IP address of a device on the ExtraHop system with an IP address outside of your network. For example, you can track the activity of a VPN user by associating the IP address of the VPN client on your internal network with the external IP address assigned to the user on the public internet.

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 REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

An open data stream (ODS) is a channel through which you can send specified metric data to an external, third-party system. For example, you might want to store or analyze metric data with a remote tool, such as Splunk, MongoDB, or Amazon Web Services (AWS).

Sending data through an open data stream is a two-step procedure. First, you configure a connection to the target system that will receive the data. Second, you write a trigger that specifies what data to send to the target system and when to send it. For more information, see Open Data Streams.

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 REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

You can retrieve and delete packets stored on the ExtraHop system.

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.

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 REST API Explorer. You can click on any operation in the REST 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 REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

This resource enables you to generate a token required to connect a sensor (Discover appliance) to a Command appliance or Reveal(x) 360.

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

Records are structured flow and transaction information about events on your network.

After you connect the ExtraHop system to a record store, you can generate and send record information to the recordstore, and you can query records to retrieve information about any object on your network. For more information, see Query for records through the REST API.

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 REST API Explorer. You can click on any operation in the REST 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.

Here are some important considerations about scheduled reports:

• You can only create a report for dashboards that you own or have been shared with you. Your ability to create a report is determined by your user privileges. Contact your ExtraHop administrator for help.
• Each report can only link to one dashboard.
• If you created a report for a dashboard that was later deleted or became inaccessible to you, the scheduled email will continue to be sent to recipients. However, the email will not include the PDF file and will instead notify recipients that the dashboard is unavailable to the report owner.

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 REST API Explorer. You can click on any operation in the REST 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 system.

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 REST API Explorer. You can click on any operation in the REST 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 REST API Explorer. You can click on any operation in the REST 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 REST API Explorer. You can click on any operation in the REST 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. For more information, see Tag a device through the REST API.

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 REST API Explorer. You can click on any operation in the REST 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 REST API Explorer. You can click on any operation in the REST 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 system and the privilege 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 REST API Explorer. You can click on any operation in the REST 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 REST API Explorer. You can click on any operation in the REST 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 REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

To guarantee that an asset, such as an important server, database, or laptop, is guaranteed Advanced Analysis, you can add that device to the whitelist, which is referred to as the watchlist in the Web UI.

Here are important considerations about the whitelist:

• The whitelist only applies to Advanced Analysis.
• The whitelist can contain as many devices as allowed by the Advanced Analysis capacity, which is determined by your license.
• A device stays on the whitelist whether it is inactive or active. A device has to be active for the ExtraHop system to collect Advanced Analysis metrics.

For more information about Advanced Analysis, see Analysis levels.

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 REST API Explorer. You can click on any operation in the REST API Explorer to view implementation information such as parameters, response class and messages, and JSON model and schema.

You can automate upgrades to the firmware on your ExtraHop system through the ExtraHop REST API. This guide includes methods for both the cURL command and a Python script.

While the firmware upgrade process is similar across all ExtraHop appliances, some appliances have additional considerations or steps that you must address before you install the firmware in your environment. If you need assistance with your upgrade, contact ExtraHop Support.

All appliances must meet the following requirements:

• The firmware version must be compatible with your appliance model.
• The firmware version on your appliance must be supported by the upgrade version.
• Command appliances must be running firmware that is greater than or equal to their connected appliances.
• Discover appliances must be running firmware that is greater than or equal to Explore and Trace appliances.

If your deployment only includes a Discover appliance, proceed to the cURL or Python upgrade instructions.

If your deployment includes additional appliance types, you must address the following dependencies before proceeding with the upgrade instructions.