Create the Configuration File

Based on the payload, you next create a SmartResponse configuration file called actions.xml. This file defines actions taken by the plugin and provides a mechanism for passing arguments to the plugin.

The Basic Configuration File

The XML wrapper consists of a mandatory header and one or more action blocks. The header names the SmartResponse and assigns it a unique identifier (GUID). Each action section has two basic tasks. First, to define the functions performed by the SmartResponse. Second, to map input fields from the SIEM into command line arguments for the action. A simple version of this file completes the following:

• Defines a single action.
• Requires "-file AddItemToList.ps1" as the first command line argument.
• Provides the filename as the second command line argument.
• Provides the item to add as the third command line argument.

The last two are string values that need to be dynamically set at runtime. Each time you run the SmartResponse, there is a chance you add a different item to a different list.

This full configuration file would appear follows:

<?xml version="1.0" encoding="utf-8"?>

<remv1:Remediation-Plugin xmlns:remv1="RemediationVersion1.xsd" Name="Add Item To List">

<remv1:Action Name="Add Item To List" Command="C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe">

<remv1:ConstantParameter Name="Script" Switch="-file AddItemToList.ps1" Order="1" />

<remv1:StringParameter Name="Auto Import File Name" Switch="" Order="2" />

<remv1:StringParameter Name="Item To Add" Switch="" Order="3" />

</remv1:Action>

</remv1:Remediation-Plugin>

The configuration file must be named actions.xml.

Note the following items in bold in the sample configuration file above:

• The plugin is named Add Item To List.
• The plugin contains one action, also called Add Item To List, that calls powershell.exe.
• The first command line parameter is always -file AddItemToList.ps1.
• The second command line parameter is a filename with no command line switch.
• The third command line parameter is the item to add, with no command line switch.

The configuration file must model the expected parameters of the command line prompt execution of the payload. When you start writing the configuration file, refer to how you would expect to execute the response in the command line prompt.

A Complex Configuration File

In the previous section, we used a simple configuration wrapper with one action and simple parameters. In this section, we cover all of the optional elements in the wrapper and more complex configurations.

The XML Header

The configuration file is provided as an XML document which starts with an XML header (see the following example) and a schema reference defining the file as a plugin.

<?xml version="1.0" encoding="utf-8"?>

<remv1:Remediation-Plugin xmlns:remv1="RemediationVersion1.xsd" Name="PluginName" Guid="00000000-0000-0000-0000-000000000000" Version="1" IsLogRhythmPlugin="false">

The initial tag consists of the following key attributes:

• The XML namespace. All of the SmartResponse wrapper syntax is defined in RemediationVersion1.xsd and all tags in the namespace start with "remv1:."
• Name. Every plugin must have a unique Name, as the name field is used to identify the script to the Plugin Manager.
• GUID. The Guid is an optional tag to uniquely identify the plugin in your SIEM environment. In the XML, you must use the exact capitalization of Guid, not GUID.
• Version. The optional Version tag manages multiple versions of the same plugin.
• IsLogRhythmPlugin. This optional tag is reserved for LogRhythm internal use. You must omit it or set it to false. If you set this attribute to true, you must also supply LogRyhthm’s license and sign the plugin (which cannot be done outside of LogRhythm).

Historically, few plugins have included the Guid, Version and IsLogRhythmPlugin attributes, and the XML can be created without these elements. The console generates a GUID for you if it is not included in the plugin.

The following shows the simplest possible XML header and closing tag. This wrapper has no actions and would be ineffective deployed in this way.

<?xml version="1.0" encoding="utf-8"?>

<remv1:Remediation-Plugin xmlns:remv1="RemediationVersion1.xsd" Name="YourPluginName">

</remv1:Remediation-Plugin>

In version 7.2.2 and higher, the SmartResponse Plugin Manager requires the Guid, Version and IsLoGrhythmPlugin attributes in the XML. The minimal XML header is therefore:

<remv1:Remediation-Plugin xmlns:remv1="RemediationVersion1.xsd" Name="YourPluginName" Guid="00000000-0000-0000-0000-000000000000" Version="1" IsLogRhythmPlugin="false">

