Add device cloud instance properties through the REST API
Device cloud properties enable you to view information about your cloud environment in the ExtraHop system. You can identify the cloud instance name, type, and ID of a device along with the cloud account that owns the device and the ID of the Virtual Private Cloud that the device is in.
This guide provides instructions for adding an observation through both the ExtraHop API Explorer and example Python scripts for Amazon AWS and Microsoft Azure. If you update cloud properties with a REST API script, you can continuously retrieve information from your cloud provider to make sure that your cloud property information is always up to date.
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 make changes through the REST API and complete the procedures below. (See Generate an API key.)
- Familiarize yourself with the ExtraHop REST API Guide to learn how to navigate the ExtraHop API Explorer.
Retrieve and install the example Lambda Python script for AWS
The ExtraHop GitHub repository contains an example Python script that imports AWS EC2 instance properties into the ExtraHop system. The script maps network interfaces of EC2 instances to devices discovered on the ExtraHop system by MAC address.
The script is designed to run as a Lambda function within AWS. Here are some important considerations for running the script in AWS:
- The script is designed to run on a set time interval. Each time the script is run, it scans each instance on the VPC and updates the corresponding devices in the ExtraHop system. For information about configuring a Lambda function to run periodically, see the AWS tutorial here.
- The Lambda function must be able to access resources on your VPC. For more information, see the AWS tutorial here.
- The Lambda function must have list and read access to the DescribeInstances action for the EC2 service. For more information, see the AWS tutorial here.
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) |
Retrieve and install the example Python script for Azure
The ExtraHop GitHub repository contains an example Python script that imports Azure device properties into the ExtraHop system. The script assigns cloud device properties to every device discovered by the ExtraHop system with a MAC address that belongs to an Azure VM network interface. The script is designed to be run on a set time interval. Each time the script is run, it scans each VM and updates the corresponding devices in ExtraHop.
The script requires the following modules from the Azure Python SDK:
The script also requires you to have configured Azure authentication credentials in the following environment variables on the machine that runs the script:
- AZURE_SUBSCRIPTION_ID
- AZURE_CLIENT_ID
- AZURE_CLIENT_SECRET
- AZURE_TENANT_ID
For information about generating these credentials, see the Azure documentation.
Thank you for your feedback. Can we contact you to ask follow up questions?