Skip to main content
Skip table of contents

Create the Payload

SmartResponse Plugin consists of the following two elements that must exist under a single root folder structure:

  • Payload. The payload consists of executables, scripts, and other supporting file types. The payload defines the actions that are taken by the SmartResponse after initiation.
  • Configuration File. The configuration file indicates the input and output parameters of the SmartResponse Plugin and tells the SIEM how to activate the response.

Both elements are combined into a re-distributable plugin.

Create the Payload

Although a SmartResponse can call any executable program, Windows PowerShell is the most common type of payload. PowerShell offers an incredible range of scriptable capabilities and is installed by default on most systems that have either a LogRhythm Platform Manager or a LogRhythm Windows System Monitor. If your targeted action is not installed by default on the execution system, you will have to install it so that the SmartResponse Plugin can execute.

The PowerShell payload must be designed in a way that it:

  • Accepts command line arguments.
  • Performs proper error handling.
  • Executes an action.
  • (Optional) Writes any output to standard out.

To use the SmartResponse as part of a context operation, write any messages to standard out (typically using Write-Host in PowerShell). When the SmartResponse Plugin is executed from the Web Console, the output from standard out maps to a display window so that an analyst can review and act on the information.

PowerShell Scripts as a SmartResponse Plugin Payload

SmartResponse Plugins can run on the LogRhythm Platform Manager (W2K8R2 or W2K12) or on a v7.0 or higher LogRhythm System Monitor running on Windows XP.

While administrators can use any executable file for a SmartResponse action, PowerShell is the most commonly used scripting language for SmartResponse. Since Microsoft has included it with all versions of Windows since Windows 2008, and it can be installed on all versions since and including Windows XP, it is one of the most widely available scripting platforms within the Microsoft Windows ecosystem. The minimum supported version of PowerShell is v2. If the plugin requires a newer version then this is included in the documentation accompanying the plugin, or as a validation step in the PowerShell Script itself.

PowerShell best practices specific to SmartResponse Plugin scripts are listed below. General guidelines and best practices for PowerShell are beyond the scope of this document.

Comments in PowerShell

As a best practice, provide useful comments in the PowerShell script. The comments should give a description of what the script is intended to accomplish, note any limitations, and provide explanations of specific logic. LogRhythm recommends specific comments for SmartResponse Plugins that describe which LogRhythm data should be supplied and whether the script runs on the Platform Manager or a System Monitor.

The following is an example of the header comments listing what LogRhythm components can execute the script:

# ScriptName.ps1 
# Author 
# Date created 
# Description 
# Required version of PowerShell (or specify if supported on any version) 
# This PowerShell script should only be run on the Platform Manager 
# This PowerShell script should only be run on an Agent 
# This PowerShell script can be run on the Platform Manager or an Agent

Command-Line Parameters

PowerShell offers a number of ways for scripts to consume command-line parameters. The most important thing is that the script consumes them in a robust manner, since the plugin containing the PowerShell is run silently by the ARM or System Monitor process. Note that the PowerShell execution policy should be set to All-Signed before executing any SRP.

The following example shows the preferred method for consuming command-line parameters. This provides clear feedback to the LogRhythm or Web Console if an invalid parameter is passed, supports both positional and named parameters, and allows parameters to be mandatory or optional.

Using CmdletBinding() provides Verbose and Debug options. The binding command and parameter definitions must be the first executable lines in the script (including before the exception handling), otherwise the script will not work.

[CmdletBinding()]
Param(
[Parameter(Mandatory=$True,Position=1)]
[string]$computerName,
[Parameter(Mandatory=$True)]
[string]$filePath
)

In this example, two parameters are passed to the script. The first is mandatory, and is defined as being in position 1. This parameter may be passed without specifying its name by placing it in position 1 at the command prompt, since the position is defined. Alternatively, the parameter name may be specified. The second parameter is also mandatory, but no positional value is given, so this parameter must be passed as a named parameter at the command prompt.

The SmartResponse Plugin configuration file supports using positional or named parameters. Positional parameters are defined by the Order field, whereas named parameters are defined by the Switch field. A trailing space must be included within the quotations marks:

<remv1:StringParameter Name="StringParam1" Switch="-StringParam1 " Order="Unsorted">

For clarity, each SmartResponse should use either all positional or all named parameters, and not a combination of the two to avoid confusion.

Debugging Scripts

