Create a Process file

This topic describes how to create a Process file.

The process file includes the following sections:

To create a Process file:

  1. Create a Process file with the following format:

      
    ##########################################################################
###			PROCESS FILE
### 			Version vXX.YYYYMMDD.ZZ
##########################################################################

[states]

[transitions]

[CPM Parameters Validation]

[parameters]

[Debug Information]
  2. Add the required sections, as described in: States, Transitions, CPM parameter validations, Debug information.

States

States are actions that participate in the process.

A state has the following format:

name=action

name

The logical state name used in the transitions section

Alpha-numeric

action

The action to be preformed when reaching the state

Depends on the type of

state

 

 

Use a backslash, ‘\’, before the following special characters in the action: {, }, [, ], \, $.

Spawn

This action type defines the client application that is used to connect to the remote machine and perform the process on that application.

SSH

There are two ways to connect over SSH.

  • Write the action in the following format: 

    (spawn)bin\\plink.exe <parameters>

The following table describes the parameters.

Parameter name

Format

Required

Address

<Address>

Yes

Protocol

-SSH

Yes

Port

-P <Port>

No

SSH Key

-I <SSH Key Parameter>

No

 

 
  • The connection over SSH is not done using Plink. The connection is established using a library that comes with TPC.

  • If you are using an SSH key, and the SSH key uses a passphrase, provide the passphrase in a variable called "passphrase".

  • If you are sending additional prompts in between the username and the password, then:

    • Each prompt can only be used once.

    • All the states between sending the username command to sending the password command may include only one transition, because TPC runs the login process only after it identifies the username and password.

 

 

Example 1:

StartSession=(spawn)bin\\plink.exe <address> -SSH -P <port>

In this example, an SSH connection is established using the address and the port of the target account or platform. The user name and password are set using prompts to complete the connection.

 

 

Example 2:

StartSession=(spawn)bin\\plink.exe <address> -<protocol> -P <port>

In this example, a connection is established using the address and the port of the target account or platform, as in the previous example. The protocol used to connect is also taken from the target account or platform, and can be set to either SSH or Telnet.

 

 

Example 3:

StartSessionWithSSHKeys=(spawn)bin\\plink.exe <address> -i "pmextrapass1"

In this example, a connection is established using an SSH key. This is done using the -i parameter, which receives the name of the parameter that holds the key. In this case pmextrapass1, which includes the key of the logon account.

Use this method if you have issues connecting using Renci.

  1. Enable the ability to use Plink in the process.ini file.

    • In the process.ini file, in the parameters section, add UsePLINK=Yes.

  2. Download the following files to the CPM bin folder:

    • From WinSCP.com, download WinSCP.exe

    • From https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html, download plink.exe

       
      • Make sure to rename the plink.exe file so that it doesn't override an existing plink.exe file used by PMTerminal. The file name should begin with plink, for example, plink074.exe.
      • Do not use the plink.exe file that comes with the CPM.

The following examples use plink074.exe to establish an SSH connection. 

 

Example 1:

StartSession=(spawn)bin\\plink074.exe <address> -<protocol> -P <port>

 

 

Example 2:

StartSessionWithSSHKeys=(spawn)bin\\plink074.exe <address> -i $ssh_Key_parameter

Python

  • To call a Python script, write the action in the following format:

    (spawn)"C:\\Python27\\python.exe" -u bin\\<Script Name> <Parameters>

The following table describes the parameters.

Parameter name

Description
Script Name

The name of the script to spawn.

If the script is located in a sub-folder in the CPM bin folder, specify the relative path to the script.

-u An indication for Python that the outputs should be written to the location from which TPC reads the prompts.
Parameters

A list of parameters and their values to be passed to the script.

Note: Do not pass credentials to the script as parameters. Pass credentials as prompts, when possible. When not possible, for example for SSH Keys, read them directly from the relevant environment variable.

 

 

Example:

StartScript=(spawn)"C:\\Python27\\python.exe" -u bin\\Plugin.py "--address=<address>" "--logonAddress=<extrapass1\address>" "--"--logonusername=<extrapass1\username>"

In this example, the "Plugin.py" script is called. The script receives the following as parameters:

  • Target account address
  • Logon account address
  • Logon account user name

PowerShell

  • To call a PowerShell script, write the action in the following format:

    (spawn)PowerShell.exe bin\\<Script Name> <Parameters>

The following table describes the parameters.

Parameter name

Description
Script Name

The name of the script to spawn.

If the script is located in a sub-folder in the CPM bin folder, specify the relative path to the script.

Parameters

A list of parameters and their values to be passed to the script.

Note: Do not pass credentials to the script as parameters. Pass credentials as prompts, when possible. When not possible, for example for SSH Keys, read them directly from the relevant environment variable.

 

 

Example 1:

StartScript=(spawn)PowerShell.exe bin\\Plugin.ps1 <username> <address> <port>

In this example, the Plugin.ps1 script is called. The script receives the following as parameters:

  • Target account address
  • Logon account address
  • Logon account user name