If you upload a plugin with a duplicated GUID, you are prompted to replace the existing or create a new one for that plugin. The collision detection makes uploading a standard "000" GUID acceptable.

If present in the configuration file, the GUID and version display in the Console and are used as identifiers. If not, the plugin manager automatically generates both fields when the plugin is created.

The Action Section

A SmartResponse exists to perform actions. The Action section gives us a way to define what action to take, and what parameters to pass into the action from the Alarm.

The Action tag defines a name for the action and a command to execute. The tag may also contain additional xml parameter elements. For example, the following action tag defines an action to open PowerShell:

<remv1:Action Name="PowerShell" Command="C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe">

ParametersGoHere

</remv1:Action>

A plugin may define a single action, or it may define multiple actions. Therefore, there may be several Action elements within the configuration file, each representing an individual action related to the overall plugin purpose. For example, an NG Firewall may expose an API that offers multiple actions that may be initiated, and these actions may be delivered in a single SmartResponse Plugin. Placing multiple actions in a single plugin is simply an administrative convenience. Doing so has no effect on the eventual action of the plugin. Each action can exist in a standalone SmartResponse Plugin.

The Action Name Field

The name field provides a textual description of what the action does, and must be unique within the plugin. There is no requirement for it to be unique within the LogRhythm deployment. The action name may be the same as the plugin name. This is typically the case when a plugin only delivers one action. You can also have several named Actions contained within the plugin.

In the LogRhythm Console, the action displays as <plugin name>:<action name>. Long names may wrap or not display fully. The best practice is to keep the names as short as possible while maintaining descriptive clarity.

The Action Command Field

The Command attribute provides the fully qualified path and name of the application which executes to complete the action. This Command field can be any executable program that is installed on the Platform Manager or System Monitor. The best practice is to include the fully qualified path of the binary to be executed to avoid deliberate or inadvertent launching of a different binary.

In the case of PowerShell scripts, the command is the script engine "powershell.exe" with a fully qualified Windows path.

<remv1:Action Name="YourActionName" Command="C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe">

If the path to the binary cannot be resolved, the plugin fails at run time. The resulting error message in this case is a generic failure message and not indicative that the command or command path is missing or incorrect.

Parameters

Very few SmartResponse Plugins are stand-alone actions that can be run without any input parameters. In fact, the main purpose of a SmartResponse is to take action based on information present in an alarm. The Action XML tag can contain Parameter tags to pass additional data into the executable defined in the Command attribute.

Parameters may be defined as one of the following:

• Constant. Constant parameters are fixed and never change. The most common use case is to pass a script name into PowerShell.
• String. String parameters can be changed when the system is deployed. Use Input subtags to map string parameters to values in the SIEM alarm. For more information on Input tags, see inputvalue.
• Encrypted Parameter. A third type of parameter tag, called EncryptedParameter, is a wrapper tag around a StringParameter. For more information, see encrypted.

Common Parameter Attributes

All parameters share a common set of attributes within the tag:

• Name. The name defines the parameter and is useful for understanding the intended purpose of the parameter.
• Switch. If present, the switch is the integral part of a command line parameter when named parameters are used.
• Order. The order field is used to indicate the order of the parameters. Order can contain a number indicating the parameter position, or a text value of unsorted parameters.

Switch and Order are used to indicate named or positional parameters. As a best practice, use either named or positional parameters in an action, but not both. Incorrect or blank ordering for the parameters may result in an error when creating a new SRP xml.

If you are using a mix of named parameters and ordered parameters that do not have switches, make sure that the switch field contains a single space.

Constant Parameter

Constant parameters are command-line arguments fixed for the action regardless of how the SmartResponse is initiated.

A ConstantParameter always remains the same, and cannot be configured by the user or alarm that triggers the SmartResponse Plugin. These parameters are useful for fixing a command line parameter within the context of a particular action.

<remv1:Action […] Command="C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe">

<remv1:ConstantParameter Name="DisplayName" Switch="-File Sample.ps1" Order="Unsorted"/>

</remv1:Action>

