Send-SplunkEvent, a PowerShell cmdlet for sending events to the Splunk HTTP event collector

splunk-hec.psm1

# TODO: write the help
# TODO: support SSL self-signed certs
# TODO: need to validate JSON, and/or add a new param set that accepts hashtable and 
#   convert internally.
# TODO: support RAW mode
# TODO: refactor to use EC batch (concatenated events in one HTTP request) instead of
#   PowerShell pipelines which will do a request per object (event payload) on the pipeline
# TODO: think about load balancing per Geoffrey Martins.


<#
.Synopsis
   Short description
.DESCRIPTION
   Long description
.EXAMPLE
   Example of how to use this cmdlet
.EXAMPLE
   Another example of how to use this cmdlet
.INPUTS
   Inputs to this cmdlet (if any)
.OUTPUTS
   Output from this cmdlet (if any)
.NOTES
   Version: 0.1
#>
function Send-SplunkEvent {
    [CmdletBinding(SupportsShouldProcess=$true, 
        ConfirmImpact='Low')]
    Param (
        # Name or IP address of Splunk server with HTTP Event Collector enabled
        [Parameter(Mandatory=$true, 
            Position=0)]
        [ValidateNotNullOrEmpty()]
        [Alias("cn", "server")] 
        [string]$ComputerName,

        # TCP Port used for HTTP Event Collector
        [ValidateRange(0,65535)]
        [int]$Port = 8088,

        # Authentication token
        [Parameter(Mandatory=$true,
            Position=1)]
        [ValidateNotNullOrEmpty()]
        [guid]$Token,

        # Event body in JSON format. Pass objects through the ConvertTo-Json cmdlet for best results.
        [Parameter(Mandatory=$true,
            Position=2)]
        [string]$EventJSON,
        # Override the host field for this event
        [string]$EventHost,
        # Override the index field for this event
        [string]$Index,
        # Override the source field for this event
        [string]$Source,
        # Override the sourcetype field for this event
        [string]$SourceType,
        # Override the timestamp (Splunk _time field) for this event
        [datetime]$Time,
        # If specified, uses SSL connection to collector. Self-signed SSL certificates (on the Splunk server) are not supported yet.
        [switch]$UseSSL = $false
    )

    Begin {
        if ($UseSSL) { $scheme = "https://" }
        else { $scheme = "http://" }
        $uri = "$scheme${ComputerName}:$Port/services/collector/event"
        $header = @{Authorization = "Splunk $token"}
    }

    Process
    {
        $Event = @{ event = $EventJSON }
        if ($EventHost) {
            $Body.Add("host",$EventHost)
        }
        if ($Index) {
            $Body.Add("index",$Index)
        }
        if ($Source) {
            $Body.Add("source",$Source)
        }
        if ($Sourcetype) {
            $Body.Add("sourcetype",$Sourcetype)
        }
        <# TODO: implement conversion of .NET datetime to Unix epoch
        if ($Time) {
            $Body.Add("time",$Time)
        }
        #>
        $Body = $Event | ConvertTo-Json
        if ($pscmdlet.ShouldProcess($ComputerName, "Send event")) {
            Invoke-RestMethod -Method Post -Uri $Uri -Headers $Header -Body $Body
        }
    }

    End {
    }
}