The new ScriptRunner version 2018R3 brings many new features and improvements for our customers. The development work focussed on password security and user friendliness for the users of the Delegate App. All new features will be presented in detail below.
New Delegate App
As part of the updates to our code frameworks, the Delegate App has been completely reworked and now includes a second view for displaying the actions. In addition to the traditional tile view, there is now also a list view. All information displayed in tile format is also available in the list view. In addition, the time of the last execution and the time of the next time-controlled execution are displayed in the new view. You can switch between the views by clicking on the easily recognizable List/Tile icon next to the search field.
The tabs have also been completely redesigned and users can now select their own tabs themselves. You can use the „+“ button in the menu bar to select and add a tab. The new tab is integrated into the bar and is sorted alphabetically. Tabs that are not or rarely needed can simply be closed by clicking the „x“ button.
The startup behaviour of the Delegate App has also been changed. If no actions are selected as favourites by setting the star symbol, the tab „All“ is used.
All settings are saved user-specifically, so that when the Delegate App is restarted its settings are immediately available again.
Revised forms and new data types
Other new features concern the application of actions and the forms themselves. If more than 7 input fields are defined for an action, you can switch to a view with several input tabs. This improves clarity for the user and eliminates scrolling in long forms.
The automatic generation function for PowerShell data types has been extended by the two types [SecureString] and [DateTime]. [SecureString] hides the input, [DateTime] provides a date picker. Both new data types are also available in the forms of the Admin App.
Beside the data type [SecureString], a hidden input can also be added to other data types. In addition, input fields can now be defined as multi-line inputs. For both scenarios, an additional parameter attribute is used in the parameter declaration in the script.
[Parameter(HelpMessage="ASRDisplay(Password)"] #führt zur verdeckten Eingabe eines Strings
[Parameter(HelpMessage="ASRDisplay(Multiline)"] #führt zur Darstellung einer Multiline-Box
Changes to input fields that have been filled by attribute queries are now highlighted with a colored background. This makes it easier to distinguish changed fields from unchanged fields.
Standardized data entry in fields is often a problem. Different spellings for the same names etc. lead to poor data quality. For this purpose, PowerShell uses validate sets that are displayed in a dropdown of the ScriptRunner Web App. A new feature is that Validate Sets can also be used when attribute queries are used. This functionality can be used, for example, to unify existing different values of AD attributes step by step when changes are made. This allows queries and validate sets for attributes such as department, location, and so on to be combined in an action to change user properties. If the query result corresponds to the value in the validate set, e.g. „Sales“, it is used unchanged; the value has already been selected in the dropdown menu. In contrast, non-compliant query results are not displayed, but the validate set is available for selection.
Repeated execution of an action
Actions can now be repeated with the last parameter values without having to re-enter them. This function is also available in the Admin App. Also, the interactive feedback window has been improved after starting the action. It now contains a progress bar as well as the possibility to execute the action again with the same parameters as the last time.
Delegate App in corporate design
You can now adapt the Delegate App for the users to your company CD. The customization affects three properties:
- Start screen when calling the app, also called splash screen
- Logo in the top left corner of the top bar
- Color of the top bar
The settings are made in the directory of the Web App on the Web server. If the IIS is used with the standard installation, you will find the following under
C:\Program Files (x86)\AppSphere\ScriptRunnerWebApps\DelegateApp\custom
the necessary settings for this. These settings will be kept for future updates.
First you should save two image files in PNG format in the directory:
- Logo file as custom_headerlogo.png with a maximum height of 30px
- Splash screen file as custom_splashscreen.png with a max. width of 530 px
Then edit the file customstyle.css. Remove the end comment character „*/“ behind the background color value. Enter the color value for the background as the name, e.g. green or hex value, e.g. #a1cc1f.
Then start the web server with IISReset. Now you can use the Delegate App in your company’s CD.
New security level for credentials
Administrative access is usually necessary for the execution of PowerShell scripts. ScriptRunner manages the information for these credentials with its execution policies (actions).
Credentials in ScriptRunner
The credentials are stored in the credential store of the Windows operating system on the ScriptRunner host. If the ScriptRunner service is operated by default, the Credential Store of Local System is used, if another account is used, the Credential Store on the local machine is used.
If a script is started, a Windows background process for the PowerShell is started on the ScriptRunner host. Depending on the configuration of the policy, this process accesses the credentials stored there via the operating system mechanisms. Due to this system, the ScriptRunner process itself does NOT have access to the password information at any time. ScriptRunner controls the policies exclusively by references to the credentials stored in the operating system.
This very secure procedure has already been extended in an earlier version of ScriptRunner. First, the visible account name was replaced by a generated GUID. What’s more, an additional encryption of the password information has been implemented to prevent an attacker who has already gained access to the ScriptRunner host from reading the password information of the credentials with a tool like Mimikaz. Since the encryption uses individual machine features, even a memory dump cannot be used to recover password information.
While these measures are extremely safe if certain basic rules are observed, the ScriptRunner Host is also a critical component in the infrastructure because of its functions. For this reason, access and interactive login to the host should only be allowed for a very limited number of people. These accounts have the role of „host administrators“ and could thus gain access to system resources such as the credential store.
An additional level of security
In order to be able to implement an even higher level of security for the credentials, ScriptRunner now supports central password safes and password servers. Password servers are a specific infrastructure component to centrally manage and automatically renew user, application and system passwords network-wide and to make them available to various frontend and backend applications. The password servers manage various safes in which the necessary account information is stored. The access of the respective application can be limited to a specific safe.
Functionality and configuration
If a script is started, a Windows background process for the PowerShell is started on the ScriptRunner host. The background process receives a temporary token. With this token, the process can access the password safe and retrieve the associated credential via a reference ID. Due to this system, there is no account information on the ScriptRunner host anymore, only the reference ID to the credential in the password safe.
In addition to the token mechanism, a reverse proxy mechanism can also be used. CyberArk uses this form to ensure, by means of a reverse request, that only a previously defined and characterized process is allowed to submit a password request, which is only forwarded and answered by the password safe proxy to the password server.
The connection between ScriptRunner and the password server system is established via a connector. The connection is configured via the PowerShell cmdlet
as well as for CyberArk additionally with the cmdlet
It is important to select the correct API for the respective product via the parameter -API ‚product_api_name‚ and to configure the connection information.
A separate license is required to use the Password Server Connector.
Best practice for credentials and password safes with ScriptRunner
In the ScriptRunner Policy Set, define only technical administration accounts for the target systems, e.g. SR-AD-Admin, SR-VMware-Admin, SR-Exchange-Admin. Only grant these accounts the rights they need to run the PowerShell scripts on the target systems, for example for the role of Exchange Mailbox Admin, but not for the role of Organization Admin.
In a password server environment, create a separate safe for ScriptRunner on the password server. Include the technical administration accounts for ScriptRunner in this safe. Then configure the Password Server Connector on the ScriptRunner host as described above.
Now create a new credential in the ScriptRunner Policy Set in the main menu „Credentials“. Select the option „Retrieve Password from Password Server“ and enter the reference ID for the credential in the Password Server. You can display this reference ID in the password server. In the example Pleasant Password Server, the reference ID is for example part of a special URI.
For simple, step-by-step transition, both variants for credential storage can be used in parallel.
Advanced execution options for actions
Actions are the core functionality of ScriptRunner. In this context, guidelines for the execution of the individual scripts are defined and the ScriptRunner Service controls the entire script execution.
In particular, the execution of the scripts can take place in different contexts:
- Local execution on the ScriptRunner host in the system context of the ScriptRunner service (default LocalSystem)
- Local execution on the ScriptRunner host in the context of a specific administrative account
- Remote execution on a remote target system
- Remote execution on an Office 365 client
- Remote execution on an Azure client; there is a new target system type „AzureRM Services“ for this.
- Executing an Action on a Container for Target Systems
Changed and new: local execution modes
For local execution, the modes have been extended and their behavior improved. In addition to the system context, there are now three modes. The configuration is done at the target system settings.
- Thread impersonation mode runs PowerShell scripts with an impersonated thread without the entire process environment running in the context of that user. This is the preferred mode when the PowerShell script does not require user-specific local resources. The process runs in the local system context, the thread personalizes. This mode allows the use of [PSCredential] parameters and enables the ScriptRunner Report Live update.
- Simple RunAs process mode runs PowerShell scripts in a local process as RunAs in the assigned user context. It thus gives the script access to basic resources installed or authorized locally for that user, such as PowerShell modules, environment variables, and user directories.
Note: This mode does not support [PSCredential] parameters or ScriptRunner Report Live update. #
- Local WSMAN process mode leaves process control to the local Windows WSMAN service. It creates a local RunAs process with a complete local user environment. This mode also provides full [PSCredential] parameter support and ScriptRunner Report Live update.
Note: The connection to the local WSMAN service (via PowerShell Loopback Remoting) already counts as the ‚first hop‘, which can complicate further implicit remote accesses in the script (‚2nd hop problem‘).
IMPORTANT for the update to ScriptRunner 2018R3: manually created local target systems with the FQDN ‚.‘ are automatically converted to the simple RunAs process mode. If additional [PSCredential] parameters are used in the script, the target system must be switched to thread impersonation mode.
New: Processing options for container target systems
Containers are a collection of target systems. Containers can be assigned in one action instead of single systems. Previously, when using container target systems, only parallel execution of the PowerShell script was possible on all target systems within containers.
Now there are more possibilities for this:
- Parallel execution on all target systems in the container
- Sequential execution on all target systems of the container, one after the other
- Random selection of a target system from the container with round robin
- Selection of a target system as long as it can be reached, otherwise change to another one
New: Synchronization of script processing
Parallel processing of actions on ScriptRunner can lead to unwanted overlaps in execution. An overlap can potentially occur in two places in ScriptRunner:
- when using the same action
- when using the same script by different actions
This can lead to blockages, unwanted effects, or load situations in the target system, for example, when complex reports arerun twice. One reason for this could be that the runtime of a time-controlled action is longer than its cycle time. In this case, the action would be restarted by the scheduler without the previous action having already been completed.
In this context, the control for time-controlled execution of actions has also been revised. The processing queue now automatically checks whether time-controlled processing is already running or pending, and ignores any new processing requests. The aim is to ensure that the execution times of an action do not override each other and that a later execution cannot overtake a current or pending one. In this case, the new execution time is ignored.
New: Azure Resource Manager target system
Another target system type has been introduced. With the Azure Resource Manager, you can use the variety of PowerShell modules for Azure resources. The connection handling to Azure is done by ScriptRunner, just like with the Office 365 target systems.
To use AzureRM, the Azure-RM PowerShell modules must be installed on the ScriptRunner host.
Find-Module -Name azure* | Sort-Object -Property Name
Please note that AzureRM consists of a whole set of PowerShell modules. The base module for connecting to Azure is Azure.Profile. This must be installed on the ScriptRunner host to use the target system type.
Install-Module -name AzureRM.Profile -Repository PSGallery
Improved query functions
The queries introduced with version 2018R1 have quickly become one of the most popular features among admins and service desk users. In the version 2018R2 this way was continued and also in the new version 2018R3 there are new and some improvements.
The limitation of the result set displayed immediately in the dropdown has been increased from 100 to 500 entries. More queries can now be used in AutoRun mode. If the result set is nevertheless exceeded once, a search field is automatically displayed and the search can be specified more precisely.
The queries on attributes in the Active Directory have been extended. AD Queries can now also process non-string attributes, e.g. integer or true/false attributes as extended attributes. It is now also possible to include attributes that do not exist or are displayed in the Attribute Editor as <not set>. This is the case, for example, if you want to read a list of users for which the value [ad-attribute] has not yet been set.
In addition, the use of LDAP has been improved by appropriate trim functions for blanks and line breaks.
In the lists of static list queries, the entries can now simply be re-sorted. So subsequent entries in the dropdown menu can be positioned appropriately.
New script functions
The ScriptRunner Central Script Repository currently displays four different PowerShell elements:
- PowerShell scripts that are used as the main script in an action
- PowerShell scripts that are used as a script in a query (tag: _QUERY_)
- PowerShell scripts which are embedded as Script Library and whose individual functions can be used in the main script (Tag: _LIB_)
- PowerShell cmdlets from directly mounted modules that can be used directly in place of the main script in an action
PowerShell functions in a library
For many DevOps the more intensive use of PowerShell often raises the question of the reusability of functionality and code. In the simplest and worst case, the corresponding code blocks are copied into other scripts. However, this makes changes, maintenance and overview more difficult.
A much simpler and durable solution is to use Script Libraries in ScriptRunner. These are PowerShell scripts that contain only PowerShell functions. Previously, this solution was limited to one PowerShell function per library script. This limitation has been removed. A library can now contain a variety of reusable functions.
The individual PowerShell functions of the library script can also be used directly in queries (with additional tag: _QUERY_) or instead of a main script in an action.
Best Practice for Script Libraries in ScriptRunner
The first step is to determine which functions are to be used repeatedly. These functions should be clustered thematically. The functions of each theme cluster are then implemented in a library script.
A naming scheme should be defined for the names of the functions. For example, all functions for the Files/Shares subject area with „File-functionname“. During implementation, it is important to ensure that the parameter block is defined within the function. This ensures the local validity of the parameter only within the function. Possible duplications of parameter names with a main script have no effect.
transfer file from source to destination
path and name of source file
path of destination to copy
function File-Delete() ....
Examples of libraries with PowerShell functions can be found in our Action Packs on GitHub.
Use of functions from Script Libraries
The functions from the libraries can be used in different ways:
- as a function call in a main script
- instead of a main script in an action
- as a scripted query
To call functions in a main script at runtime, the function code must be loaded into the PowerShell process of the main script. In ScriptRunner this is done by a setting in the PowerShell options.
Additional and not to be underestimated advantage: the action, including all functions, can also be executed completely remotely, since ScriptRunner ensures that all elements are available on the remote target system at runtime. In contrast, self-written modules must always be installed on the target system.
If a function is to be used directly instead of a main script in an action, the configuration is analogous.
To use the function as Scripted Query, the corresponding function must first be selected in the main menu „Scripts|Cmdlets“ and tagged with _QUERY_. Afterwards a corresponding query can be configured.
The input parameters for the scripted query can either be set as the default value directly in the query, or they can be set using the main script.
In addition to the main features described above, the following features have been implemented:
Live output in the report
If an action is started, a report is created immediately. This report can be viewed immediately in the Admin App. Start the selected action in the main menu „Actions“ and then click the button „Report“ in the action bar. The report opens. The status of the action is „running“ and is represented by a corresponding symbol. At the bottom of the report the running PowerShell output can be followed.
A prerequisite for use is the output of messages for the individual steps in the processing of the script, independent of the result message. Error messages are also output.
Quick access to reports via „Eye of Osiris“
Access to the current reports of a script execution was previously only possible via the Action Bar or the Dashboard. At the same time, status messages were displayed when clicking on „Eye of Osiris“ in the lower right corner.
The functionality has now been extended. After clicking on „Eye of Osiris“, only clickable status messages are displayed. Clicking on a status message opens the corresponding report.
Side-by-side HTTP and HTTPS
ScriptRunner Host can use a second IP port. This makes it possible for the app to access HTTP and HTTPS simultaneously. In addition, scenarios for the use of domain authentication and ADFS can be used in parallel.
Letzte Artikel von Frank Kresse (Alle anzeigen)
- Feature Overview of New Version 2018R3 (English version) - 7. November 2018
- Feature-Überblick zur neuen Version 2018R3 - 26. Oktober 2018
- ScriptRunner im Proof of Concept - 18. April 2018