TIPS & TRICKS

How to edit Notable events in ES programatically

Splunk By Splunk April 13, 2015

Several people have asked if the Splunk for Enterprise Security has an API for programmatically modifying notable events. It does, and this post will outline how to use it.

A little background…

Notable events in ES are associated with an event_id field. This field uniquely identifies a notable event. You can see this field if you run a search for notable events and select the event_id field using the field picker. Make sure to use the notable macro when searching for notable events since this macro handles some things necessary for examining notable events. The search should look like this:

`notable`

After selecting the event_id field in the field picker, you should be able to see the event_id in search (under the event actions):

notable event ID

The event_id is important because the REST API will need it in order to identify the events to edit.

Editing notable events using the REST API

Enterprise Security’s REST API not only allows you to edit notable events but also allows you to include a comment. Technically, you only have to provide a session key and a comment; all of the other fields are optional. Any fields you do not specify will be left unchanged.

I made a helper function below that will make editing the events simple:

import splunk
import json
 
def updateNotableEvents(sessionKey, comment, status=None, urgency=None, owner=None, eventIDs=None, searchID=None):
    """
    Update some notable events.
 
    Arguments:
    sessionKey -- The session key to use
    comment -- A description of the change or some information about the notable events
    status -- A status (only required if you are changing the status of the event)
    urgency -- An urgency (only required if you are changing the urgency of the event)
    owner -- A nowner (only required if reassigning the event)
    eventIDs -- A list of notable event IDs (must be provided if a search ID is not provided)
    searchID -- An ID of a search. All of the events associated with this search will be modified unless a list of eventIDs are provided that limit the scope to a sub-set of the results.
    """
 
    # Make sure that the session ID was provided
    if sessionKey is None:
        raise Exception("A session key was not provided")
 
    # Make sure that rule IDs and/or a search ID is provided
    if eventIDs is None and searchID is None:
        raise Exception("Either eventIDs of a searchID must be provided (or both)")
        return False
 
    # These the arguments to the REST handler
    args = {}
    args['comment'] = comment
 
    if status is not None:
        args['status'] = status
 
    if urgency is not None:
        args['urgency'] = urgency
 
    if owner is not None:
        args['newOwner'] = owner
 
    # Provide the list of event IDs that you want to change:
    if eventIDs is not None:
        args['ruleUIDs'] = eventIDs
 
    # If you want to manipulate the notable events returned by a search then include the search ID
    if searchID is not None:
        args['searchID'] = searchID
 
    # Perform the request
    serverResponse, serverContent = splunk.rest.simpleRequest('/services/notable_update', sessionKey=sessionKey, postargs=args)
 
    # Make sure the request was successful
    if serverResponse['status'] != '200':
        raise Exception("Server response indicates that the request failed")
 
    # Return the information about the request
    response_info = json.loads(serverContent)
    return response_info

Download notable_edit_example.py to get this function (as well as examples).

To use this function, just call updateNotableEvents() with the appropriate arguments. This function allows you to edit notable events in two ways:

  1. By editing events that match a list of eventIDs that are provided to the function
  2. By editing all events that match a search

Editing events that match a list of eventIDs

Lets say that I want to edit an event with the ID of “F93A9857-59D8-4AEB-AD97-4F182E0C959E@@notable@@1363d37ec74a79d00e22af26bfe0718b”. To edit this event, I would need to first get a session key. In this example, I’ll generate by logging into Splunk with the default credentials:

from splunk import auth
 
sessionKey = auth.getSessionKey(username='admin', password='changeme')

Now that I have a session key, I can call the function and add a comment to the notable like this:

updateNotableEvents( sessionKey=sessionKey, comment='Just adding a comment', eventUIDs=['F93A9857-59D8-4AEB-AD97-4F182E0C959E@@notable@@1363d37ec74a79d00e22af26bfe0718b']))

This will output the following, noting that both events were updated:

2 events updated successfully

Editing all events that match a search

A second way to edit events is to ask the function to edit all of the events that match a given search. This is done by running a search and then calling API with the search ID. This will cause ES to process the results and edit all of the eventIDs it finds in the search.

First, run the search and make sure it completes with results:

import splunk.search

# Kick off a search
job = splunk.search.dispatch("search `notable` | head 2", sessionKey=sessionKey, earliest='-7d')

# Wait until the search is done
while True:
    if job.isDone and (job.resultCount > 0 or job.eventCount > 0):
        print "Search is done, result count is", job.resultCount
        break

Next, provide the search ID to the API:

printResultMessage( updateNotableEvents( sessionKey=sessionKey, comment='Just adding a comment via a search', searchID=job.sid))

This will output the following indicating that the search returned two events and that both were updated:

Search is done, result count is 2
2 events updated successfully

Note that the search job artifacts will need to exist when the call to updateNotableEvents() is done. If the call is done too long after the search was executed, then the results might no longer exist. Also, the search will need to have the eventID field; any search operations that remove this field will prevent the APi from determining which events to edit.

Wrapping up

The best way to learn how to use this API is to try the attached sample code. You can download the example file notable_edit_example.py and use the updateNotableEvents() function in your own code. That example uses Splunk’s Python libraries. Use this one (notable_edit_example_native.py) if you want an example that doesn’t rely on Splunk libraries (only needs the requests library). Although this example show how to do it in Python, you can also call this endpoint in JavaScript. If you have any problems, leave a comment under this post or make a question in Splunk Answers.

----------------------------------------------------
Thanks!
Luke Murphey

Splunk
Posted by

Splunk