New Module: PSSplunkSearch
As often happens when I’m doing my day to day job, I’m asked to start watching something. I go to the website of our app (in this case Splunk), type in the query and do the search. Have to do this 4 or 5 times throughout the day. I don’t know about you, but I find this really annoying. I’m not entirely sure why, but just typing something at the command line is just so much easier for me, better yet just writing a quick script with all my parameters in it and running it for a quick look. And hence, PSSplunkSearch is born–because spending 4-5 days writing a new module to complete a task I only had to do for one day is totally efficient, right?
A little about Splunk
I don’t profess to be an expert in Splunk–far from it–so writing this module was a lesson in how searches work in Splunk. A standard search is you submit a query to Splunk and it runs on the server (this is a Search Job), when done you can retrieve the results. But how best to do this from a module standpoint? The easiest would be to just run the search, wait for it and then pull the results all in one function–and in fact that’s exactly how the module started. For me though, I hate assuming I know best what you are going to do. Maybe you’re going to be running some huge query that’ll take hours to complete and don’t want to run a script the whole time waiting for it? Maybe you have a scheduled search that kicks off and you want to watch that from PowerShell?
With that in mind, I decided to split those three actions up into their own discreet functions modeling after the PowerShell PSJob workflow. The three primary functions are:
With a few ancillary functions needed:
| Function | Description |
| Connect-Splunk | Use this function to authenticate to Splunk. You need to provide the server name for you Splunk server here. |
| Disconnect-Splunk | Use this function to disconnect from Splunk. |
| Get-SplunkSearchJob | Use this function to get detailed information about a search job |
| Get-SplunkSearchJobList | List all of the search jobs currently stored on the server |
| Remove-SplunkSearch | Remove a search job from the server |
This is enough to get your search run, and the data retrieved. The workflow would look something like this:
- Connect-Splunk
- Start-SplunkSearch
- Wait-SplunkSearch
- Receive-SplunkSearch
- Remove-SplunkSearch
Below is an example of searching your Splunk server for the event ID 4740 (user locked out). Because you’ve done a good job indexing your information you created an index on your Splunk server called “domain_controller” which has isolated all event’s from your DC’s. By default, PSSplunkSearch will default to just 1 day for the search–we don’t want to overwhelm your server! In this example though, we need to search for lock outs between 2/20/21 and 2/22/21.
Connect-Splunk -Server splunkserver.mydomain.com
$SearchJob = Start-SplunkSearch -Query "EventCode=4740" -Index "domain_controller" -Start "2/20/21" -End "2/22/21"
$SearchJob | Wait-SplunkSearch
$Data = $SearchJob | Receive-SplunkSearch
$SearchJob | Remove-SplunkSearchInvoke-SplunkMethod
Let’s talk a little bit about one other function in the module, Invoke-SplunkMethod. This is really just a wrapper for Invoke-RestMethod with some specific Splunk requirements. Normally I would hide this function away as a private function so it’s only available to the module functions and not to you as a user. But I broke my rule here because I recognize that Splunk is a lot bigger then search. I mean a lot bigger. I don’t know that I will ever add additional functionality to this module, but that doesn’t mean you might not have additional tasks you want to do. Hopefully Invoke-SplunkMethod will help you get there without having to code everything–authentication, server name and port, etc.
Streaming a search
Ok, before you start yelling at me, yes I know you can stream results from the API. I chose not to do this because I had to focus on something and I wanted to model the module after the PSJobs thing. I may add this functionality later on, as I can foresee a need to do a running search. Maybe you’re running something and you need to see if any errors start coming in, and you’ll be doing live monitoring for awhile. As with any development project, you have to draw a line on where you stop before getting the product out there.
I very much consider this an MVP release, and I hope you like it!
PSSplunkSearch
Sorry, the comment form is closed at this time.
Me
LinkedIn
The Surly Admin 