Writing A Custom Platform Script

... for SSH that **Safeguard understands

---

There is a sample Generic Linux script which will be useful in providing an example for context as you read this document.

Scripts will be written with the intent to work with safeguard. To accomplish this, we need to understand a little about how safeguard and the custom platform engine interact. Safeguard communicates with custom platform engine via a predefined set of operations and parameters. A script does not need to support all of the operations. Typically, the script would support at least CheckSystem, CheckPassword, ChangePassword and DiscoverSshHostKey. The operations that a script can support include:

• CheckSystem – Verify that the service account has access to the remote host.
• CheckPassword – Verify that the given account user and password are valid on the remote host.
• ChangePassword – Change the password for the given user on the remote host.
• DiscoverSshHostKey – Get the ssh host key of the remote host.
• DiscoverAccounts – Get a list of accounts with associated information for a given asset.
• DisableAccount – Enable the specified account on an asset.
• EnableAccount – Disable the specified account on an asset.

Within the script, each operation defines what information it expects by defining an array of parameters. The parameter definition includes:

• Name – A string that indicates the name of the parameter.
• Type – The data type of the parameter.
  • Boolean
  • Integer
  • Float
  • String
  • Array
  • Object
  • Secret
  • Email
• Required – Whether this parameter is required (optional, default true.)
• DefaultValue – if this parameter is not supplied use the indicated value. (Only usable for parameters that are not required)

Safeguard invokes these operations with the needed data passed in as parameters. There are currently 36 reserved parameter names to facilitate communication between safeguard and the custom platform engine. Those applicable to Ssh scripts are listed in the table below. These reserved parameters have fixed data types. The data types for these reserved parameters are validated as part script validation during upload. The intent of these fixed parameter names and types is to allow scripts to communicate what data they need in a way that safeguard can understand. Each of these have a specific meaning to safeguard. For example. If a script uses the parameter named FuncUserName as a parameter to an operation, it is saying, give me the user name for the service account on the remote host. The following is a table containing the reserved parameter names applicable to Ssh scripting:

Name	Type	Notes
AccountPassword	Secret	The password of the account being manipulated
AccountUserName	String	The account user for the account being manipulated
Address	String	The address of the remote host
AssetName	String	The name of the asset, or remote host, which holds the account(s). This is largely used in messages to report status or errors.
CheckHostKey	Boolean	Whether to validate the host key
DelegationPrefix	String	The delegation prefix to use for privilege elevation, for example, sudo
DiscoveryRules	Array	The filters for the DiscoverAccounts operation that limit which accounts are returned.
EnablePassword	Secret	The enable password sent to the Pix os
FuncPassword	Secret	The password for the service account
FuncUserName	String	The user name for the service account
HostKey	String	Expected public Ssh key of the remote host used.
NewPassword	Secret	The new password to be given to the account specified in AccountUserName for the ChangePassword operation
Port	Integer	The port of the remote host
Timeout	Integer	The timeout value used when establishing a connection to the remote host
UserKey	Secret	Can be used in place of a FuncPassword. Ssh private key of the user account

The script will need to communicate status and results. For example, let’s take the DiscoverAccounts operation. This could take a while, the script may want to report back progress. This is accomplished by using the status command (see example script). The script will need to supply data on the accounts that it has discovered. This can be done with the WriteDiscoveredAccount command. WriteDiscoveredAccount and WriteResponseObject are commands that store data that can then be retrieved by the calling entity. Lastly, the script will need to indicate whether it succeeded of failed in its execution of the designated operation. The script does this with the return value supplied by the operation. A return of true indicates that the operation succeeded. Anything else is deemed a failure.