runposh

Copyright © 2020 by Bill Stewart

Freeware License

This program may be used freely in any environment without payment to the author, with the following conditions:

• Give me credit.
• Let me know how you're using the program.
• The program and this documentation must not be modified.
• The program cannot be used as a part another software package without notifying the author.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Introduction

This program is based on an earlier utility I wrote called ps1exec. I wrote it to address the following challenges of running PowerShell scripts from outside the PowerShell command line:

• Execution policy. If an execution policy is defined, we need to disable it. Execution policy is an administrator safety feature; it is not a security boundary. See Execution Policy for more information.
• Window style. Since PowerShell is itself a console program, we can't control its initial console window state. (The PowerShell -WindowStyle parameter only sets the console window state after it initially appears at its default position.)
• Elevation. There's not a simple and straightforward way to directly run a PowerShell script elevated.

runposh addresses these limitations by doing the following:

• It disables the PowerShell execution policy.
• It can set the window style for the PowerShell console window (for example, hidden).
• It can request elevation for the PowerShell process.

runposh requires at least Windows PowerShell version 2. (Windows PowerShell version 2 is included with Windows 7/Server 2008 R2. Later OS versions include newer Windows PowerShell versions.)

runposh is provided in 64-bit (x64) and 32-bit (x86) versions.

Usage

The program's command-line syntax is as follows:

runposh [options] ["scriptfile" [-- parameters [...]]]

General options:

If you specify a script filename on the command line, the following options apply:

If you are not running a PowerShell script, the following options apply:

IMPORTANT: All command-line options are case-sensitive (e.g., you must specify --startdir, not --StartDir or --STARTDIR).

Elevation Notes

The --elevate parameter requests elevation for the PowerShell process. It is a shortcut for the following manual steps:

1. Right-click the PowerShell icon and choose Run as administrator.
2. Disable the execution policy.
3. (If script filename specified) Run the script.

IMPORTANT: The --elevate parameter only provokes the elevation prompt; it cannot automatically enter credentials or bypass the elevation prompt.

If the current process is already elevated, the --elevate parameter does nothing.

Windows automatically sets the starting directory for an elevated process to the System32 directory (e.g., C:\Windows\System32). This is by design for security reasons. This means that, when you use --elevate, runposh ignores the --startdir parameter. Also, if you run a script, you will need to specify the full path and filename of the script.

Do not use --elevate when scheduling a script for unattended use because there's no one to answer the elevation prompt (i.e., runposh will simply hang indefinitely).

PowerShell Core

runposh supports both Windows PowerShell and PowerShell Core. If you don't specify --core, runposh defaults to Windows PowerShell.

In either case, runposh tries to find PowerShell on your system two ways:

1. by reading the App Paths key in the registry, and
2. by Searching the Path environment variable

Alternatively, you can specify a path and filename to a specific PowerShell Core executable using the --core parameter (see Usage for more information).

Execution Policy

It is important to understand that PowerShell's execution policy is an administrator safety feature; it is not a security boundary. (Think seatbelt, not door lock.)

It is possible to configure the execution policy to prevent scripts from running, and some domain administrators have configured this option because they are under the impression that it increases security.

This impression is not correct, because PowerShell running a script does not enable the user to bypass security. The user's account is the security boundary. When a user runs PowerShell, the PowerShell process runs as that user. Another way to say this: Running a PowerShell script does not somehow give the user more rights than they had previously.

Preventing script execution does not increase security. The PowerShell execution policy is designed to prevent users from accidentally running unsigned scripts; it should not be (ab)used to try to prevent users from running scripts altogether.

Using PowerShell to automate tasks is not going away; preventing scripts from running breaks many administrative functions and prevents many users from doing their jobs.

Accordingly, runposh disables the execution policy for the PowerShell process it starts (see Technical Details).

Examples

The following table lists some sample commands. (The script names are made up.)

Technical Details

runposh builds a command string and uses PowerShell's -EncodedCommand parameter to run it. The command string is built using the components listed in the following table:

The Disable-ExecutionPolicy function contains the following code:

function Disable-ExecutionPolicy {
  ($c = $ExecutionContext.GetType().GetField("_context",
  "nonpublic,instance").GetValue($ExecutionContext)).GetType().GetField("authorizationmanager",
  "nonpublic,instance").SetValue($c,
  (New-Object Management.Automation.AuthorizationManager "Microsoft.PowerShell"))
}

The authorizationmanager name depends on whether you are running Windows PowerShell or PowerShell Core. In Windows PowerShell, the authorization manager is named _authorizationManager; in PowerShell Core, it is named <AuthorizationManager>k__BackingField.

runposh constructs the PowerShell command line as follows:

path [-NoExit] [other parameters] -EncodedCommand encodedcommand

Notes:

• path is the path and filename of the PowerShell executable
• If you don't specify a script file, runposh adds the -NoExit parameter (i.e., open an interactive console)
• The values for other parameters are determined from the command-line parameters provided on the runposh command line
• The argument for the -EncodedCommand parameter is a base64-encoded copy of the string built from the components noted in the table above

Once runposh has constructed the command line, it executes PowerShell using the ShellExecuteEx Windows API function. If elevation was requested (--elevate), runposh uses the runas verb; otherwise, it uses the open verb.

If --wait is used, runposh waits for the PowerShell process to terminate. Once PowerShell terminates, runposh exits with PowerShell's exit code.

Version History

1.1 (2020 Mar 05)

• Improved error message if Windows PowerShell/PowerShell Core not found.
• Fixed a few typographical errors.

1.0 (2020 Feb 24)

• Initial version.