Splunk Custom Search Command Example
This repo contains an example of how to make a custom search command for Splunk. This includes a base class that makes it super easy to create one.
Here is how you make one:
Step 1: Copy search_command.py
Copy the file search_command.py into the bin directory of your app. search_command.py is available within this repository under the path "/src/bin/search_command_example_app/search_command.py.
When you are done copying it, your app should have a file with this path:
bin/search_command.py
Step 2: Create your custom search command
In the steps below you will create the Python class that contains the code of your custom search command.
2.1: Create the custom search command file
Create the Python file that will contain your custom search command. We are going to make a simple search command that just echoes something back, so it will be named "echo.py". This would be in the file:
bin/echo.py
2.2: Import the search command base class
Modify your search command to import the search command base class and sys:
from search_command import SearchCommand
import sys
2.3: Create your search command class
Create an new class that inherits from the SearchCommand class and calls the constructor from the super-class. Note that I have named the class "Echo":
class Echo(SearchCommand):
def __init__(self):
# Initialize the class
SearchCommand.__init__(self, run_in_preview=True, logger_name='echo_search_command')
def handle_results(self, results, session_key, in_preview):
pass
2.4: Modify the constructor to take the search command arguments
Modify the constructor to take whatever arguments you want it to take. In this case, I want the search command to take an argument "what_to_echo"; the constructor now takes the argument and stores it:
from search_command import SearchCommand
import sys
class Echo(SearchCommand):
def __init__(self, what_to_echo="Hello World"):
# Save the parameters
self.what_to_echo = what_to_echo
# Initialize the class
SearchCommand.__init__(self, run_in_preview=True, logger_name='echo_search_command')
def handle_results(self, results, session_key, in_preview):
pass
2.5: Implement handle_results()
Implement handle_results() to do whatever your search command is supposed to do. In this, mine will just output the contents of the "what_to_echo" argument.
from search_command import SearchCommand
import sys
class Echo(SearchCommand):
def __init__(self, what_to_echo="Hello World"):
# Save the parameters
self.what_to_echo = what_to_echo
# Initialize the class
SearchCommand.__init__(self, run_in_preview=True, logger_name='echo_search_command')
def handle_results(self, results, session_key, in_preview):
self.output_results([{'echo' : self.what_to_echo}])
2.5: Add the code to execute the search command
Finally, add the code to cause the search command to execute at the bottom of the file:
from search_command import SearchCommand
import sys
class Echo(SearchCommand):
def __init__(self, what_to_echo="Hello World"):
# Save the parameters
self.what_to_echo = what_to_echo
# Initialize the class
SearchCommand.__init__(self, run_in_preview=True, logger_name='echo_search_command')
def handle_results(self, results, session_key, in_preview):
self.output_results([{'echo' : self.what_to_echo}])
if __name__ == '__main__':
try:
Echo.execute()
sys.exit(0)
except Exception as e:
print e
Step 3: Register your custom search command in commands.conf
3.1: Create the commands.conf entry
Finally, register your search command by adding it to commands.conf. Create the file "default/commands.conf" in your app. The stanza name should match the name of the command as it will appear in Splunk; "filename" must match the filename of the search command in the bin directory:
[echo]
filename = echo.py
generating = true
passauth = false
"generating" is set to true since this search command doesn't accept Splunk results but rather creates new results. "passauth" is set to false because this search command doesn't need to have access to splunkd.
3.2: Reload the commands.conf file
Splunk won't recognize your new commands.conf entry until you restart or you specifically tell Splunk to reload the conf files.
You can force Splunk to reload your commands.conf entry by vanigating to the followuing URL in your browser and clicking "refresh":
http://127.0.0.1:8000/en-US/debug/refresh?entity=admin/commandsconf
You don't need to call this endpoint everytime you edit the search command Python, just when you edit the commands.conf file. The Python code will get picked up automatically.
Step 4: Run the command
Now that Splunk recognizes your command, you can run it from the search bar. Run the search by entering this in the search bar:
| echo what_to_echo="This works!"
Make sure not to include spaces between the argument. Running a search like this will not work correctly:
| echo what_to_echo = "This won't work"
FAQs
How do I consume search results in a search command?
You will need to do two things if you need your search command to process results within SPL.
One, update the command in commands.conf to set generating to false.
Second, you will need to update handle_results() to do something with the results which will be in the "results" argument. Here is an example that adds a new field 'source_length' with the length of the source field:
def handle_results(self, results, session_key, in_preview):
for result in results:
if 'source' in result:
result['source_length'] = len(result['source'])
self.output_results(results)
How do I get a session key so that my search command can access Splunk's REST API?
You will need to update your commands.conf entry to tell Splunk to pass a session key to your search command by setting "passauth" to true. Something like this:
[echo]
filename = echo.py
passauth = true
Once you do that, the session_key parameter that is passed to handle_results() will be a valid session key.