Configure ticket tracking for detections

You must enable ticket tracking before your scripts can update ticket information on your ExtraHop system through the REST API. Optionally, specify a URL template that adds an HTML link for the ticket to your detection card. Click the link to open the linked ticket in your ticketing system in a new browser tab.

1. Log into the Admin UI on the Discover or Command appliance.
2. In the System Configuration section, click Ticket Tracking.
3. Select the Enable ticket tracking checkbox.
4. (Optional): In the URL field, specify the URL template for your ticketing system and add the $ticket_id variable at the appropriate location. For example, type a complete URL such as https://jira.example.com/browse/$ticket_id. The $ticket_id variable is replaced with the ticket ID associated with the detection.
   

While there are many ways to write a trigger that interacts with ticket tracking software, this example shows you how to create a trigger that performs the following actions:

1. Log into the Web UI on the ExtraHop Discover or Command appliance.
2. Click the System Settings icon and then click Triggers.
3. Click New.
4. Click the Configuration tab, and specify a name and optional description for the trigger.
5. From the Events list, select DETECTION_UPDATE.
6. The DETECTION_UPDATE event runs every time that a detection is created or updated in the ExtraHop system.
7. Click the Editor tab.
8. In the Editor tab, specify Detection class parameters in a JavaScript object. These parameters determine the information that is sent to your ticketing system.
   The following example code adds the detection ID, description, title, categories, and risk score to a JavaScript object called payload:

   const summary = "ExtraHop Detection: " + Detection.id + ": " + Detection.title;
   const description = "ExtraHop has detected the following event on your network: " + Detection.description 
   const payload = {
       "fields": {
           "summary": summary,
           "assignee": {
               "name": "escalations_team"
           },
           "reporter": {
               "name": "ExtraHop"
           },
           "priority": {
               "id": Detection.riskScore
           },
           "labels": Detection.categories,
           "description": description
       }
   };

9. Next, define the HTTP request parameters in a JavaScript object below the previous JavaScript object.
   For example, the following code defines an HTTP request for the payload described in the previous example: defines a request with a JSON payload:

   const req = {
       'path': '/rest/api/issue',
       'headers': {
           'Content-Type': 'application/json'
       },
       'payload': payload
   };

   For more information about ODS request objects, see Open data stream classes.

10. Finally, specify the HTTP POST request that sends the information to the ODS target.For example, the following code sends the HTTP request described in the previous example to an ODS target named ticket-server:

    Remote.HTTP('ticket-server').post(req);

const summary = "ExtraHop Detection: " + Detection.id + ": " + Detection.title;
const description = "ExtraHop has detected the following event on your network: " + Detection.description 
const payload = {
    "fields": {
        "summary": summary,
        "assignee": {
            "name": "escalations_team"
        },
        "reporter": {
            "name": "ExtraHop"
        },
        "priority": {
            "id": Detection.riskScore
        },
        "labels": Detection.categories,
        "description": description
    }
};

const req = {
    'path': '/rest/api/issue',
    'headers': {
        'Content-Type': 'application/json'
    },
    'payload': payload
};

Remote.HTTP('ticket-server').post(req);

After you have configured a trigger to create tickets for detections in your ticket tracking system, you can update ticket information on your ExtraHop system through the REST API.

#!/usr/bin/env python2

import json
import requests
import csv

API_KEY = 'f6876657888a7c1f24ac77827'
HOST = 'https://example.extrahop.com/'

# Method that updates detections on an ExtraHop appliance
def updateDetection(detection):
    url = HOST + 'api/v1/detections/' + detection['detection_id']
    del detection['detection_id']
    data = json.dumps(detection)
    headers = {'Content-Type': 'application/json',
               'Accept': 'application/json',
               'Authorization': 'ExtraHop apikey=%s' % API_KEY}
    r = requests.patch(url, data=data, headers=headers)
    print r.status_code
    print r.text

# Array of detection information
detections = [
                 {
                     "detection_id": "1",
                     "ticket_id": "TK-16982",
                     "status": "new",
                     "assignee": "sally",
                     "resolution": None,
                 },
                 {
                     "detection_id": "2",
                     "ticket_id": "TK-2078",
                     "status": None,
                     "assignee": "jim",
                     "resolution": None,
                 },
                 {
                     "detection_id": "3",
                     "ticket_id": "TK-3452",
                     "status": None,
                     "assignee": "alex",
                     "resolution": None,
                 }
             ]

for detection in detections:
    updateDetection(detection)

requests.get(url, headers=headers, verify=False)