Home ISESteroids Documentation Security and Protection
 

Security and Protection

ISESteroids ships with advanced and easy-to-use security and protection features. They are unobtrusive and show in the editor status bar:

Risk Assessment

  1. Rapid Risk Assessment: A “traffic light” icon indicates the potential risk level: green (no apparent risk), yellow (moderate risk), or red (high risk). Click the icon for a risk assessment
  2. Digital Signature Support: A signature icon indicates whether the file is digitally signed, and whether the signature is valid or whether the script was manipulated

The sample code above displays a red icon, indicating that part of the code needs review. See the next section to learn how ISESteroids helps you review the critical parts.

Rapid Risk Assessment

It is common practice in many organizations to search for code on the Internet, and adjust it. Often, this code is not thoroughly analyzed for risks because it seems too much effort to fully review the code. ISESteroids has a built-in risk assessment helping you to quickly identify portions of code that needs review.

If the risk assessment shows a yellow or red color, click the icon and choose “Analyze Risks”. ISESteroids walks you through all the parts of a script that are considered a potential risk.

Risk Analysis

For each case, you can quickly decide what to do:

  • Dismiss: you identified the code as benign in this context
  • Whitelist: you identified the code as generally benign, even in other scripts and contexts. ISESteroids will not issue a warning for this risk anymore

Once you have dismissed or whitelisted all risks, you can choose to approve or digitally sign the script. Approvals are stored in an NTFS stream in the script file and are valid only locally, whereas a digital signature is persistently stored inside the script.

Teaching the Risk Assessment Relevant Risks

Initially, the risk assessment is very strict and will produce a lot of “false alarms”:

  • Any cmdlet with a verb like Stop, Remove, New, and other verbs that indicate system change are flagged “red”.
  • Critical cmdlets like Invoke-Expression or Set-Alias are marked “red” because they, too, can change the system
  • [ScriptBlock]::Create() and Add-Type are also marked “red” because they can introduce malicious code
  • Any cmdlet with a verb like Clear, Enable, Disable, Set, Start, and Suspend are marked “yellow” because they perform medium risk system change
  • Any .NET method that is not whitelisted is marked “red”

When you review risks, you can teach ISESteroids which risks are relevant to you, and place commands or .NET methods on your whitelist.

White Lists and Black Lists

To manage your white- and black lists, click the risk icon in the status bar, and choose “Manage White/Black-Lists…”. This opens a dialog with your risk levels.

Open White List

The dialog shows four tabs:

  • No Risk: this is your whitelist. Commands on this list will not be flagged
  • Medium Risk: when detected, will show yellow icon
  • High Risk: this is your blacklist. Commands on this list show red icon
  • Trusted Certificates: when you decide to trust a digital signature, the certificate thumbprint is placed on this list. This way, you can trust certificates that are not necessarily trusted by Windows, and maintain your own private trust.

Whitelist

When you right-click a list, a context menu opens and offers to export the list to Microsoft Excel, or restore the factory defaults.

Each entry in the lists is comma separated:

[Expression],[MatchType],[Description]

Valid match types are:

  • Static: must appear as stated, no wildcards allowed, case-insensitive
  • Like: supports wildcards like “*”, match uses the -like operator, case-insensitive

Digital Signature Support

Scripts are text-based and can easily be tampered with. Digital Signatures identify tampered scripts and the original script author.

It is very simple to protect your script with a digital signature. Just identify the signature icon in the status bar. It shows the current state:

  • Unsigned Script. No digital signature present
  • Valid Signature
  • Damaged Signature
  • Damaged Signature, but you are the signer

Signature Icon

To add a new digital signature, click the icon. A context menu opens with various options. Choose “Add Signature”. If you do not yet own a code signing certificate, ISESteroids offers to create a self-signed certificate for you. ISESteroids then lists all available certificates so you can pick one to sign the script file.

On Windows 10 and better, the dialog shows one certificate at first. Click “More Choices” to see all available code signing certificates.

Select Certificate

Once you select a certificate and click OK, a signature block is added at the end of your script.

Signed Script

The signature icon in the status bar shows a valid digital signature.

Manage Signature

When you click the signature, a “wrench” icon appears in the left editor bar. Click it to see signature options:

Manage Signature

Creating New Code Signing Certificate

One of the main obstacles for many script authors was that they do not own code signing certificates (digital identities). ISESteroids offers to create self-signed certificates whenever you try and sign a script but have no code signing certificate. You can create as many additional certificates as you need by clicking the signature icon, choosing Advanced Options/Create Self-Signed Test Certificate.

