custom-platform-script.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://raw.githubusercontent.com/petrsnd/SafeguardCustomPlatform/main/schema/custom-platform-script.schema.json",
  "title": "Safeguard Custom Platform Script",
  "description": "JSON Schema for Safeguard Custom Platform scripts. Provides autocomplete and hover help for editors while remaining permissive enough to allow valid edge-case scripts.",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string",
      "format": "uri",
      "description": "Optional JSON Schema URI for editor support. SPP ignores unknown top-level properties.",
      "default": "https://raw.githubusercontent.com/petrsnd/SafeguardCustomPlatform/main/schema/custom-platform-script.schema.json"
    },
    "Id": {
      "type": "string",
      "description": "Unique platform identifier used by Safeguard."
    },
    "BackEnd": {
      "type": "string",
      "const": "Scriptable",
      "description": "Execution backend. Custom platform scripts always use \"Scriptable\"."
    },
    "Meta": {
      "type": "object",
      "description": "Optional free-form metadata for humans, such as version, notes, prerequisites, or warnings.",
      "additionalProperties": true
    },
    "Imports": {
      "description": "Optional import libraries. Accepts a single string or an array of strings.",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "Import": {
      "description": "Alias for Imports. Accepts a single string or an array of strings.",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "Functions": {
      "$ref": "#/definitions/functionsArray",
      "description": "Optional array of reusable named function definitions."
    },
    "CheckSystem": {
      "$ref": "#/definitions/operationDefinition",
      "description": "Validates connectivity and service account access."
    },
    "CheckPassword": {
      "$ref": "#/definitions/operationDefinition",
      "description": "Verifies the current managed account password."
    },
    "ChangePassword": {
      "$ref": "#/definitions/operationDefinition",
      "description": "Rotates the managed account password."
    },
    "CheckSshKey": {
      "$ref": "#/definitions/operationDefinition",
      "description": "Verifies whether an SSH key is configured."
    },
    "ChangeSshKey": {
      "$ref": "#/definitions/operationDefinition",
      "description": "Adds, updates, or removes SSH keys."
    },
    "CheckApiKey": {
      "$ref": "#/definitions/operationDefinition",
      "description": "Validates an API key."
    },
    "ChangeApiKey": {
      "$ref": "#/definitions/operationDefinition",
      "description": "Rotates an API key."
    },
    "CheckFile": {
      "$ref": "#/definitions/operationDefinition",
      "description": "Validates a file-based credential or artifact."
    },
    "ChangeFile": {
      "$ref": "#/definitions/operationDefinition",
      "description": "Updates a file-based credential or artifact."
    },
    "EnableAccount": {
      "$ref": "#/definitions/operationDefinition",
      "description": "JIT operation that enables an account."
    },
    "DisableAccount": {
      "$ref": "#/definitions/operationDefinition",
      "description": "JIT operation that disables an account."
    },
    "ElevateAccount": {
      "$ref": "#/definitions/operationDefinition",
      "description": "JIT operation that elevates an account."
    },
    "DemoteAccount": {
      "$ref": "#/definitions/operationDefinition",
      "description": "JIT operation that demotes an account."
    },
    "UpdateDependentSystem": {
      "$ref": "#/definitions/operationDefinition",
      "description": "Updates a dependent system after credential rotation."
    },
    "DiscoverAccounts": {
      "$ref": "#/definitions/operationDefinition",
      "description": "Discovery operation that emits discovered accounts."
    },
    "DiscoverServices": {
      "$ref": "#/definitions/operationDefinition",
      "description": "Discovery operation that emits discovered services."
    },
    "DiscoverAssets": {
      "$ref": "#/definitions/operationDefinition",
      "description": "Discovery operation that emits discovered assets."
    },
    "DiscoverApiKeys": {
      "$ref": "#/definitions/operationDefinition",
      "description": "Discovery operation that emits discovered API keys."
    },
    "DiscoverSshHostKey": {
      "$ref": "#/definitions/operationDefinition",
      "description": "Discovers SSH host keys during asset onboarding."
    },
    "DiscoverAuthorizedKeys": {
      "$ref": "#/definitions/operationDefinition",
      "description": "Discovers authorized SSH keys on the target."
    },
    "RemoveAuthorizedKey": {
      "$ref": "#/definitions/operationDefinition",
      "description": "Removes an authorized SSH key from the target."
    },
    "CreateAdminUser": {
      "$ref": "#/definitions/operationDefinition",
      "description": "Creates an administrative user on the target."
    }
  },
  "required": [
    "Id",
    "BackEnd"
  ],
  "additionalProperties": true,
  "definitions": {
    "parameterType": {
      "type": "string",
      "description": "Parameter data type. Matches the DataType enum in the scripting engine.",
      "enum": [
        "Null",
        "Boolean",
        "Integer",
        "Float",
        "String",
        "Array",
        "Object",
        "Secret",
        "Email",
        "null",
        "boolean",
        "integer",
        "float",
        "string",
        "array",
        "object",
        "secret",
        "email"
      ]
    },
    "parameterDefinition": {
      "type": "object",
      "description": "Describes a single parameter including its type, whether it is required, and an optional default value.",
      "properties": {
        "Type": {
          "$ref": "#/definitions/parameterType"
        },
        "Required": {
          "type": "boolean",
          "description": "Whether Safeguard must supply a value before the operation can run. Defaults to true."
        },
        "DefaultValue": {
          "description": "Optional default value used when no explicit value is provided."
        },
        "Description": {
          "type": "string",
          "description": "Optional human-readable description for administrators and editor hovers."
        }
      },
      "required": [
        "Type"
      ],
      "additionalProperties": true
    },
    "parameterObject": {
      "type": "object",
      "description": "A single-key object where the property name is the parameter name and the value describes that parameter.",
      "minProperties": 1,
      "maxProperties": 1,
      "additionalProperties": {
        "$ref": "#/definitions/parameterDefinition"
      }
    },
    "parameterArray": {
      "type": "array",
      "description": "Ordered list of parameter declarations for an operation or function.",
      "items": {
        "$ref": "#/definitions/parameterObject"
      }
    },
    "functionDefinition": {
      "type": "object",
      "description": "A named reusable function definition. Must have a Name and a Do block.",
      "properties": {
        "Name": {
          "type": "string",
          "description": "Function name referenced by Function commands."
        },
        "Parameters": {
          "$ref": "#/definitions/parameterArray"
        },
        "Do": {
          "$ref": "#/definitions/commandArray",
          "description": "Ordered list of commands to execute."
        }
      },
      "required": [
        "Name",
        "Do"
      ],
      "additionalProperties": true
    },
    "functionsArray": {
      "type": "array",
      "description": "Array of named function definitions.",
      "items": {
        "$ref": "#/definitions/functionDefinition"
      }
    },
    "operationDefinition": {
      "type": "object",
      "description": "An operation entry point. Declare Parameters and provide Do with the steps to execute.",
      "properties": {
        "Parameters": {
          "$ref": "#/definitions/parameterArray",
          "description": "Parameters consumed by the operation."
        },
        "Do": {
          "$ref": "#/definitions/commandArray",
          "description": "The command list that the engine executes for this operation."
        }
      },
      "required": [
        "Parameters",
        "Do"
      ],
      "additionalProperties": true
    },
    "knownCommandPayload": {
      "description": "Commands accept various payload shapes depending on the command type. This schema stays permissive at the payload level.",
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "array"
        },
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "integer"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ]
    },
    "knownNestedCommandObject": {
      "type": "object",
      "description": "Single-key command object used by classic Do blocks. The key is the command name.",
      "minProperties": 1,
      "maxProperties": 1,
      "additionalProperties": false,
      "properties": {
        "AwsFunction": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Invoke an AWS Lambda function or AWS API call."
        },
        "BaseAddress": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Set the base URL that relative request paths resolve against."
        },
        "Break": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Exit the current loop or return early from a function."
        },
        "ClearCookie": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Remove a cookie from the current HTTP session state."
        },
        "Comment": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Add an inline note that does not affect runtime behavior."
        },
        "CompareMacOsPasswordHash": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Compare a password against a macOS directory-service hash."
        },
        "ComparePasswordHash": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Compare a password against a salted hash."
        },
        "CompareShadowHash": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Compare a password against a salted /etc/shadow hash entry."
        },
        "CompareUnixPasswordHash": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Compare a password against a general Unix password hash."
        },
        "Condition": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Branch execution using an If expression with Then and optional Else blocks."
        },
        "Connect": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Open an SSH or Telnet session and create a connection object."
        },
        "CryptMd5": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Generate an MD5 crypt hash from input text."
        },
        "Declare": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Declare and initialize a variable (alias for SetItem)."
        },
        "Disconnect": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Close an existing connection object and end the session."
        },
        "DiscoverSshHostKey": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Retrieve SSH host key data for asset trust workflows."
        },
        "Eval": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Evaluate an expression for side effects or object manipulation."
        },
        "ExecuteCommand": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Run a remote command in batch mode and capture stdout, stderr, and exit status."
        },
        "ExecuteDependentCommand": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Invoke a dependency-related command exposed to the script."
        },
        "ExtractFormData": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Parse HTML response content into a reusable form object."
        },
        "ExtractJsonObject": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Parse JSON content into an object the script can inspect."
        },
        "For": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Repeat a block a fixed number of times."
        },
        "ForEach": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Iterate over each item in a collection."
        },
        "Function": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Call a named reusable function."
        },
        "GetCookie": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Read a cookie value from the current HTTP session state."
        },
        "GetFormData": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Read form data from a previously extracted form (alias for GetFormValue)."
        },
        "GetFormValue": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Read a field value from an extracted HTML form object."
        },
        "Headers": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Add or update HTTP headers on a request object."
        },
        "HttpAuth": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Apply HTTP authentication such as Basic, Bearer, or NTLM."
        },
        "Log": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Write a diagnostic message to the task log."
        },
        "NewHttpRequest": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Create a named HTTP request object for later configuration."
        },
        "Receive": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Read terminal output into a buffer variable."
        },
        "Request": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Execute an HTTP request and capture the response object."
        },
        "Return": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Exit the current operation or function and optionally return a value."
        },
        "Send": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Send interactive text or commands to a terminal session."
        },
        "SetCookie": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Create or overwrite a cookie value for later requests."
        },
        "SetFormData": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Set form data on a form object (alias for SetFormValue)."
        },
        "SetFormValue": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Populate a field in a form object before submission."
        },
        "SetItem": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Create or update a variable in script state."
        },
        "SmaAccountName": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Resolve the service account name for the current operation context."
        },
        "Split": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Split text into an array using a delimiter or pattern."
        },
        "SslRequest": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Execute an HTTPS request with explicit SSL/TLS configuration."
        },
        "Status": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Report a progress update or user-facing status message."
        },
        "Switch": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Run one of several blocks based on a match value."
        },
        "Throw": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Raise an error and stop execution unless it is caught."
        },
        "Try": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Run a block with error handling via a Catch block."
        },
        "UrlDecode": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Decode previously encoded URL text."
        },
        "UrlEncode": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Encode text for safe use in URLs or form payloads."
        },
        "VmwareSdkConnect": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Connect to a VMware vSphere environment via SDK."
        },
        "VmwareSdkDiscoverAssets": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Discover assets in a VMware vSphere environment."
        },
        "VmwareSdkDisconnect": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Disconnect from a VMware vSphere environment."
        },
        "Wait": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Pause execution for a defined interval."
        },
        "WriteDiscoveredAccount": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Emit a discovered account result."
        },
        "WriteDiscoveredAsset": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Emit a discovered asset result."
        },
        "WriteDiscoveredService": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Emit a discovered service record."
        },
        "WriteDiscoveredSshKey": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Emit a discovered SSH key record."
        },
        "WriteResponseObject": {
          "$ref": "#/definitions/knownCommandPayload",
          "description": "Write a structured response object back to the platform task engine."
        }
      }
    },
    "genericCommandObject": {
      "type": "object",
      "description": "Fallback for commands not explicitly listed in the schema. The engine resolves commands by name at runtime.",
      "additionalProperties": true
    },
    "command": {
      "description": "A command inside a Do array. Known command names get autocomplete and hover help; the generic fallback permits any valid command shape.",
      "anyOf": [
        {
          "$ref": "#/definitions/knownNestedCommandObject"
        },
        {
          "$ref": "#/definitions/genericCommandObject"
        }
      ]
    },
    "commandArray": {
      "type": "array",
      "description": "Ordered list of commands executed by an operation or function.",
      "items": {
        "$ref": "#/definitions/command"
      }
    }
  }
}