Using the CmdLetBinding() approach to parameters provides Verbose and Debug logging methods. Any PowerShell script using CmdLetBinding() may be called using a -verbose or -debug switch. There is no need to provide any parameters or code handling for this switch.

  • If -verbose is used as a command-line parameter, it activates any Write-Verbose commands in the script. Output is written to the command prompt in yellow text with the prefix of "VERBOSE:".
  • If -debug is used as a command-line parameter, it activates any Write-Debug commands in the script. Output is written to the command prompt in red text with the prefix of "DEBUG:".

This has the effect of allowing Write-Debug and Write-Verbose statements to be placed inline in the code for the purposes of debugging or troubleshooting, but those statements will automatically be ignored if the appropriate switch is not specified on the command line.

It is sufficient for most SmartResponse plugins using PowerShell script to implement either Verbose or Debug. It is unnecessary to implement both.

Errors and Exceptions

PowerShell offers a variety of ways to handle errors and exceptions in scripts. Errors and exceptions may be included at a variety of levels, and the mechanisms provided can be nested so that different exceptions and errors are handled in different ways.

Write-Error and Write-Host are typically used to report errors in the PowerShell script. The SmartResponse framework captures standard and error output and writes it to the agent log. Additionally, the output is sent back to the SmartResponse interface to be displayed in the output field.

It is recommended to include a high-level exception handling routine for the whole script. The following example provides some guidance:

trap [Exception] {
write-error $("TRAPPED: " + $_)
exit 1
}

This locates any terminating exceptions and exits the script with an error code.

Implement more focused error handling for specific scenarios using the try/catch/finally construct. For example:

try
{
1/0
}
catch [DivideByZeroException]
{
Write-Host "Divide by zero exception"
}
catch [System.Net.WebException],[System.Exception]
{
Write-Host "Other exception"
}
finally
{
Write-Host "cleaning up ..."
}

PowerShell Execution

Permission to execute PowerShell scripts is governed by an Execution Policy. The PowerShell ExecutionPolicy setting allows restricting from where and what types of scripts can be executed. By default, Windows only allows interactive shell use.

The following are the possible states of an ExecutionPolicy:

  • Restricted
  • Unrestricted
  • AllSigned
  • RemoteSigned
  • Bypass

In addition to the ExecutionPolicy, there are a number of different scopes for the ExecutionPolicy:CurrentUser, Machine or Process. For more information, see About Execution Policies on Microsoft’s Website.

LogRhythm recommends the following for all customers:

  • Set the ExecutionPolicy on hosts that run SmartResponse to AllSigned for the scope of the service account running the SmartResponse.
  • Digitally sign PowerShell Scripts developed for use in SmartResponse with a trusted code signing certificate before the plugin is created for final release.

The ExecutionPolicy may already be defined via GPO or otherwise.

Sample PowerShell Script "AddItemToList.ps1"

The following sample PowerShell script follows the pattern of most SmartResponse payloads. The error handling and argument parsing are standard. Variability between different SmartResponse Plugins comes from what functions are executed after parsing the arguments.

This script has been reduced to the most simplified format for readability, and does not conform to all best practices.

#Simplified AddItemToList PowerShell Payload
#Note that some error handling, argument validation and other logic
#has been simplified or removed for this guide


#Handle exceptions by writing them to the console output. Errors will appear in the
#SmartResponse Plugin manager during testing.
        
trap [Exception] {
write-error $("TRAPPED: " + $_)
exit 1
}


#Read command line arguments. First argument is file name, second item is text to add to file
$OutputFileName = $args[0]
$ItemToAdd = $args[1]


#Set path for output files.
$Path_32 = "C:\Program Files (x86)\LogRhythm\LogRhythm Job Manager\config\list_import\"
$Path_64 = "C:\Program Files\LogRhythm\LogRhythm Job Manager\config\list_import\"


#Add ItemToAdd to the file
if ((Test-Path -path $Path_32)){
$FilePath = $Path_32 + $OutputFileName
Out-File -FilePath $FilePath -InputObject $ItemToAdd -NoClobber -Append
}
if ((Test-Path -path $Path_64)){
$FilePath = $Path_64 + $OutputFileName
Out-File -FilePath $FilePath -InputObject $ItemToAdd -NoClobber -Append
}


#Write output to let analyst know task is complete
Write-Host "new item added to list"

To simplify testing and evaluation of your code, LogRhythm recommends writing one script per action and keeping the function logic as simple as possible. Avoid using switch logic to make a single script perform multiple actions based on an input argument. It is often better to make multiple actions to keep the logic cleaner, and make the code more testable and re-usable.

The sample payload consists of a single action. Execute the payload by typing the following in a command line prompt:

C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe –file AddItemToList.ps1 importfile.csv additem


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close