PowerShell 5.0 Just Enough Administration (JEA) Part 2: Creating Toolkits and Understanding Logs
In the first part of this series, PowerShell 5.0 Just Enough Administration (JEA) Part 1: Understanding JEA and Configuring the Demo Toolkit, I showed you how to install the xJEA PowerShell module, which includes the necessary Desired State Configuration (DSC) resource to configure JEA on one or more servers running the Windows Management Framework 5.0 using the supplied setup script.
In the second and final part of this series, we’ll define our own JEA toolkits, and check the logs to get information on what commands were run, when, where and by which users, via the JEA activity log and the Windows Event Log.
Define a JEA toolkit
In the first part of this series, we created a JEA toolkit that enabled users who connected to run a limited set of commands to kill specific processes on the device, or restart services. Creating a list of cmdlets, parameters and functions that are available in the toolkit can be a little complicated, because it isn’t necessarily obvious how to work with the DSC syntax. But help is at hand in the form of the JEA Toolkit Helper.
Download and run the JEA Toolkit Helper
To expedite the creation of a DSC script to create our own JEA toolkit, I recommend downloading the JEA Toolkit Helper, which is free from Microsoft’s website. The toolkit helper comes in the form of a PowerShell script, which is supported by a GUI.
Before running the script, if you are not logged in using the default administrator account, you will need to disable UAC. For more information on disabling UAC, see Disabling User Account Control (UAC) in Windows 7 on the Petri IT Knowledgebase. The process for disabling UAC in Windows Server 2012 R2 is the same as in Windows 7, and don’t forget to enable UAC once you’re done.
Additionally, you’ll need to set the PowerShell script execution policy to unrestricted before running the JEA Toolkit Helper. To set the policy, open a PowerShell prompt, and run the cmdlet as shown below:
Now we’re ready to run the JEA Toolkit Helper. Right click the downloaded .ps1 script file, select Run with PowerShell from the context menu, and click Open in the warning dialog box. A PowerShell console window will open. Type R in the window and press ENTER to run the script. After a few moments, the script’s GUI will open.
Create a DSC script using the JEA Toolkit Helper
We’ve never used the tool before, so there’s no .CSV file containing information about the cmdlets, parameters and functions we want to make available. In this example, I’m going to set up a toolkit for print administrators, so they can connect to a server, access all the cmdlets available as part of the PowerShell Print Management module, restart the Print Notify and Spooler services, and get basic information about the server’s network configuration.
- Make sure that you are on the Design Helper tab.
- Give the toolkit a name in the box to the right of We are working with the Toolkit named. I’m going to call this toolkit Print.
- Using the drop-down menu to the right of Or you can add a full/partial module, or use it to filter the cmdlets list, select NetTCPIP and then click Add Get-* only. This will allow users to view the server’s configuration, but not modify it. After clicking Add Get-* only, you will see a new row appear in the grid in the bottom half of the GUI.
- Do the same for the NetAdapter module.
- Now select the PrintManagement module from the same menu, but this time click Add to Toolkit. This allows users full access to the Print Management PowerShell module.
- Now using the menu to the right of Or you can pick a cmdlet and – optionally – properties, select the Restart-Service cmdlet.
- Using the next drop-down menu, select the parameter Name from the list, and then click Add to Toolkit.
- In the ValidateSet column to the right of Name, type PrintNotify;Spooler. This will limit users to restarting only the Spooler and Print Notify services.
- At the bottom of the GUI, check the box to the left of Configure Allowed Users.
- In the box to the right of Configure Allowed Users, type Print Operators, and then click Update Delegation.
Note that if you enter values in the GUI that are invalid, error messages are shown in the PowerShell console that started when the JEA Toolkit Helper PowerShell script was launched. Check there for any error messages in red.
The ValidatePattern column allows you to restrict the format in which parameters are specified if required. There’s also an additional column – ParameterType – that’s not accessible via the toolkit GUI, and it allows you to optionally restrict the kind of data that is passed to the endpoint, such as strings only.
- Once you’ve got all the settings in place, switch to the Script output tab, and click Copy to Clipboard at the bottom of the GUI.
- Open PowerShell ISE, copy the script contents into the window, and save the script to a convenient location as PrintEP.ps1.
At the point, in theory you can export the settings to a .csv file, so that they can be imported into the tool at a later time, and import the configuration to the local machine and test it. But in my experience, these options can cause the tool to hang. So to avoid losing all your hard work, I recommend copying the script as described above before clicking any of the other buttons on the Script output tab.
- Now click Export to CSV, and a text file containing the toolkit’s settings will be saved to the desktop, should you need it at a later time.
- Click Import, and then switch to the PowerShell console window.
- Once the import process has completed, you’ll be notified to wait 30 secs before testing the configuration. Click OK in the notification window.
- Back in the JEA Toolkit Helper GUI, click Test. Again, you’ll need to switch to the PowerShell console to see the results.
Test attempts to connect to the new JEA endpoint, and display the available commands. If the account you’re logged in with doesn’t have permissions to connect to the new endpoint, the test will fail.
Logging and reporting
Now that you can configure your own JEA endpoints, all that’s left is to monitor their use. WMI and PowerShell Remoting events are written to the Windows Event Log and can be found in Event Viewer under Applications and Services Logs > Microsoft > Windows > PowerShell > Operational.
The most important event to look for in the Operational log is Executing Pipeline (Event ID 4103). This event contains the important information about the remote user that connected to the endpoint, the local user account that was used to execute commands, what commands were run, when, and the RunSpaceID.
Additionally, JEA logs to the ActivityLog.csv file, which is located at C:\Program Files\Jea\Activity.