A good use case for a ConstantParameter occurs when an Action tries to execute a PowerShell script called "Sample.ps1." The full command line for this would be "powershell.exe –File Sample.ps1." As discussed previously, the Action would have Command set to "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe." A ConstantParameter would be set to the complete value "-File Sample.ps1" which indicates the script to run. In this case, we always run this script regardless of any other parameters or configuration to the SmartResponse.

<remv1:Action Name="Test" Command="C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" > <remv1:ConstantParameter Name="Script" Switch="-nop -file Sample.ps1 " Order="1" />

In LogRhythm 7.0 or higher, the SmartResponse Switch attribute for PowerShell scripts must be in the following format: "-File Sample.ps1". This is because the PowerShell binary has the ability to directly ingest PowerShell cmdlets as arguments from the command line. This could lead to the SmartResponse being used for remote code execution in limited circumstances. Using the "-File" method of specifying the script prevents abuse of PowerShell.

String Parameters

String parameters are command-line arguments that may be different each time an Action is executed depending on how the LogRhythm Administrator configures the plugin for a particular alarm. A string parameter’s value can be set at either configuration time (in which case it never changes for that particular configuration) or at run time (in which case it changes every time the response executes).

String parameters allow the definition of command line switches or parameters by name using user defined strings instead of a constant that is fixed for the plugin action.

The following example would add a parameter called DisplayName. This value is passed on the command as an argument called "address:" as defined in the Switch attribute.

<remv1:Action …>

<remv1:StringParameter Name="DisplayName" Switch="\address: " Order="Unsorted"/>

</remv1:Action>

The actual value passed is extracted at runtime as either a static value set by the administrator when configuring the SmartResponse, or as a dynamic value injected from the alarm or event.

It is critical that the Switch attribute contains the complete command line switch including the prefix (most commonly ‘\’ or ‘-‘) and the delimiter (most commonly ‘:’ ‘=’ or a space). Command-line programs vary widely on how well they support variation in the switch prefix and delimiter. The only way to ensure the value provided matches expectations is to require the information in the parameter definition.

In order to execute a remediation action, all string parameters must completely resolve their arguments prior to executing the SmartResponse action. The values are determined at runtime based on how the LogRhythm administrator configures the SmartResponse for the alarm. The value might be a metadata field passed through from the alarm, or a fixed value manually set when the alarm is configured.

You can pre-define default values using Input Value tags. Input tags are optional and only used to simplify the deployment process. For more information, see inputvalue.

Encrypted Parameters

Encrypted Parameters modify the behavior of a String Parameter so that the value is stored with additional encryption.

An Encrypted Parameter has no options and simply wraps an existing String Parameter. Encrypted parameters identify another parameter as one whose value contains sensitive information (e.g., a password or community string). When a parameter is identified as encrypted, any input value assigned to that parameter when the SmartResponse is configured for an alarm is encrypted when it is stored in the EMDB.

<remv1:Action …>

<remv1:EncryptedParameter>

<remv1:StringParameter Switch="\switch:" Order="Unsorted"/>

</remv1:EncryptedParameter>

</remv1:Action>

Using the EncryptedParameter tag forces the executor of the plugin (the Platform Manager or System Monitor) to leverage the LRcrypt tool to encrypt the values passed in the string parameter. LRcrypt leverages Windows libraries for encryption. The default behavior is to use an AES algorithm. The actual algorithm choice depends on how the Windows environment is configured.

Use encrypted parameters sparingly since not everything is sensitive. Parameters that use information from an alarm or event do not require encryption because the information is already provided in plain text. Typically items such as passwords and API keys should be encrypted. Additionally, it is recommended that Encrypted Parameters are not provided with a Default Input Value, because that value is stored in the configuration file in plaintext and is contained within the plugin.

Input Values

A String Parameter can optionally contain sub-tags that define a default value or pre-configure the value to be filled from specific metadata. Input parameters are optional in the configuration file, but reduce the time it takes to deploy and configure a SmartResponse.

Input Values can be one of the following types:

• Static. Configured by the LogRhythm administrator and does not change on a per-alarm basis.
• Metadata. Deteremined by the data contained in the alarm or event triggering the SmartResponse. These values change on every execution of the SmartResponse.

Input values are optional. Using them in the configuration file reduces the time it takes to deploy and configure a SmartResponse, but makes the configuration file more complicated.

