PowerShell script reference for Adaptable SSH Key Discovery

Similar to other Venafi Adaptable solutions, Adaptable SSH Key Discovery utilizes a PowerShell script that contains functions you can use to get information from the devices you are connected to and to take action on those devices.

TIP  When creating new PowerShell scripts for use with Adaptable SSH Key Discovery, keep in mind that the file name is used to identify your script from within the associated object in SSH Protect. Using logical names can help you and other administrators recognize the purpose and intent of each script.

This section documents all available PowerShell functions for use with the Adaptable SSH Key Discovery driver. PowerShell scripts are stored in the \Venafi\Scripts\AdaptableSSHManagement folder.

The input parameters and response format for each function is predefined. All functions receive a set of general parameters, whereas those parameters that are specific to the function are only passed to it.

DID YOU KNOW?  To prevent vulnerabilities, the PowerShell scripts are stored on the Trust Protection Platform server. While it might have been more convenient to allow downloading the script, storing the scripts on the Trust Protection Platform server prevents potentially harmful scripts from affecting the server. Only privileged users on your Trust Protection Platform server can access scripts.

You must ensure the same version of all your Adaptable SSH Key Discovery scripts are on all servers in the cluster that have the WebConsole component installed. For this reason, it is wise to include a script version number in the file name, so you can easily check to see that the same version of the script is installed on all servers in the cluster.

NOTE  To work effectively with any Venafi adaptable solution, you must have some working knowledge of PowerShell scripting, or you must have equivalent experience with a scripting language similar to PowerShell.

A sample script is provided in the \Venafi\Scripts\AdaptableSSHManagement\Samples folder. Only files that are in the main \Venafi\Scripts\AdaptableSSHManagement\ folder can be selected in an Adaptable SSH Key Discovery object in Policy Tree. Files in all sub-folders are ignored.

BEST PRACTICE  When customizing (or creating a new) PowerShell script, keep the following security best practices in mind:

  • Avoid hard-coding credentials into your PowerShell scripts.
  • Only include code in functions that relate to the task they are designated to perform.
  • Scripts should not do anything that could alter the integrity or availability of the local Windows system (the system hosting Trust Protection Platform).

Data is passed to (and returned by) each function using hash table data structures.

A general hash table, which includes a common set of data, is passed to all of the functions. A specific hash table, which includes data that is applicable specifically to the function, is passed to functions that require additional data. All functions must return a single hash table that includes a result along with any other variables that the function is required to return.

Consider the following guidelines and expected behaviors:

  • Thrown exceptions are handled as unexpected. If there is an error, we recommended you use Result="Failure" and pass the error description in the Error="" parameter.
  • All functions (except where noted) must be present in the script, but they are optional from a logic standpoint.
  • In the function references that follow, the following two functions are listed as not being required: GetConfigPath, and CleanUP. This means they are optional to implement. However, they should still be present in the script, and should return Result="Success" even with empty result data.

Supported features

Adaptable SSH Key Discovery supported features with PowerShell scripts include the following:

  • Administrators can specify which device custom fields are passed when PowerShell functions are invoked. The custom fields can be specified on policy or device.

  • Custom fields. Custom fields defined in the PowerShell script can be configured by administrators listed in the policy or device. The fields are passed using the $GeneralCustomFields parameter.

  • Macros. The values of custom fields are evaluated for macros.

  • Signed scripts. Adaptable SSH discovery supports signed PowerShell scripts. This allows the PowerShell developer who has rights to sign the script to bypass the need for an approver to approve the script after it has been changed.

  • Client details. From a PowerShell script, you can specify and return all information about a client device.

Functions

The individual functions for Adaptable SSH Key Discovery are documented in the following sections.