Create Certificate

  • Trust Certificate: the certificate is copied to the Root Certificate and Trusted Publishers certificate store. The certificate is now trusted by Windows on this machine. To “untrust” the certificate, once you have signed a script using this certificate, click the signature icon in the status bar, and uncheck “Trust certificate”. This will remove the certificate from Root Certificate and Trusted Publishers. It does not remove the code signing certificate from your store.
  • Create Exportable Certificate: Marks the certificate as exportable, so you can export it to a pfx file to transfer it to another computer when you open your personal certificate store.

Signature Updates and Adornments

When you start editing a signed script, the signature no longer matches your script content. ISESteroids changes the appearance of the signature, and the signature icon in the status bar. When you hover over the signature, a tooltip explains what is wrong.

Invalid Signature

  • Ghosted Signature: if you own the private key to the signature, but the signature no longer matches your script content, the signature displays ghosted. ISESteroids updates the signature as soon as you save your script.
  • Strike-Through Signature: if you do not own the private key (signature was done by someone else), and the signature no longer matches the script, it appears “striked through” because you cannot update it. When you save your script, ISESteroids asks whether you want to remove the invalid signature or replace it with your own signature.

Importing PFX-Files

If you’d like to sign a script with a certificate that is not installed on your computer but available as PFX-file, click the signature icon in the status bar, and choose Advanced Options / Load Certificate from PFX-File:

Load Pfx

If the PFX file contains multiple certificates, all suitable code signing certificates are shown so you can select which one to import. The imported certificate is then available for code signing in all dialogs for as long as ISESteroids runs.

Using Timestamps in Signatures

When you sign a script file, the signature is valid as long as the script content matches the signature and the signer certificate is not expired. Expiration can be a problem when employees leave the company, and may become a problem years from now. This is why you can specify an official timestamp server. The timestamp server proves that the certificate was valid at the time when the signature was added, so the signature stays valid even if the signer certificate expires sometime in the future.

To add a timestamp server, click the signature icon in the status bar just like in the previous example, and choose Advanced Options / Use Timestamp Server for Signing. This opens a list with some predefined timestamp servers, plus an empty field where you can add additional timestamp servers.

Trusting and Untrusting Certificates

Anyone can create a code signing certificate, even a hacker. This is why ISESteroids reports a “valid” signature only if the signer certificate is trusted. There are two modes of trust:

  • Windows Trust: the certificate is located in the Root Certificate Authorities store, or was issued by a root certificate in this store
  • ISESteroids Trust: the certificate thumbprint is on the certificate whitelist

To control trust, click the signature icon in the status bar. If the current script is signed, check or uncheck “Trust This Certificate”. When you check it, the certificate is placed on ISESteroids private trust list. When you uncheck it, the certificate is removed from the private trust list plus if it is a self-signed certificate that was copied to the root certificate store, it is removed from this store.

Private Trust

ISESteroids’ private trust enables you to independently trust certificates and safely use self-signed certificates. If for example you receive a signed script from a colleague or friend, you can decide to trust his signature. Thanks to ISESteroids private trust, this is completely independent of Windows settings and requires no Administrator privileges. Next time you again receive a signed script from that person, ISESteroids shows a valid signature (or detects and warns that the script was signed by your friend but changed afterwards).

Obfuscation

While sharing code and ideas is wonderful in most scenarios, there are use cases where intellectual property must be protected.

ISESteroids comes with a simple yet very powerful obfuscation engine. It extracts information and makes the code and structures very hard to read. To obfuscate a script, choose Tools / Obfuscate Code. A dialog opens and controls the level of obfuscation:

Obfuscation Dialog

Carefully review the options. The combo box Mode sets the type of obfuscation. The remaining checkboxes control what gets obfuscated. Once you click OK, the current script is obfuscated and opened in a new editor tab.

Obfuscated Script

Obfuscation will never change your existing script. It always produces a new one. Always make sure that you save your original script at a secure location. If you obfuscate your script and delete the original script, you will not be able to restore your original script because obfuscation not only makes code hard to read. It also removes information such as comments and meaningful variable names.

If you checked Create Obfuscation Table, then ISESteroids creates a second script with a hashtable, listing the name changes performed. You can save this file and use it to better understand bug reports and other feedback returned by customers that use obfuscated scripts. You can also use this to restore an obfuscated script to some extend in case the original script was lost.

Obfuscation Table

Hide

Keeping Public Functions and Parameters Unobfuscated

When obfuscating a script that defines public functions (functions that others will later call), do not obfuscate these functions and their parameters.

If you uncheck “Obfuscate Functions” and “Obfuscate Parameters”, then all functions and parameters are left intact. This is not the best approach. Instead, simply make functions global by prepending the keyword “global:” to a function name. ISESteroids will never obfuscate global function names and their parameters.

After obfuscation is done, you can safely remove the “global:” prefix again.

EXE Generator

ISESteroids 2.6.2.30 or better

