Actions

Actions are taken after particular rules' conditions are met. Actions are specified with the New-PSPAction cmdlet.

New-PSPAction -File -Path %temp%\test.txt -Format '{appname},{rule}' -Name 'File'

Action Types

Block

The block action with block users from executing scripts that match the assigned rule.

New-PSPAction -Block

Parameters

Parameter	Description
Block	Enables blocking

File

The file action will append to a file whenever a rule's conditions are satisfied. You will need to define the path and format for the file action.

This example logs all the PowerShell engine application names to a file.

New-PSPAction -File -Path "%temp%\log.txt% -Format "{applicationName}" -Name "File"

Parameters

Parameter	Description
Path	Path to the file to write to. Environment variables are supported.
Format	The formatting string used for writing the message.
Name	The name of this action

Event Log

The event log action writes an audit record to the Windows Application event log using the PowerShellProtect source. Choose the entry type and provide a formatting string.

New-PSPAction -EventLog -EventLogEntryType Warning -Format "{timestamp}, {applicationName}, {rule}" -Name "Event Log"

Event log entries use these IDs:

Entry type	Event ID
Information	101
Warning	103
Error	102

Parameters

Parameter	Description
EventLog	Enables the event log action.
EventLogEntryType	Required. The Windows event log entry type: Information, Warning, or Error.
Format	Required. The formatting string used for the event message.
Name	The name of this action.

TCP

The TCP action connects to a TCP address and port to send a formatted TCP message. This is primarily used for SIEM integration. You will need to specify the hostname, port and format settings. The message is sent as an UTF8 encoded string to the address and port.

This example sends the application name of the PowerShell engine to the machine MYSIEM on port 527.

New-PSPAction -TCP -HostName "MYSIEM" -Port 527 -Format "{applicationName}" -Name "TCP"

Parameters

Parameter	Description
HostName	The host name or address to send the message to
Port	The port to send the message to
Format	A formatting string for the format of the message
Name	The name of this action

HTTP

The HTTP action sends HTTP requests to the configured URL using the specified format. The message is sent as a UTF8 encoded string.

This example sends the application name of the PowerShell engine to an HTTP server.

New-PSPAction -Http -Address "http://powershelluniversal:8080/protect" -Format "{applicationName}" -Name "HTTP"

Settings

Parameter	Description
Address	The URL to send the HTTP request to.
Format	A formatting string for the format of the message
Name	The name of this action.

UDP

Send UDP datagrams to a target hostname and port. You can use formatting strings. Messages are encoded in UTF8.

This example sends the application name of the PowerShell engine to the machine MYSIEM on port 527.

New-PSPAction -UDP -HostName "MYSIEM" -Port 527 -Format "{applicationName}" -Name "TCP"

Parameters

Parameter	Description
HostName	The host name or address to send the message to
Port	The port to send the message to
Format	A formatting string for the format of the message
Name	The name of this action

Formatting Strings

You can use formatting strings to configure the output of the various audit actions (File, TCP, HTTP). You can use the following properties in your format strings.

Properties

Property	Description
Script	The complete script content.
ContentPath	The path to the script if it was executed as a by path name. This will be an empty string if executed from the terminal.
ApplicationName	The name of the application that ran PowerShell. This is typically a string with the format PowerShell_path_version.
UserName	The username of the user that ran that command.
ComputerName	The name of the computer running the command.
Administrator	Whether the PowerShell process has administrative permissions.
DomainName	The name of the user's domain running the command.
Rule	The rule that triggered the action.
TimeStamp	The UTC time stamp of the message.

Syntax

The property name will be replaced by the value. Put the name of the property and brackets.

{timestamp}, {applicationName}, {rule}

Examples

TCP to SIEM

In this example we are logging any use of a command containing "webrequest" with a TCP request to a SIEM (such as Splunk)

$Condition = New-PSPCondition -Property "command" -contains -Value "webrequest"
$Siem= New-PSPAction -File -Format "{applicationName},{rule},{UserName},{ComputerName},{ContentPath},{Administrator},{DomainName}" -HostName "12.34.45.67" -Port '514' -Name 'Siem'
$Rule = New-PSPRule -Name "Web Request" -Condition $Condition -Action $Siem
$Config = New-PSPConfiguration -Rule $Rule -Action -Action @($BlockAction, $FileAction)

Test-PSPConfiguration -Configuration $Config -ScriptBlock { Invoke-WebRequest "https://www.ironmansoftware.com" }