When writing the PowerShell script, write the input and output prompts as follows:

Input

To receive inputs from TPC, use [Console]::ReadLine() .

 

Example:

Write-Host 'Input the username'
$User = [Console]::ReadLine()

Output

The following output mechanisms work well with TPC.

  • Out-Host
  • Out-String
  • Write-Debug
  • Write-Error
  • Write-Host
  • Write-Output

VB Script

To call a VB script, write the action in the following format.

(spwan)"cscript.exe" “/nologo” “.bin\\<Script Name>” <Parameters>

The following table describes the parameters.

Parameter name

Description
Script Name

The name of the script to spawn.

If the script is located in a sub-folder in the CPM bin folder, specify the relative path to the script.

/nologo

Specifies that the Windows Script Host banner is not displayed before the script runs.
Parameters

A list of parameters and their values to be passed to the script.

Note: Do not pass credentials to the script as parameters. Pass credentials as prompts, when possible. When not possible, for example for SSH Keys, read them directly from the relevant environment variable.

 

 

Example 1:

StartScript=(spawn)"cscript.exe" "/nologo" ".\\bin\\Plugin.vbs" "/Address:<address>" "/logonuser:$logonaddress\\$logonusername"

In this example, the script Plugin.vbs is called. The script receives the following as parameters:

  • Target account address
  • Logon account address
  • Logon account user name

Other executables

Spawn commands can be used to call any executable.

To interact with TPC, the executable should:

  • Utilize the windows stdin, stdout and stderr to be totally unbuffered.
  • Be able to print to the windows console handler.

Invoke

This action type enables the plugin to perform actions on the remote machine using more than one type of API to carry out the process on that application.

This command is parallel to the Spawn command.

Write the action in the following format:

(Invoke) "<DLLPath>" "<Action>"

The following table describes the parameters:

Parameter name

Description
DLLPath

The path to the plugin dll.

Valid values: A valid relative (to the TPC folder) or absolute path.
Action

The CPM action to run.

Valid values: verifypass ,logon, changepass, prereconcilepass, reconcilepass, deletepass, deleteafterreconcile

 

 

Example:

(Invoke) "CyberArk.Extensions.Plugin.WebApp.dll" "verifypass"

In this example, verify password is done using web.

Send to remote

This action type defines the information to send to the remote machine. It is the most common action, so it does not require a keyword.

 

Example 1:

ChangePassNoUserName=passwd

In this example, the passwd command is sent to the target machine. This is the standard command in Linux\Unix when the user changes their own password.

 

 

Example 2:

ChangePass=passwd <username>

In this example, the passwd command is sent to the target machine with the user name of the target account. This is the standard command in Linux\Unix for changing another user's password.

CRLF character

By default, when sending a prompt to the target, TPC adds a CRLF character to the end of each prompt.

TPC uses the Carriage Return character only when running SSH or Telnet. In all other cases, TPC uses the Line Feed character (ASCII 10, \n).

When you don't want TPC to send the CRLF character for a specific prompt, use NoCRLF.

 

Example:

ChangePassNoUserName=(NOCRLF)passwd

In this example, the passwdcommand is sent to the target machine, and \r will not be added to the end of the prompt sent to the target.

Script

This action type defines a valid Tcl script that is evaluated during runtime when the action is performed. Multiple actions can be performed in a single state using the ; (semicolon) separator.

All Tcl commands are supported. For details, see Tcl commands.

Failure scenarios

This action sets the return code and message that are returned to the CPM and the end user.

Fail(<Message>,<Code>)

Parameter name

Description
Message

The message displayed to the end user.

Code

The return code.

The standard codes are between 8000 and 8999.

 

 

Example:

FailTARGETInvalidUsernameOrPassword=FAIL(Invalid username or bad password, 2114)

In this example, a failure state is defined for an invalid user name or an invalid password. The error code is set to 2114, which is the standard code for this scenario.

End state

This state sets the successful return from the plugin. You must name this state “END”.

When reaching this state, the plugin returns a return code 0 (success), to the CPM and the end user.

Transitions

Transitions define the flow of the process. Each transition is made up of three parameters called a triple, which are separated by commas.

  
CurrentState1, Condition, NextState

 

CurrentState The current state.

A name of a state from the list defined in <Link to states>.

A final state or failure state cannot be used in the current state.
Condition

The condition to check.

The condition can be either an expression or a prompt.

As an expression, the condition is true if the expression is true.

As a prompt, the condition is true if the prompt matches the output from the spawned process.

A name of a condition from the list defined in <Link to condition>
NextState The next state.

A name of a state from the list defined in <Link to states>.

Each state that is used as the next state must also be used as the current state in a different transition to avoid broken links.

 

 

Example 1:

Login, Username, SendUsername

In this example, when reaching the state Login, Username, which is a prompt condition of the value username: is checked against the prompt returned from the target. If it matches, the next state will be SendUsername , which is a state that includes the value of the username to be sent to the target.

 

 

Example 2:

SendUsername, Password, SendPassword

SendPassword, StandardPrompt, END

