The PowerShell Script job step type is used to execute scripts written in the PowerShell scripting language. 

 

This job step type extends basic job step functionality.  For details common to all job step types click here.

 

In addition to the common attributes shared by all job steps this job step type has the following attributes:

 

Connection tab: Specifies how to connect to a PowerShell endpoint

•Use Default Host And Runspace: This option specifies that the PowerShell connection will be made using the default connection context for the security identity under which the step is processing. No other options on this tab are applied when this setting is checked.

•Connection URL: URL used to construct the connection endpoint URI (either local or remote) used to establish the PowerShell environment connection.  If left blank the default runspace connection URL for the current host is used.

•Connection Certificate Options: When the Connection URL uses the HTTPS scheme to connect these options determine how certificates are validated.

•Skip CA Check: When checked the server certificate is not validated to ensure that it is from a trusted certificate authority (CA).

•Skip CN Check:When checked the certificate common name (CN) does not have to match that of the server name in the connection URL.

•Skip Revocation Check: When checked the certificate authority is not contacted to ensure that the certificate has not been revoked since issuance even if it is otherwise valid.

•Shell URL: URL that specifies the default shell that is launched upon connection to the endpoint.  The shell determines the default command-lets that are available to script authors.  Common shell endpoint URL values can be selected from the drop-down list.

•Authentication Mode: Indicates the means by which the client authenticates

•Credentials: A standard username and password combination is provided.

•Authentication Mechanism: The authentication method used to connect to the connection endpoint.  If a Connection URL is not provided use the Default authentication mechanism as some values (such as Kerberos) cannot be used with connections to either localhost, 127.0.0.1, [::1], or blank names.

•Username: (Optional) Windows user name in DOMAIN\USERNAME or USERNAME@DOMAIN format.  If provided the endpoint connection will be made in the provided security context instead of that of the service account when executed automatically or the interactive user when the job is executed manually.

•Password: (Optional) Password for the Windows user name used to connect to the PowerShell service endpoint.

•Certificate: Client authenticates using a certificate from a trusted certificate authority (CA).

•Certificate Thumbprint: The thumbprint of a certificate from the user store of the client process identity is provided.

•Processing Timeout (seconds): The process timeout.  If this timeout period is exceeded the script is automatically terminated and the job step will report failure.

•Load User Profile: Instructs the remote machine to load the caller's user profile for access to custom registry settings and profile application data.

•Enable Network Access: When the connection URL machine name is the current host (i.e. the loopback scenario) the host process is created with the user interactive token allowing PowerShell script code to access network resources (i.e. double-hopping).

•Use UTF-16 Encoding: Script code and variables are provided to PowerShell in UTF-16 format instead of the default UTF-8.

•Proxy Access Type: When the Connection URL uses the HTTPS scheme this option controls this option allows for configuration of a proxy account.

•Proxy Authentication: The authentication method used to resolve proxy addresses when connecting to endpoints.  Negotiate should be sufficient in most cases.

•Proxy Username: Windows user name in DOMAIN\USERNAME or USERNAME@DOMAIN format used to create the HTTPS proxy.

•Proxy Password: Password for the Windows user name used to create the HTTPS proxy.

Variables tab: Allows implementers to pass values into the script and/or store script variables into pasUnity parameters.

•Input Macro: Optional macro expression that if specified causes the variable to be implicitly declared prior to script execution as a string with the value from the macro expression.

•Variable Name: The name of the PowerShell variable.  This should not include spaces and does not need to be prefixed with a $ character.

•Output Parameter Name: The name of a pasUnity parameter that will be created or updated following execution of the script.

Script Code tab:

•Script Options: Specify the behavior of script parsing and execution.

•Apply Macros: Check if you wish to transform pasUnity macros and parsing expressions before the batch is executed.

•Expose $work: When executing a script using the default host and runspace configuration option you can expose the .NET Work object that controls job execution to PowerShell for manipulation.  This should only be used by individuals with a precise understanding of the pasUnity object module and knowledge of how to manipulate in an asynchronous execution environment.

•Fail on Exception: If checked the job step will automatically report failure if any IO is intercepted on standard error.  Check the documentation for the command-lets you are running before checking this box as some write to standard error under normal circumstances.

•Script Code: This contains the body of the script code that will be executed.  Scripts may take advantage of any functionality that the endpoint and shell they are connecting to have implemented.

Advanced tab:

•Redirect Standard Output: When checked allows pasUnity to intercept the shell output of the script to include in verbose audit logs and detailed exception event log entries.  When the job is executed manually pasUnity will display redirected output to the trace pane at the bottom of the user interface.

•Redirect Standard Error: When checked allows pasUnity to intercept the shell exception stream of the script to include in verbose audit logs and detailed exception event log entries.  When the job is executed manually pasUnity will display redirected messages to the trace pane at the bottom of the user interface.

•Pipe Output To Out-String: When checked pasUnity will pipe the contents of the script to the Out-String command-let so that the data returned for auditing in job summaries and to the UI is in text format and not underlying object format.

•Echo Script to Log: Check if you wish to echo the script to the log file.

After making changes be sure to press the Update button to save your changes.

 

Copyright © 2024 pasUNITY, Inc.

 

Send comments on this topic.