Make sure you are running ISESteroids 2.6.2.30 or better. The EXE Generator was completely rewritten. Older versions lack some of the described features.

Launching scripts is not for everyone. Whenever you plan to hand a script to someone not familiar with PowerShell, the EXE Creator that ships with ISESteroids can turn your script into an application file.

To create an application, simply compose a script, thoroughly test it, and make sure it runs when you execute the script. So if you define a function, make sure your script acutally calls that function.

When you are ready, choose Tools / Turn Code into EXE.

Create EXE

A dialog opens where you can choose an application icon and set various other options:

PowerShell Executable

Once you made your choice, click OK and pick a name and location to save the executable. After the executable is generated, ISESteroids opens Windows Explorer and selects the file so you can immediately test drive it.

Save Application

Testing Executable

When you double-click the generated executable, your script is launched. Note that your application will not temporarily save your script to some file. It uses a solution that works in pure memory.

It behaves just like before, so if you defined mandatory parameters, PowerShell will ask for them.

Testing EXE

You can also run the application interactively. Open a cmd.exe or powershell.exe, then run your application. You can submit parameters to it just like to your original script:

Submitting Parameters

Comment Based Help

Help is supported. Just add comment based help to your script code. For example, turn below code into an application.


<#
.SYNOPSIS
Takes two numbers and multiplies them

.PARAMETER Number1
First number. Mandatory.

.PARAMETER Number2
Second number. Defaults to 10.

.EXAMPLE
testapp.exe -Number1 10 -Number2 20
Result is 200

.EXAMPLE
testapp.exe -Number1 10
Result is 100

.EXAMPLE
testapp.exe 400 9.6
Result is 3840
#>


param
(
   [Double]
   [Parameter(Mandatory)]
   $Number1,

   [Double]
   $Number2 = 10
)

$result = $Number1 * $Number2
"The result is $result"

When you run the application and submit -? as parameter, comment based help is shown:

Comment Based Help

Supported Variables

You can use the special variables $PSScriptRoot, $PSCommandPath, and $MyInvocation in your script. ISESteroids automatically maps these locations to the EXE file location. In addition, $LASTEXITCODE is passed on to the caller of the excutable and shows as error level.

Here is a sample script:


"Location: $PSScriptRoot"
"Path: $PSCommandPath"

$MyInvocation

ping doesnotexist -n 1 -w 500

"Last Error Level: $LASTEXITCODE"

When you convert it to an application, the result would look like this:

Windows PowerShell
Copyright (C) 2016 Microsoft Corporation. All rights reserved.

PS C:\Users\tobwe> C:\Users\tobwe\Desktop\MyExecutables\testapp.exe
Location: C:\Users\tobwe\Desktop\MyExecutables
Path: C:\Users\tobwe\Desktop\MyExecutables\testapp.exe


MyCommand             : testapp.exe
BoundParameters       : {}
UnboundArguments      : {}
ScriptLineNumber      : 11
OffsetInLine          : 1
HistoryId             : 1
ScriptName            : C:\Users\tobwe\Desktop\MyExecutables\testapp.exe
Line                  : testapp.exe
PositionMessage       : At C:\Users\tobwe\Desktop\MyExecutables\testapp.exe:11 char:1
                        + testapp.exe
                        + ~~~~~~~~~~~
PSScriptRoot          : C:\Users\tobwe\Desktop\MyExecutables
PSCommandPath         : C:\Users\tobwe\Desktop\MyExecutables\testapp.exe
InvocationName        : testapp.exe
PipelineLength        : 1
PipelinePosition      : 1
ExpectingInput        : False
CommandOrigin         : Internal
DisplayScriptPosition :

Ping request could not find host DOESNOTEXIST. Please check the name and try again.
Last Error Level: 1
Press any key...
PS C:\Users\tobwe> $LASTEXITCODE
1
PS C:\Users\tobwe>

Restrictions

Code that you convert to application cannot run other console applications which require interactive input. Essentially, what you can run inside the ISE editor also runs in your application. The same restrictions apply.

So you can run nslookup.exe microsoft.com, but you cannot run nslookup.exe and wait to be prompted later.

These restrictions only apply to other executables you run from your script. It is perfectly fine to use cmdlets like Read-Host, or to use .NET methods like [Console]::ReadLine().

Never Keep Secrets in Scripts

Secrets like passwords or other sensitive data never belong in a script, and converting a script to an application can only make it harder for evil people to get to your secrets, but never prevent it. The reason is simple: an application is a stand-alone file, so even if the content is obfuscated and encrypted, the secret to decryption must reside in the same file. After all, when a user launches the application, it needs to get to the unencrypted script code to execute it.

Applications are a convenient delivery vehicle for scripts, and they can be used to protect intellectual property to some degree, but they never ever add significant protection for sensitive data.