SendPassword, AccessDenied, InvalidLogon

In this example, after sending the username (see example 1), we expect one of the following outputs from the machine:

  • Password. A prompt condition of the value password:. After which we will send the password.
  • StandardPrompt. A prompt condition of the value #. After which we will go the END state, which will return with success to the CPM and the end user.
  • AccessDenied. A prompt condition of the value Access denied. After which we will proceed to the failure state InvalidLogon , which will return an error message to the end user.

Parameters

Add the following parameters to the file.

Name

Description

Default value
PromptTimeout The maximum number of seconds to wait for a prompt from the target before failing.

60

SendHumanMin

The minimum number of milliseconds before each character is sent.

If both the SendHumanMin and SendHumanMax parameters are not set, the characters will be sent all at one time.

If only the SendHumanMin parameter is set, the SendHumanMax parameter will be set to its default value.

0

SendHumanMax

The maximum number of milliseconds before each character is sent.

If both the SendHumanMin and SendHumanMax parameters are not set, the characters will be sent all at one time.

If only the SendHumanMax parameter is set, the SendHumanMin parameter will be set to its default value.

Twice the SendHumanMin value

EnableTPCLogonPrompts

Use this parameter to enable the plugin to continue the process in case the logon action fails.

Possible values are:

  • Yes
  • No (default)

When set to Yes, TPC returns:

Scenario

TPC returns
Logon success Standard prompt
Logon failure

One of the following messages:

  • SocketException - Unable to open connection: A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond.
  • SshAuthenticationException - Access denied: Permission denied (password). OR Access denied: Permission denied (keyboard-interactive).
  • FingerPrintMismatchException - Fingerprint mismatch for '<FingerprintKey>'.
  • InvalidOperationException - Exception error message
  • SshConnectionException - Did not find any matching prompt for Invalid password prompt OR other exception error message
  • roxyException - The client is already connected.

When set to No, TPC returns:

Scenario

TPC returns
Logon success Standard prompt
Logon failure

One of the following exceptions:

  • SocketException 9002
  • SshAuthenticationException 2114
  • FingerPrintMismatchException 9007
  • InvalidOperationException 9001
  • SshConnectionException 9003
  • ProxyException 9004

 

  

States:
LoginUser=<username>
Loginpass=<pmpass>
FAIL=FAIL($output_match(buffer), 8058)
END=
 
Prompts:
InvalidLogin=.*Exception.*
StandardPrompt=.*\$ ?$|.*\# ?$|.*\> ?$|.*\% ?$|.*\] ?$
 
Transitions:
LoginUser, Password, LoginPass
LoginPass, InvalidLogin, FAIL
LoginPass, StandardPrompt, END
 
Parameters:
EnableTPCLogonPrompts=yes

CPM parameter validations

TPC is an infrastructure for many plugins and platforms that require different parameters. To work with these platforms, the plug-in provides a way to define different validation rules for the relevant parameters. For example, a user name is required to change passwords on Solaris machines, while it is not required to change a terminal password in a Cisco router.

In order to protect a platform, the validation rules are defined to prevent the use of special characters in parameters. For platforms that require special characters in a parameter, you can use the AllowCharacters rule to define a list of allowed special characters for a parameter. The AllowCharacters rule can be used with or without the Mandatory rule, and both the Mandatory and AllowCharacters rules are optional.

  
<Parameter>, source=<Source>, Mandatory=<Expression>, AllowCharacters=<List of chars>

 

 

Example 1:

Address, source=FILE, Mandatory=yes

In this example, the parameter “address” which is taken from the target account, is required always.

 

 

Example 2:

VirtualDirPath, source=FILE, Mandatory=no

In this example, the parameter VirtualDirPath, which is taken from the target account, is optional. This is equal to not writing this line but is useful to make the plugin more readable.

 

 

Example 3:

extrapass1\Username, source=FILE, Mandatory=![string equal -nocase "<pmextrapass1>" ""]

In this example, the username of the logon account (extrapass1) is required only if a logon account is attached. This is checked by making sure that the logon account’s password is not empty.

 

 

Example 4:

pmpass, source=ENV, Mandatory=yes

In this example, the password of the target account is always required. Since the password is sensitive, it is taken from source=ENV.

 

 

Example 5:

username, source=FILE, Mandatory=yes, AllowCharacters=;%#

In this example, the username of the target account is always required, and the special characters, ;%#, are allowed in the username parameter.

Debug information

There are two ways to turn on the debug log in TPC:

method

Description

From the platform

In the PVWA, turn on the Debug parameter from the following location:

Target Account Platform > Automatic Password Management > Additional Policy Settings.

From the plugin (Process file)

Add the required parameters to the debug information section of the Process file, and set them as required:

  • DebugLogFullParsingInfo
  • DebugLogFullExecutionInfo
  • DebugLogDetailBuiltInActions
  • ExpectLog
  • ConsoleOutput

Example: ConsoleOutput=no

Tip: Leave the debug flags in the plugins turned off and use the flag in the platform when needed.

See also: Create a Prompts file