ExtraHop Trace 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 tag as /api/v1/tags/1 and the ID for the tag as 1.

  {
   "date": "Tue, 09 Nov 2021 18:21:00 GMT ",
   "via": "1.1 localhost",
   "server": "Apache",
   "content-type": "text/plain; charset=utf-8",
   "location": "/api/v1/tags/1",
   "cache-control": "private, max-age=0",
   "connection": "Keep-Alive",
   "keep-alive": "timeout=90, max=100",
   "content-length": "0"
  }

  Copy
• 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
  },

  Copy
• 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

  Copy

  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

  Copy

  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 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:

The ExtraHop system consists of a network of connected ExtraHop appliances, such as sensors, consoles, recordstores, and packetstores that perform tasks such as monitoring traffic, analyzing data, storing data, and identifying detections.

You can retrieve information and establish connections for local and remote ExtraHop appliances.

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

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.

You can monitor the progress of some administration jobs started through the REST API. If a REST request creates a job, the job ID is returned in the location header of the response. The following operations create jobs:

• POST ​/extrahop​/firmware​/latest​/upgrade
• POST ​/extrahop​/sslcert

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

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:

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:

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:

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:

You can automate upgrades to the firmware on your ExtraHop appliances through the ExtraHop REST API. This guide provides instructions to upgrade through the REST API Explorer, a 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 connected Explore and Trace appliances.

If your deployment only includes a sensor, proceed to the API Explorer, cURL or Python upgrade instructions.

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