Set Up a Script Environment to Access PowerShell
To create a Power Rules script outside the Privilege Management for Windows environment, you must set up a scripting environment. This allows you to access the PowerShell cmdlets you can use to write your script and test it in a mock Privilege Management for Windows environment.
The first steps are to import the following modules:
- PRInterface module: Contains the cmdlets you can use for your script. It is installed with Privilege Management for Windows.
- PRTestHarness module: Allows you to mimic the behavior of Privilege Management for Windows so the rule script behaves as if Privilege Management for Windows was installed.
You can then create an instance of the TestHarness module and provide test data if required.
- Import the PRInterface module. You can import the module to a different environment if you need to work on a script in a separate environment.
- Import the PRTestHarness module.
- Create an instance of the PRTestHarness module. This allows you to work with, and if you choose, stub the PRTestHarness module with test data.
Import the PRInterface PowerShell Module
PRInterface is the name of a PowerShell module that provides cmdlets for the Power Rules script to use to pass information to and from Privilege Management for Windows. Using it you can:
- Manipulate the behavior of a rule
- Provide information about a Privilege Management for Windows event
- Show customizable dialog boxes that display information to, and gather information from, an end user
- Run an application as another user
- Add detail to audit events
You can use the PowerShell cmdlet get-help <cmdletname> to view the full help documentation, including examples, in PowerShell.
You must change the paths to point to your PRInterface folder.
You can import the PRInterface modules, so your script mimics the behavior of the Privilege Management for Windows PowerShell execution environment. The AddAdmin_ExamplesApp.json file in the PRTestHarness folder contains example data you can use to get started.
For a list of variables, please see the Privilege Management for Windows Administration Guide.
To import the PRInterface module:
Import the PRTestHarness PowerShell Module
PRTestHarness is a PowerShell module that provides a mechanism for testing Power Rules scripts outside the Privilege Management for Windows execution environment. This allows you to simulate a Privilege Management event and run a script in PowerShell ISE to see the resulting behavior. This means you can speed up script development by testing and debugging outside the Privilege Management for Windows Power Rules environment.
The test harness mimics the behavior of Privilege Management for Windows. This process is known as stubbing and it allows you to write scripts using the PRInterface module in other PowerShell environments.
You must change the paths to point to your PRTestHarness folder.
To import the PRTestHarness module:
Stub Privilege Management for Windows with PRTestHarness
Each time you want to edit your integration script in a new instance of Windows PowerShell ISE, you need to create a Defendpoint Accessor, and optionally, provide example data to it. This example references the AddAdmin_ExampleApp.json file, which contains example data.
Stub the Privilege Management for Windows interface with some test data:
$global:DefendpointAccessor = New-PRTestHarness -TestConfig 'C:\PowerRules\PRTestHarness\AddAdmin_ExampleApp.json'
Test the Configuration
You can provide the following arguments to the PRTestHarness cmdlet:
[-TestConfig <string>] [-TestSettings <string>] [<CommonParameters>]
Test the data is coming through from the AddAdmin_ExampleApp.json file:
-TestSettings allows you to also specify a path with file name to a Settings file. Settings files are encrypted on the endpoint so any credentials or sensitive information for your integration are protected.
For more information, please see Use a Settings File with a Rule Script File.