How To Make A Custom Splunk Command

Step 0: Understanding the types of commands

You can think of Splunk custom search commands as specialized command components within Splunk apps that understand your unique needs.

Each command has a specific type that serves as the boundary of how it can work and interact with other commands. Here are the different types:

• Streaming commands: Process results in one event at a time, applying transformations individually.
• Transforming commands: Arrange results into a data table for statistical analysis.
• Generating commands: Retrieve information from indexes without modifications.
• Dataset processing commands: Require the complete dataset before execution.

From here, let's take everything in steps - by completing the 4 easy steps below, you'll have a functioning custom search command.

Step 1: Setting up your Splunk environment

Let's first get the Splunk home directory under control.

$SPLUNK_HOME is an environment variable used in various places and it depends on where you have installed Splunk Enterprise on your machine. Please set it to the right directory before continuing.

• On Linux or macOS: Open a terminal window and type echo $SPLUNK_HOME.
• On Windows: Open a Command Prompt window and type echo %SPLUNK_HOME%.

Now in order to execute a custom command, we must first have Splunk Enterprise running. Please download the most recent version of Splunk Enterprise.

After downloading and unpacking, you can launch Splunk via the terminal by executing:

$SPLUNK_HOME/bin/splunk start

After this is successful, Splunk Enterprise will be available at http://localhost:8000 in your browser.

To create an app, open the above page and navigate to Manage Apps, click the Create app button, and enter your app's name along with some additional information like folder name, version, author and description.

By pressing "Save!", you'll now have a Splunk app and can access the app's directory at $SPLUNK_HOME/etc/apps/my_cutom_command_app/.

Now that we have a container for custom commands, you must choose a programming language to write the code of the command in.

Python is the most popular language used among Splunk developers and we'll be using that going forward, but you can also use Java - the choice is yours!

Step 2: Writing the script for your command

Let's assume our custom command name is my_custom_command.

Now that the entire environment for the custom command has been configured, we need to create a script for it at $SPLUNK_HOME/etc/my_cutom_command_app/bin/my_custom_command.py. Note that the name of the script (the .py file) is the same as the command name - this is not required, but good practice.

For writing the script we need the Splunk Enterprise SDK for Python, which you can copy and paste into the following folder:

$SPLUNK_HOME/etc/my_cutom_command_app/bin/splunklib

Below are examples of each of the different types of commands - streaming, transforming, generating and data processing. Pick one and move on to the next step.

You can also feel free to modify the code to play around with it right now.

Streaming

import sys
from splunklib.searchcommands import dispatch, StreamingCommand, Configuration


@Configuration()
class CustomCommand(StreamingCommand):
    def stream(self, events):
        for event in events:
            yield event


dispatch(CustomCommand, sys.argv, sys.stdin, sys.stdout, __name__)

Reporting / Transforming

import sys
from splunklib.searchcommands import dispatch, ReportingCommand, Configuration


@Configuration()
class CustomCommand(ReportingCommand):
    @Configuration()
    def map(self, events):
        pass

    def reduce(self, events):
        pass


dispatch(CustomCommand, sys.argv, sys.stdin, sys.stdout, __name__)

Generating

import sys
from splunklib.searchcommands import dispatch, GeneratingCommand, Configuration


@Configuration()
class CustomCommand(GeneratingCommand):
    def generate(self):
        pass


dispatch(CustomCommand, sys.argv, sys.stdin, sys.stdout, __name__)

Eventing / Data Processing

import sys
from splunklib.searchcommands import dispatch, EventingCommand, Configuration


@Configuration()
class CustomCommand(EventingCommand):
    def transform(self, events):
        pass


dispatch(CustomCommand, sys.argv, sys.stdin, sys.stdout, __name__)

Step 3: Tell Splunk about it

Now how does Splunk know we made a custom command? We register it within our app with two config files - commands.conf and searchbnf.conf. Create these files in your app's default directory.

commands.conf path & content:

$SPLUNK_HOME/etc/apps/my_custom_app/default/commands.conf

[my_custom_command]
python.version = python3
filename = my_custom_command.py
chunked = true

searchbnf.conf path & content:

$SPLUNK_HOME/etc/apps/my_custom_app/default/searchbnf.conf

[my_custom_command-command]
syntax = [my_custom_command]
shortdesc = [A short description of your custom command]
usage = public

Step 4: Restart Splunk and test it

We can now restart Splunk to apply the new configuration using this command.

$SPLUNK_HOME/bin/splunk restart

You can also do this directly from the UI via Setting > Server Controls > Restart Splunk.

Now you can test it in the "Search and Reporting" app with this SPL command:

index=_internal | my_custom_command

Congratulations! You've successfully created a custom search command in your Splunk app. Now you can enhance and modify the script based on your specific use case.

Bonus: You can check out the Splunk-app-examples which is a treasure chest of ready-made templates and inspiration for your Splunk custom search commands.

Happy Splunking!