Tag a device through the REST API
Tags can help you classify devices that share a common characteristic from among potentially hundreds of discovered devices on your network.
You might want to tag devices by their role on your network, such as the devices that make up your development and production servers. For example, if you are running multiple AWS instances in your environment, it is critical to size them for their workload. An undersized instance can result in poor performance; an oversized instance is needlessly costly. If you tag your AWS instances, you can easily set up device groups by instance size, and then create a dashboard to monitor usage and performance metrics.
In this guide, you will learn how create a tag, find the device you want to tag, and then add the tag to the device. An example script is provided at the end, which adds a given device tag to all IP addresses read from a CSV file.
- You must log into the ExtraHop appliance with an account that has unlimited 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 REST API Explorer.
Create a tag
If you already have a tag on the system, you can skip this step. The example script at the bottom of this guide will check for a tag and create a new tag only if necessary.
Retrieve devices that match your criteria
In this step you will search for the devices that you want to tag and note the device ID. You must have the device ID before you can tag devices.
Assign the tag to a device or device group
In this step, you will assign a tag to a device by the device ID you found in the previous step.
- Scroll down the page and click Tag to display tag operations.
- Click POST /tags/{id}/devices/{child-id}.
- Click Try it out.
- In the child-id field, type the ID of the device you want to tag.
- In the id field, type the ID of the tag you want to assign.
- Click Send Request to assign the tag to the device.
Tip: | After you click Send Request, you can click the tabs to view scripts for the operation in Curl, Python 2.7, or Ruby. |
Python script example
The following Python script reads IP addresses from a csv file, creates a device tag, and then assigns the tag to all devices with the specified IP addresses. The script creates a new tag only if the specified tag does not already exist. The script includes the following configuration variables that you must replace with information from your environment:
HOST: The IP address or hostname of the Discover appliance
APIKEY: The API key
TAG: The name of the tag
DEVICE_LIST: The file that contains the list of IP addresses
#!/usr/bin/python3 import http.client import json import csv HOST = 'extrahop.example.com' APIKEY = '123456789abcdefghijklmnop' TAG = 'new-tag' IP_LIST = 'ip_list.csv' headers = {'Content-Type': 'application/json', 'Accept': 'application/json', 'Authorization': 'ExtraHop apikey=%s' % APIKEY} #### Returns the ID of a tag #### def get_tag_id(tag): tag_id = '' conn = http.client.HTTPSConnection(HOST, context=context) conn.request('GET', '/api/v1/tags', headers=headers) resp = conn.getresponse() tags = json.loads(resp.read()) tag_index = 0 while tag_id == '' and tag_index < len(tags): if tags[tag_index]['name'] == tag: tag_id = tags[tag_index]['id'] tag_index += 1 return tag_id #### If the tag does not already exist, create it #### tag_id = get_tag_id(TAG) if tag_id != '': print(TAG + ' already exists') else: print('Creating ' + TAG + ' tag') body = {"name": TAG} conn = http.client.HTTPSConnection(HOST, context=context) conn.request('POST', '/api/v1/tags', headers=headers, body=json.dumps(body)) resp = conn.getresponse() if resp.status == 201: print(TAG + ' tag created successfully!') else: print('Error: could not create ' + TAG + ' tag') sys.exit() tag_id = get_tag_id(TAG) #### Get IPs from IP_LIST file #### device_ips = [] with open(IP_LIST, 'rt', encoding='ascii') as f: reader = csv.reader(f) for row in reader: for item in row: device_ips.append(item) #### Get IDs for devices with the specified IPs #### device_ids = [] tagged_devices = [] for ip in device_ips: conn = http.client.HTTPSConnection(HOST, context=context) url = '/api/v1/devices?limit=100&search_type=ip%20address&value=' + ip conn.request('GET', url, headers=headers) resp = conn.getresponse() try: devices = json.loads(resp.read()) except: continue for device in devices: device_ids.append(device['id']) tagged_devices.append(device['display_name']) #### Add tag to devices #### body = {"assign": device_ids} conn = http.client.HTTPSConnection(HOST, context=context) url = '/api/v1/tags/%d/devices' % tag_id conn.request('POST', url, headers=headers, body=json.dumps(body)) resp = conn.getresponse() if resp.status == 204: print('Success! Assigned %s to the following devices:' % TAG) for name in tagged_devices: print(' ' + name) print('Assigned %s to %d devices' % (TAG, len(device_ids))) else: print('Error! Failed to tag specified devices')
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 appliance. Alternatively, you can add the context option and
send the request over TLSv1.2 to bypass certificate verification. However, this method
is not secure and is not recommended. The following code creates an HTTP connection over
TLSv1.2:conn = httplib.HTTPSConnection(HOST, context=ssl.SSLContext(ssl.PROTOCOL_TLSv1_2)) |
Thank you for your feedback. Can we contact you to ask follow up questions?