-
Notifications
You must be signed in to change notification settings - Fork 24
The Structure of a Custom Platform Script
A custom platform script is a file that describes how to communicate with a remote system type in order to perform management functions, such as changing a password. Safeguard custom platform scripts are actually JSON models, using objects to describe the actions that form those management functions.
The script object contains:
"Id": "MyPlatformId"
This is a required property, used by Safeguard to identify the platform type managed by the script. Each platform type must have a unique (to your Safeguard appliance or cluster) ID. An ID must only contain alphanumeric characters, and no spaces.
"Backend": "Scriptable"
Safeguard uses various "back ends" to manage platforms using different technologies. Currently, all custom platform scripts are managed by a single back end, named Scriptable. This property is required, and should always have the value "Scriptable".
"Meta": {
"Author": "Rob Fone, One Identity",
"ScriptVersion": "1.0",
"Last Updated": "2019-06-04",
"Description": "Platform script to support my cool in-house web based application"
}
The Meta property was introduced in Safeguard 2.8, and takes an object value. This object may contain any valid JSON name-value pairs, and is intended to carry any metadata you wish to include in the script.
Safeguard currently supports a number of operation types. Each type is optional in your script, but we recommend that you include CheckSystem in addition to the specific operation types you wish to support. The operation types are detailed below.
| Operation Type Name | Description |
|---|---|
| CheckSystem | Verify that we can connect to the remote system, and optionally perform any checks required to verify that we will be able to perform management operations on that system. For example, check the permissions of the functional account in use. |
| CheckPassword | Check that the password provided for the named account is valid. This operation should result in one of three outcomes: The operation succeeded and the password is correct; or the operation succeeded and the password is incorrect; or the operation failed so we could not establish whether the password is correct. |
| ChangePassword | Change the password for the given account. |
| DiscoverSshHostKey | If the script relies on SSH to communicate with the remote system, Safeguard will use this operation to obtain and verify the host key of the remote system when connecting for the first time. When using SSH, Safeguard requires that you provide this operation. |
| ChangeSshKey | This operation is used to add or replace a user's authorized key when that user is using SSH key authentication |
| RemoveAuthorizedKey | This operation is used to remove a user's authorized key when that user is using SSH key authentication |
| DiscoverAuthorizedKeys | User to discover all the authorized keys configured for a user account |
| EnableAccount | Used to enable a user account |
| DisableAccount | Used to disable a user account |
| ElevateAccount | Used to elevate a user account |
| DemoteAccount | Used to demote a user account |
| CheckSshKey | Used to check whether an authorized key is configured for a user account |
| DiscoverAccounts | Used to discover all user accounts on a remote host |
| DiscoverServices | Used to discover all systems (of predefined types) running as user accounts on a windows system |
| UpdateDependentSystem | Used to update the password for all systems running on a windows host as a selected user account |
Safeguard will automatically determine the operations supported by your script, determined by their presence in your script. Every operation type you include has the same format in the script:
"OperationType": {
"Parameters": [ < list of operation parameter objects > ],
"Do": [ < list of command objects > ]
}
For example, a simple CheckSystem operation that uses SSH with a functional account and password to connect with the target system might look like:
"CheckSystem": {
"Parameters":
[
{
"FuncUserName":
{
"Type": "string",
"Required": true
}
},
{
"FuncPassword":
{
"Type": "secret",
"Required": true
}
},
{
"Address":
{
"Type": "string",
"Required": true
}
},
{
"HostKey":
{
"Type": "string",
"Required": true
}
}
],
"Do": [
]
}
Parameters and Do arrays are explained in more detail below.
In addition to the operation handlers above, you may define your own re-usable sections of scripts, or Functions. Operation handlers are just special-case functions with names known to Safeguard to provide well known entry points to your script. Aside from that, functions and operation handlers are the same.
"MyLoginFunction":
{
"Parameters":
[
{
"UserName":
{
"Type": "string"
},
"Password":
{
"Type": "string"
}
}
],
"Do": [ ]
}
Functions are invoked using the Function command.
Operation handlers and functions are passed values, either from another call within the script, or from Safeguard when entering the script. The operation handler or function declares the parameters it supports in the parameters array. Each parameter object must define a value type, which may be one of the following:
| Data Type Name | Meaning |
|---|---|
| Boolean | A boolean value, true or false |
| Integer | Any valid integer value |
| Float | A floating-point value |
| String | A string of characters |
| Array | An array of values |
| Object | A complex object |
| Secret | A string data type that will contain sensitive data. This prevents Safeguard from entering the data in logs, or returning the information via a public API. Use this when passing a password, or private key, for example. |
A parameter object may optionally include:
| Property | Description |
|---|---|
| Description | Text describing the purpose of the parameter |
| DefaultValue | The value the parameter will be assigned if no value is passed to it |
| Required | If true, the parameter must be passed or the script execution will fail. Defaults to false. |
The arrays named "Do" in functions and operation handlers are used to describe the actual work performed. The array contains command objects, in the order that they should be executed. Every command object has the following structure:
{
"CommandName": {
< command specific properties >
}
}
A complete list of the available commands, and their properties, can be found in the Command Reference.
A description of how variables are defined and accessed can be found in the Variable Reference