Security responsibilities with custom commands
As the author of a custom search command, it is your responsibility to follow best security practices when developing custom search commands. This topic includes information about writing high-quality, secure custom search commands.
Custom search commands run with the same permissions as splunkd on the search heads and indexers of a Splunk software deployment. Custom search commands do not run in a sandbox. Consequently, the security of your deployments depends on the security of your custom search commands.
Validate search results
First and foremost, you should consider data coming from search results as untrusted user input. Search results might contain arbitrary strings. If you use these strings unescaped or without validation within your program, you might unwittingly introduce critical security vulnerabilities.
For example, if you pass an unvalidated field from a search result as the argument to a shell command, unescaped semi-colons might allow malicious individuals to run arbitrary programs on a Splunk deployment. It is your responsibility as a search command author to validate input and avoid code injection and path traversal vulnerabilities, for example:
- Code injection vulnerabilities, such as SQL injection
- Path traversal vulnerabilities, such as allowing user data to reference arbitrary file system paths
Use role-based access control
By default, custom search commands are available to any user who is logged in. It is a good practice to restrict access search commands by user roles.
Some search commands might be written to perform privileged maintenance actions, such as a command to "purge the database cache". Only users with special privileges should be allowed to use these commands.
You can use the role-based access control features to restrict permission to run search commands. You can restrict permissions to specific users or roles.
For example, you have a custom search command called "launchmissiles" that you want only users assigned to the "admin" role to be able to use. In this situation, you would follow these steps:
- Create a
default.metafile in the
metadatadirectory in your application.
- In the
default.metafile, add the following content:
[commands/launchmissiles] access = read : [ admin ], write : [ admin ]
readaccess specifies who can run a custom search command. The above example limits
readaccess to the
adminrole. You can specify access to other roles, such as the "power" role, or a new role that you define in the
writeaccess only to the "admin" role. No other role should have
See About users and roles in Securing Splunk Enterprise.
Avoid using the local file system
Avoid accessing or modifying the file system as much as possible. Any code that you write which accesses the file system might contain bugs that allow malicious individuals to exfiltrate data from a Splunk deployment. A bug could allow a user to read data from indexes that the individuals are not permitted to search.
Unconstrained file system access might lead to severe challenges when trying to deploy a custom search command in a search head cluster environment. For example, if you edit a
.conf file directly in your custom search command, those changes would not be replicated to the other members of a search head cluster. You should always use the Splunk REST API to interact with
.conf files or other knowledge objects. If you need to permanently persist data from a custom search command, use the REST API to write to the KV store or to
If you must use the file system, for example to spill data from memory to disk, create a temporary directory under the
dispatch directory for the search. Use a secure directory creation method, such as the
tempfile.mkdtemp() function in Python. The
dispatch directory is automatically purged by the Splunk software after a search expires.
- For custom search commands that use the Version 2 protocol, the dispatch directory is in the
dispatch_dirattribute of the
searchinfoJSON object that is sent with the
getinfoaction from the Splunk software.
- Do not use
$TMPDIR, or any similar strategy to find a temporary directory to write files to. Remember that the maximum length of a path on Windows is 260 characters.
Custom search command example
What's in this section?
This documentation applies to the following versions of Splunk Cloud™: 6.6.3, 7.1.3, 7.0.2, 7.0.3, 7.0.5, 7.0.0