Start Demo

Connect to Reveal(x) 360 from self-managed sensors through the REST API

The ExtraHop REST API enables you to automate connections for a large number of self-managed sensors to Reveal(x) 360 with a script. Self-managed sensors include on-premises Discover appliances or instances deployed on cloud service providers such as AWS, Azure, and Google Cloud Platform (GCP).

This guide provides instructions for the REST API Explorer, so you can test the REST operation, and an example Python script that you can modify with your environment variables.

Note:You cannot connect Trace appliances through the REST API. For information about connecting Trace appliances, see Connect to Reveal(x) 360 from self-managed sensors.

Before you begin

  • Familiarize yourself with the ExtraHop REST API Guide to learn how to navigate the ExtraHop REST API Explorer.
  • You must have an Okta user account with OktaAdmin privileges to configure Reveal(x) 360. Details for setting up this account are in the introduction email sent from ExtraHop Networks.
  • You must generate tokens through Reveal(x) 360 for each sensor that you want to connect. For more information, see Connect to Reveal(x) 360 from self-managed sensors.
  • You must log in to the sensor with an account that has system and access administration privileges to generate an API key.
  • You must have a valid API key to make changes through the REST API and complete the procedures below. (See Generate an API key.)

Connect to Reveal(x) 360 through the REST API Explorer

  1. In a browser, navigate to the REST API Explorer.
    The URL is the hostname or IP address of your sensor or console, followed by /api/v1/explore/. For example, if your hostname is seattle-eda, the URL is https://seattle-eda/api/v1/explore/.
  2. Click Enter API Key and then paste or type your API key into the API Key field.
  3. Click Authorize and then click Close.
  4. Click Cloud and then click POST /cloud/connect.
  5. Click Try it out.
  6. In the body field, replace string with the token you generated from Reveal(x) 360, as shown in the following example: 
    {
    "cloud_token": "561b85-e9092a3a-343fcb03-78c72777-8db70bbd"
}
    The Server response section displays a 201 status code.

Python script example

The ExtraHop GitHub repository contains an example Python script that connects your sensor to Reveal(x) 360 by reading tokens and API keys from a CSV file.

  1. Go to the ExtraHop code-examples GitHub repository and download the self-managed-sensor-rx360-connect/self-managed-sensor-rx360-connect.py file to your local machine.
  2. In the directory you copied the self-managed-sensor-rx360-connect.py to, create a CSV file that meets the following specifications:
    • The CSV file must not contain a header row.
    • Each row of the CSV file must contain the following three columns in the specified order:
      The sensor hostname The sensor API key The token you generated from Reveal(x) 360
    • The CSV file must be named sensors.csv and stored in the same directory as the script.
    Note:For an example of a compatible CSV file, see the self-managed-sensor-rx360-connect/sensors.csv file in the ExtraHop code-examples GitHub repository.
  3. Run the following command: 
    python self-managed-sensor-rx360-connect.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 sensor or console. 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