Custom search scripts

Custom search scripts

Create your own search commands by writings scripts. To build a search script, put a Python script in $SPLUNK_HOME/etc/searchscripts/. Python scripts in the searchscripts directory are available in the search language and can be used in a search. Find more examples on the Dev Wiki search script page.

For more help using Splunk's Python modules, please see the page on SKDs.

Configuration files

You must add your search script by name to commands.conf and permissions to authorize.conf.

commands.conf

Add an entry to commands.conf for your search script. This allows you to pipe your search to your custom search script.

[loglady]
filename = loglady.py

authorize.conf

Add two entries to authorize.conf.

First, add a capability for the script to be run:

[capability::run_script_loglady]

Second, add a line to any role to authorize users assigned that role to run the script:

run_script_loglady          = enabled

Working with results

Some things to know about passing results to and from a search command:

• Results are passed in with stdin and out with stdout.
• Arguments are passed from the search line directly to your script.

If your script is called myNewCommand.py, it can be used in a search as follows:

Please note:

• Only Python or Perl scripts are currently supported. If you use Perl, you must parse the search results on your own.
• If you make changes to your files, you must restart your Splunk server to pick up the changes.
• The inputs to your script are all the events selected by the preceding search. By default, only the top 100 results are passed to the script to run. To override this value, append your search with a new value for maxinputs; for example, maxinputs=10000.
• Extracted fields are not available in the results array that is passed to the script. To expose extracted fields, first pipe the search into kv before piping to the custom search script. For example, * | kv | myscript.

Python modules

The splunk.Intersplunk module directs events from Splunk to your Python search scripts.

• Calling getOrganizedResults returns a list of Python dictionaries, each of which represents a single event.
• Calling outputResults with a list of dictionaries passes those events back to Splunk.

The output of your script can then be fed back into Splunk as events. For example:

import sys,splunk.Intersplunk
# this call populates the results variable with all the events passed into the search script:
results,dummyresults,settings = splunk.Intersplunk.getOrganizedResults()
# hand the results right back to Splunk
splunk.Intersplunk.outputResults(results)

Although this code snippet does not do much, it shows you how to get events pass the data back to Splunk. If you want to change some of the events, add a loop to iterate over all the events. Each event is comprised of a set of key-value pairs for every extracted field.

Authenticate

Add an auth attribute to your stanza in commands.conf:

[MYSEARCHSCRIPT]
filename = MYSEARCHSCRIPT.py
passauth = true

Example

tolower.py:

import splunk.Intersplunk
import splunk.search as search
import os,re,sys,time
import splunk.auth

# this call populates the results variable with all the events passed into the search script:
results,dummyresults,settings = splunk.Intersplunk.getOrganizedResults()

authString = settings.get("authString", None)
if authString == None:
        splunk.Intersplunk.generateErrorResults("username/password authorization not given to 'backfill'.")
        sys.exit

os.environ["SPLUNK_TOK"] = authString

os.system("splunk search '* | head 1' -format csv") 

# create new list to pass back to Splunk
new_result_list = []
# Iterate over all the events:
for result in results:
  # for all the events, you want to iterate over all the extracted fields:
  new_result = {}
  for key,value in result.items():
    # change the result items. This example makes all the values lowercase.
    value = value.lower()
    new_result[key] = value
  # add the changed result to the new list of results
  new_result_list.append(new_result)
# hand the results right back to Splunk
splunk.Intersplunk.outputResults(new_result_list)

Changing events with your own command is probably the most common use-case. You do not necessarily have to return the entire original set of events. You can return any key-value pairs back to Splunk. For example:

# This prepares the return value for the script
newresults = [ { "afterglowFilename" : "afterglow.html" } ]
splunk.Intersplunk.outputResults(newresults)

This example returns only one key/value pair. This could then be combined with a field action to execute some action on this field, for example displaying the html file indicated in the value part.