StealthINTERCEPT 7.1 ships with a library of cmdlets for PowerShell (PS) which allows PS scripts to perform a majority to the configuration and control tasks normally carried out by the StealthINTERCEPT Administrators console. This opens up a variety of automation and 3rd party product integration possibilities. The StealthDEFEND product makes use of these same PS cmdlets to interact with StealthINTERCEPT.
In order to use the PS Cmdlets the PS user must be an ‘administrator’ level user of the StealthINTERCEPT (SI) Console.
Load the SI PowerShell Module
The following two steps are to load the SI PowerShell module and connect to the SI Server. These steps are required with each PowerShell session before using the available cmdlets.
The command below assumes the StealthINTERCEPT Server installation directory is on the C drive on the server where the PowerShell console resides. However, the installation directory can be set to a custom location during SI installation.
Step 1 – Run the following command to load the PS for SI module into PowerShell. The following example assumes the default installation directory, but a custom path can be used. See the end of this article for the file set needed to use PS from a machine that does not have the SI Server / Enterprise Manager installed.
Import-Module “C:\Program Files\STEALTHbits\StealthINTERCEPT\SIEnterpriseManger\SI.SIMonitor.PowerShell.dll”
Step 2 – Connect to the Enterprise Manager using the Connect-SIEnterpriseManager command. The following parameters may be used:
- Address [String] – Enterprise Manager IP address, default is 127.0.0.1
- Port [String] – Enterprise Manager Port, default is 3740
- Reconnect [Bool] – Reset connection and make a new one
Example of Connect-SIEnterpriseManager using two of the above parameters:
Connect-SIEnterpriseManager -A 192.168.189.57 -R 1
Note the Port does not need to be specified if SI was installed using the default port 3740.
Upon completion of the above two steps, all the SI PS Cmdlets are available for use. Two important Cmdlets to learn are:
Get-SIHelp and Get-Help
Get-SIHelp returns a list of the available SI PS Cmdlets
Get-Help [cmdlet name] and Get-Help [cmdlet name] –Example return usage information and a usage example for the specified cmdlet respectively.
Armed with the above Cmdlets it is easy to explore the details of all the available SI PS Cmdlets. Following is a summary for the available SI PS Cmdlets by category:
- Initial Configuration:
- Connect-SIEnterpriseManager – connect to specified Enterprise Manager Server
- Informative APIs
- Get-SIAgentStatus – Displays Agent status for all SI agents
- Get-SIHelp – Lists available PowerShell APIs for StealthINTERCEPT
- Get-Help – Displays detailed information about a specified PowerShell API
- Policies and Collections:
- Get-SIPolicy – returns a list of policy ID’s including their Name and GUID
- Enable-SIPolicy – Enable or Disable a policy by ID obtained from Get-SIPolicy
- Remove-SIPolicy – Delete a policy by ID obtained from Get-SIPolicy
- Export-SIPolicy – returns specified policy ID as XML text (tip: redirect to a file using “>>”)
- Import-SIPolicy – reads XML from specified file, replaces or adds to SI based on ID & GUID
- Get-SICollection – returns a l list of collection ID’s including name, GUID, type and size
- Remove-SICollection – Delete an SI collection based on ID obtained from Get-SICollection
- Export-SICollection – returns specified collection ID as XML (tip: redirect to file using “>>”)
- Import-SICollection – reads XML from file, replaces or adds to SI based on ID & GUID
- Enterprise Password Enforcement (EPE):
- Test-ValidatePassword – reports if input string passes active EPE rules with reason(s) if not
- Export-SICharacterSubstitution – returns current EPE Character substitution map
- Import-SICharacterSubstitution – replaces current EPE Charter substitution map
- Export-SICharacterSubstitutionWords – returns current EPE substitution word list
- Import-SICharacterSubstitutionWords – replaces current EPE substitution word list
- LDAP Deception for StealthDEFEND:
- Get-SILdapDeception – returns current LDAP Deception match and replacement strings
- Set-SILdapDeception – sets LDAP Deception match and replacement strings
SI Policy XML
SI Policies and Collections are fully defined via XML. At first, the StealthINTERCEPT XML schema can seem very daunting. There is a simple way to ‘learn by example’ what must be in the XML to create a new policy or alter an existing policy. For the sake of this article, we will assume the reader is already familiar with creating and editing SI Policies and Collections using the SI Console.
The general idea is to ‘model’ our desired policy or policy change in the SI Console and then leverage the Policy Export capabilities in the SI Console. As an example let’s use the default “AD: Group Membership Changes” policy which reports changes made by any user. For our example, we want to change it to report only changes not made by users in the “Domain Admins” group.
First we will export the unmodified policy to a file.
- In the SI Console click on the “Policies” node in the “Policy Center” tree view
- In the right panel under “Policies” find and right-click on the ““AD: Group Membership Changes” policy
- Pick ‘Export’ from the right-click menu and press the Export button and enter the desired filename.
Now using the SI Console edit the policy by adding the Domain Admins group to the Exclude section of the “AD Perpetrator” filter tab and save the policy. Repeat the steps above to export the policy to a new name.
Next using the compare tool of your choice (we like Beyond Compare) load the two XML files. We can ignore the couple of lines that had timestamp changes only. That leaves us with only the following five lines having been added to our ‘edited’ policy after the line “<filter type=HostFrom />”:
<filter type="windowsPerpetrator"> <excludeList> <item type="group" includeSubtree="false" uid="S-1-5-21-3895839511-1128481743-1472478933-515" upn="" samAccountName="">CN=Domain Computers,CN=Users,DC=Win2012r2dom,DC=com</item> </excludeList> </filter>
Here are the steps to effect the same change as above using just the PS Cmdlets. (Don’t forget to undo the change to the policy in the console first if following these steps):
- Use Get-SIPolicy to find the PolicyID for policy named “AD: Group Membership Changes”. In this example the ID is 195 (yours may vary)
- Export-SIPolicy –PolicyIDs “195” >> myPolicy.xml
- This exports the policy xml to file “myPolicy.xml” – note file name does not need to match the policy name
- Not shown – add the five lines from our compare results to the XML file using any means, be it PS or other tools
- Import-SIPolicy –Filename “C:\myPolicy.xml”
Hopefully, this example has demonstrated that one need not become an SI Policy XML master to use the PS Cmdlets. By using the SI Console to ‘model’ you’re desired policy change it will be obvious what needs to be added or removed from the policy XML. Collection XMLs work in s similar way. To export a collection use the export collection button in the “Collection Manager” edit dialog.
If you want to create and add a new Policy rather than replace an existing one be sure the PolicyID and GUID in the XML are unique / do not match any as shown by the Get-SIPolicy returned list. Then use Import-SIPolicy.
Detailed PS Cmdlet descriptions and examples can also be found in the appendix of the SI Console Admin guide (PDF or .CHM from inside console)
Remote PowerShell Connection
These instructions are for users who want to use the PowerShell StealthINTERCEPT Cmdlets from a remote server, where the Enterprise Manager is not located. On the remote server, create a folder with the following set of libraries copied from the SI Enterprise Manger install folder. Then follow steps 1 and 2 at the start of this article and just change the path to the SI.SIMonitor.PowerShell.dll file to that of the copy on your local machine.
Following is a sample script to help copy the needed files per the list above:
#------ Start of PowerShell Script ---------------------------------------------------------------------- <# Please remember this needs to be run on the Enterprise manager where the files are located This script will not clean up the files once copied. This script will not create any folders that do not exist The script does not have error checking #> # Destination where files will be copied to $copyFileDestination = "c:\Downloads\SI-Powershell" # Name of Zip File we will create with all the needed files $archiveNameandDestination = "C:\Downloads\SIPowershell.zip" # Install Directory of the Enterprise Manager $enterpriseManagerInstallDirectory = "C:\Program Files\STEALTHbits\StealthINTERCEPT\SIEnterpriseManager" Copy-Item -Path "$enterpriseManagerInstallDirectory\CertsInfo\root.dat" -Destination $copyFileDestination Copy-Item -Path "$enterpriseManagerInstallDirectory\BouncyCastle.Crypto.dll" -Destination $copyFileDestination Copy-Item -Path "$enterpriseManagerInstallDirectory\Google.Protobuf.dll" -Destination $copyFileDestination Copy-Item -Path "$enterpriseManagerInstallDirectory\Grpc.Common.dll" -Destination $copyFileDestination Copy-Item -Path "$enterpriseManagerInstallDirectory\Grpc.Core.dll" -Destination $copyFileDestination Copy-Item -Path "$enterpriseManagerInstallDirectory\Grpc.Core.Api.dll" -Destination $copyFileDestination Copy-Item -Path "$enterpriseManagerInstallDirectory\Grpc.Messages.Security.dll" -Destination $copyFileDestination Copy-Item -Path "$enterpriseManagerInstallDirectory\grpc_csharp_ext.x64.dll" -Destination $copyFileDestination Copy-Item -Path "$enterpriseManagerInstallDirectory\grpc_csharp_ext.x86.dll" -Destination $copyFileDestination Copy-Item -Path "$enterpriseManagerInstallDirectory\SI.Common.Util.dll" -Destination $copyFileDestination Copy-Item -Path "$enterpriseManagerInstallDirectory\SI.SIMonitor.ConsoleMessages.dll" -Destination $copyFileDestination Copy-Item -Path "$enterpriseManagerInstallDirectory\SI.SIMonitor.PowerShell.dll" -Destination $copyFileDestination Copy-Item -Path "$enterpriseManagerInstallDirectory\System.Memory.dll" -Destination $copyFileDestination Copy-Item -Path "$enterpriseManagerInstallDirectory\System.Runtime.CompilerServices.Unsafe.dll" -Destination $copyFileDestination Get-ChildItem -Path $copyFileDestination | Compress-Archive -DestinationPath $archiveNameandDestination #------------------- End of Powershell Script ----------------------------------------------------------------------
Anthony Sarra is the VP of Research & Development focused on building and delivering real-time activity solutions for Stealthbits technologies including the StealthINTERCEPT and Activity Monitor products. He joined Stealthbits in 2010 as part of the acquisition of NetVision Software.
Anthony has 40 years of experience in software development and management roles creating enterprise software solutions ranging from factory automation to desktop management and server security. Prior to NetVision and Stealthbits Anthony held software developer and leadership roles at Intel Corp. and Intel spin out LANDesk Software.