Start Demo

Extract the device list through the REST API

The ExtraHop REST API enables you to extract the list of devices discovered by the ExtraHop system. By extracting the list with a REST API script, you can export the list in a format that can be read by third-party applications, such as a configuration management database (CMDB). In this topic, we show methods for extracting a list through both the cURL command and a Python script.

Before you begin

  • You must log in to the ExtraHop system with an account that has full write privileges to generate an API key.
  • You must have a valid API key to retrieve devices through the REST API and complete the procedures below. (See Generate an API key.)

Retrieve the device list with the cURL command

The device list includes all device metadata, such as MAC addresses and device IDs. However, you can filter the list of devices with a JSON parser to extract the specific information you want to export. In this example, the device list is retrieved and then filtered with the jq parser to only extract the display name of each device.

Before you begin

  • The cURL tool must be installed on your machine.
  • The jq parser must be installed on your machine. For more information, see https://stedolan.github.io/jq/.
Open a terminal application and run the following command, where YOUR_KEY is the API for your user account, HOSTNAME is the hostname of your ExtraHop system, and MAX_DEVICES is a number large enough to be more than the total number of devices discovered by your system: 
curl -s -X GET --header "Accept: application/json" --header "Authorization: ExtraHop apikey=YOUR_KEY"  "https://HOSTNAME/api/v1/devices?active_from=1&active_until=0&limit=MAX_DEVICES" | jq -r '.[] | .display_name'
Note:If the command returns no results, make sure that a trusted certificate has been added to your ExtraHop system. Alternatively, you can add the --insecure option to retrieve the device list from an ExtraHop system without a trusted certificate; however, this method is not secure and not recommended.
Tip:You can append the select(.analysis == "LEVEL") option to filter results by analysis level. For example, the following command limits the results to include only devices that are selected for advanced analysis:
curl -s -X GET --header "Accept: application/json" --header "Authorization: ExtraHop apikey=YOUR_KEY"  "https://HOSTNAME/api/v1/devices?active_from=1&active_until=0&limit=10000000000"  | jq -r '.[] | select(.analysis == "advanced") | .display_name'
Tip:You can append the select(.critical == BOOLEAN) option to filter results by the critical field. For example, the following command limits the results to include only devices that are identified as critical by the ExtraHop system:
curl -s -X GET --header "Accept: application/json" --header "Authorization: ExtraHop apikey=YOUR_KEY"  "https://HOSTNAME/api/v1/devices?active_from=1&active_until=0&limit=10000000000"  | jq -r '.[] | select(.critical == true) | .display_name'
Tip:You can append the select(.cloud_instance_name != null) option to filter results by the cloud instance name field. For example, the following command limits the results to include only devices with a cloud instance name:
curl -s -X GET --header "Accept: application/json" --header "Authorization: ExtraHop apikey=YOUR_KEY"  "https://HOSTNAME/api/v1/devices?active_from=1&active_until=0&limit=10000000000"  | jq -r '.[] | select(.cloud_instance_name != null) | .cloud_instance_name'

Retrieve and run the example Python script

The ExtraHop GitHub repository contains an example Python script that extracts the device list, including all device metadata, and writes the list to a CSV file in the same directory as the script.

Important:The example python script authenticates to the ExtraHop system through an API key, which is not compatible with the Reveal(x) 360 REST API. To run this script with Reveal(x) 360, you must modify the script to authenticate with API tokens. See the py_rx360_auth.py script in the ExtraHop GitHub repository for an example of how to authenticate with API tokens.
  1. Go to the ExtraHop code-examples GitHub repository and download the extract_device_list/extract_device_list.py file to your local machine.
  2. In a text editor, open the extract_device_list.py file and replace the following configuration variables with information from your environment:

    HOST: The IP address or hostname of the ExtraHop system

    APIKEY: The API key

    FILENAME: The file that output will be written to

    LIMIT: The maximum number of devices to retrieve with each GET request

    SAVEL2: Retrieves L2 parent devices. This variable is valid only if you have enabled the ExtraHop system to discover devices by IP address.

    ADVANCED_ONLY: Retrieves only devices that are currently under advanced analysis

    HIGH_VALUE_ONLY: Retrieves only devices that are considered high value

  3. Run the following command: 
    python3 extract_device_list.py
    Note:If the script returns an error message that the SSL certificate verification failed, make sure that a trusted certificate has been added to your ExtraHop system. Alternatively, you can add the verify=False option to bypass certificate verification. However, this method is not secure and not recommended. The following code sends an HTTP GET request without certificate verification:
    requests.get(url, headers=headers, verify=False)
Last modified 2023-11-07