Writing A Custom Platform Script

... that Safeguard understands

---

There are a selection of sample scripts, e.g. Generic Linux that 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, a script that communicates using SSH would support at least CheckSystem, CheckPassword, ChangePassword and DiscoverSshHostKey. The operations that a script can support include:

• CheckSystem – Verify that the service account has privileged access to the remote host. At a minimum, this should verify that the service account can connect to the asset. Typically, it will check that the service account has access to the account password information on the asset.
• CheckPassword – Verify that the given account user and password are valid on the remote host. On platforms where the password hash is available to a provileged account (e.g. from the /etc/shadow file on Unix), then the password can be verified by comparing the encrypted password hash. Otherwise, the password can be verified by authenticating as the account.
• ChangePassword – Change the password for the given user on the remote host.
• DiscoverSshHostKey – Get the SSH host key of the remote host. This requires an SSH connection to the remote host, but does not require user authentication.
• DiscoverAccounts – Get a list of local accounts with associated group information for a given asset.
• DiscoverServices - Get a list of predefined Windows systems (ie. Windows Services, Scheduled Tasks, IIS application pools, COM+ applications) running as user accounts on a given Windows asset.
• DisableAccount – Disable the specified account on an asset
• EnableAccount – Enable the specified account on an asset.
• DemoteAccount – Demote the specified account on an asset
• ElevateAccount – Elevate the specified account on an asset.
• ChangeSshKey – Configure or replace an authorized key for a given account on an asset.
• CheckSshKey – Check if a given SSH key is configured in a user account's authorized key file on an asset. Note that this operation typically verifies the configuration, but does not attempt to authenticate the key.
• DiscoverAuthorizedKeys – Report all the authorized keys configured for a specified account on an asset.
• UpdateDependentSystem - Update the password for all systems running on a asset as a given user account. For Winodws only, this operation can update all the predefined Windows systems (ie Windows services, Scheduled Tasks, IIS application pools, COM+ applications). For a platforms that supports Custom Dependencies, then a custom command can be used to perform any custom updates required.
• RemoveAuthorizedKey - Remove an authorized key for a 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. The following list shows the reserved parameters that can be used to facilitate communication between Safeguard and the custom platform engine. 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.

In addition to these reserved parameters, any number of custom parameters can also be defined for an operation, and managed from Safeguard.

Name	Type	Notes
AccountDn	String	The distinguished name of the account being manipulated.
AccountPassword	Secret	The current password of the account being manipulated.
AccountUserName	String	The account name for the account being manipulated.
Address	String	The address of the remote host. This must be supported for custom platforms.
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.
ChangeComPlus	Boolean	Whether to update Com+ applications on a windows asset as part of the UpdateDependentSystem operation.
ChangeIis	Boolean	Whether to update IIS application pools on a windows asset as part of the UpdateDependentSystem operation.
ChangeService	Boolean	Whether to update windows services on a windows asset as part of the UpdateDependentSystem operation.
ChangeTask	Boolean	Whether to update scheduled tasks on a windows asset as part of the UpdateDependentSystem operation.
CheckHostKey	Boolean	Whether to validate the SSH host key on connection.
DelegationPrefix	String	The delegation prefix to use for privilege elevation, for example, sudo.
DependentPassword	Secret	The new password to set for dependent systems in the UpdateDependentSystem operation.
DependentUsername	String	The account name to target when updating dependent systems in the UpdateDependentSystem operation.
DiscoveryQuery	Object	The filter for the DiscoverAccounts operation to limit the data returned. For more details about the expected format of this object, see WriteDiscoveredAccount
DomainName	String	The domain name of the account being manipulated.
EnablePassword	Secret	The password for the 'enable' privileged user, used on Cisco platforms to elevate privilege. Note: the PrivilegedUser parameter must also be configured, with the default value 'enable'.
FuncAccountDn	String	The distinguished name for the service account.
FuncPassword	Secret	The password for the service account.
FuncUserName	String	The user name for the service account.
FuncUserDomain	String	The domain of the service account. Including this parameter signals to Safeguard to display the Directory Account authentication type in the Asset connection dialog.
FuncUserNetBiosName	String	The Netbios name for the domain of the service account.
HostKey	String	Expected public SSH key of the remote host used. Required for SSH platforms if CheckHostKey is true.
HttpProxyPort	Integer	The port to connect to on the proxy server.
HttpProxyPassword	Secret	The password required for authentication when connecting to the proxy server.
HttpProxyUri	String	The URI of the proxy server.
HttpProxyUserName	String	The username required for authentication when connecting to the proxy server.
NetBiosname	String	Netbios name for the domain of the account being manipulated.
NewPassword	Secret	The new password to be given to the account specified in AccountUserName for the ChangePassword operation.
NewSshKey	String	The public key to be configured in the selected account's authorized key file for the ChangeSshKey operation.
NewSshKeyComment	String	An optional comment to configure for the new authorized key in the ChangeSshKey operation.
NewSshPrivateKey	Secret	The private key, optionally used to test the authorized key configured by the ChangeSshKey operation.
ObjectSid	String	The SID of the account being manipulated, if the account is a domain account.
OldSshKey	String	The SSH key to be removed by the ChangeSshKey or RemoveAuthorizedKey operation, or verified by the CheckSshKey operation, for the user specified in AccountUserName.
Port	Integer	The port to connect to on the remote host.
PrivilegeGroupMembership	Array	The list of group names the AccountUserName will either be elevated into or demoted from. Can be used together or independently with EnableAccount and DisableAccount.
PrivilegedUser	String	The name of the privileged 'account', which is used to elevate privileges, but cannot be used to login directly, e.g. 'enable' on cisco platforms, 'expert' on Checkpoint platforms.
RestartService	Boolean	Whether to restart updated systems after changing the password as part of the UpdateDependentSystem operation.
ServiceDiscoveryQuery	Object	The filters for the DiscoverServices operation that limit the data returned. For more details about the expected structure of this object, see WriteDiscoveredService
SkipServerCertValidation	Boolean	If true, do not validate SSL certificates when using SSL.
TacacsSecret	Secret	The password to use when authenticating using Tacacs (Cisco ISE).
Timeout	Integer	The timeout value used when establishing a connection to the remote host or sending/received data.
UserKey	Secret	The private key to authenticate the service account, if using SSH key authentication instead of password authentication.
UseSsl	Boolean	If true, use SSL when connecting to the remote host.

The script can use variables to gather information from a remote host Variable Reference

The script consists of a number of commands that can be used to communicate with the remote host and manipulate data Commands.

The script can communicate status to the caller (ie Safeguard) by calling the status command Status Command. For operations that may take a long time, e.g. the DiscoverAccounts operation, you may want to report progress at intervals using the status command.

For discovery operations, the script will need to report the data that it has discovered. This can be done with the WriteDiscoveredAccount, WriteResponseData, WriteDiscoveredService and WriteDiscoveredSshKey commands. These commands store data that can then be retrieved by the calling entity (ie. Safeguard).

Lastly, the script will need to indicate whether it succeeded or failed in its execution of the designated operation. The script does this with the return value supplied by the operation. Each operation should return a boolean value; a return of true indicates that the operation succeeded, anything else is deemed a failure. A script may also Throw an exception to stop execution immediately, and report an error for the operation.