PowerShell Protect

PowerShell Protect integration for PowerShell Universal.

PowerShell Protect is a feature of PowerShell Pro Tools. It allows you to audit and block PowerShell scripts and PowerShell command lines that are executed on your machine. You can deploy the client piece and then configure it using PowerShell Universal. PowerShell Universal can also be used as a collection mechanism for events generated by PowerShell Protect. Additionally, PowerShell Universal can trigger scripts when certain rules are triggered.

You can access PowerShell Protect tooling by navigating to Security \ Protect.

Configuring PowerShell Protect

PowerShell Protect is configured via XML. PowerShell Universal can be used to create this XML. Navigate to the PowerShell Protect page and then click Configurations. Click Create New Configuration and name the configuration you are creating.

Default Rules

Default rules are configured that will block certain behaviors without additional configuration. You can choose to disable any rules you may not desire to enforce.

Actions

Actions are the result of custom rules triggering based on scripts being run. You can take actions such as blocking the script, sending the event to the event log or sending the event to PowerShell Universal.

Depending on the action selected, you will need to include additional settings. For example, to integrate with PowerShell Universal, you will need to define the HTTP address of the PSU server and an app token used to authenticate against PSU.

Custom Rules

Custom rules can be defined to match features of a script being run. For example, you can match the user, script content, variables and domain being used to run a script. If the custom rule matches, you can then execute one or more rules that you have defined.

License

PowerShell Protect requires a PowerShell Pro Tools license for each user that will have the client installed. You can include the license information on the license tab. It will be included as part of the configuration file.

Installing a PowerShell Protect Config

Once you have completed your configuration, you can navigate back to the Configurations page and download the XML.

You can learn how to install PowerShell Protect configurations here.

Events

When you configure a rule to use the Universal action, events will be populated within the Events tab of PowerShell Universal.

Triggers

When you configure a rule to use the Universal action, events can also trigger scripts. From the Automation \ Triggers page, create a new trigger and set the Event to PowerShell Protect Event. Then, you can choose to filter down which rule causes the trigger to fire.

The $ProtectEvent parameter will be passed to your script. This object contains the following properties.

Name	Type	Description
Rule	String	The name of the rule that trigger this script.
Script	String	The content of the script executed.
ContentPath	String	The script path. If run from the command line, this will be null.
ApplicationName	String	An application name identifier. This may include the application version.
UserName	String	The user that ran the script.
ComputerName	String	The computer name of where the script ran.
Administrator	Boolean	Whether or not the user had admin access while running the script.
DomainName	String	The domain name of where the script was run.
Timestamp	DateTime	When the script was run.