Both Static and Metadata input values must be contained inside a DefaultInput tag:

<remv1:StringParameter … >

<remv1:DefaultInput>

<remv1:StaticInput Value="127.0.0.1" />

</remv1:DefaultInput>

</remv1:StringParameter>

In this example, a default static value of 127.0.0.1 is passed to the string parameter. A LogRhythm administrator can override this value when configuring the SmartResponse. The value is an initial default setting.

Static Input Values

Static Input values are entered by the LogRhythm administrator when the SmartResponse Plugin is configured against a particular alarm rule. Once configured, these values remain the same every time the plugin is called by the specific alarm.

<remv1:StringParameter …>

<remv1:DefaultInput>

<remv1:StaticInput Value="DefaultInputValue" />

</remv1:DefaultInput>

</remv1:StringParameter>

Using a String Parameter with a Static Default Input value is similar to using a Constant Parameter, with one exception. This pattern provides an override mechanism where the administrator can either accept the default or replace it with a new value when registering the response. Default Input values act as built in context-sensitive help or suggestions. An example of this is a SmartResponse that calls a firewall API—the administrator enters the IP address of the firewall as a Static Input value since it would always remain the same within this deployment.

Metadata Input Values

Metadata Input values are dynamic values included when the SmartResponse executes. The LogRhythm administrator maps the Metadata Input to a particular alarm field when the SmartResponse Plugin is configured.

Each field of the alarm or event has its own tag that can be used to specify the intended metadata field. In the example below, the default value for the StringParameter is populated with the destination IP address of the first action associated with the alarm. For more information and a list of supported Metadata Input values, see Appendix A: Metadata Inputs on page 26.

<remv1:StringParameter …>

<remv1:DefaultInput>

<remv1:DIP />

</remv1:DefaultInput>

</remv1:StringParameter>

An example of this would be a SmartResponse that is going to call a Firewall API to block a destination IP address. The administrator might select the destination IP address metadata field from the alarm as the Metadata Input value since the IP address to be blocked varies depending on the event that triggered the alarm.

Metadata field names are case sensitive. If you do not use the correct capitalization, you will get errors when you import the SmartResponse.

The following reference table provides information about the fields that are consumable by a SmartResponse plugin and additional guidance on working with date formats in the data fields. Each SmartResponse is triggered by an alarm. Depending on the alarm configuration, different fields are available for use in the SmartResponse.

<remv1:BytesIn />

Formatted Metadata Input

Several metadata fields contain date and time stamp values. Use a TimeFormat tag to force these metadata fields to conform to the desired format.

<remv1:AlarmDate>

<remv1:TimeFormat TimeZone="Eastern Standard Time" FormattingString="MMMM dd, yyyy" />

</remv1:AlarmDate>

The structure of the TimeFormat tag contains the following attributes:

• TimeZone. Allows you to configure a specific time zone to convert the date and time output. Inside the configuration the time zone is specified by the Windows ID used for the time zone (this value can be looked up within the Windows Registry under HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Time Zone). If no value is provided, the time zone of the machine creating Remediation Actions is used (either the Platform Manager or the System Monitor depending on configuration).
• FormattingString. Defines the format of the date and time information. This allows you to customize which parts of the date and time are available to the executing program and what structure this information has. Omitting this option causes the date and time to be formatted by the default .NET date/time format. See the following for more information about the default .NET date/time formats:

MSDN: Standard DateTime Format Strings

MSDN: Custom DateTime Format Strings

Since both of these values are optional, there are four permutations TimeFormat can take. However, any field accepting a TimeFormat must have exactly one TimeFormat specified.

• Default Values for the output format and time zone:
  

  <remv1:TimeFormat />

• Specify only the Time Zone, Use the .NET Date Time Format:
  

  <remv1:TimeFormat TimeZone="Eastern Standard Time" />

• Specify only the Format, Use the Event Manager’s Time Zone:
  

  <remv1:TimeFormat FormattingString="MMMM dd, yyyy" />

• Specify both the Format and the Time Zone:
  

  <remv1:TimeFormat TimeZone="Eastern Standard Time" FormattingString="MMMM dd, yyyy" />

<remv1:BytesIn />