startCommandExecutionOnEndpoint

You can use this method to remotely execute a command on an endpoint and upload the resulting output as a log file to the GravityZone centralized storage.

API URL: CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/investigation.

Important

To use this method, your user account, your company, and the endpoint on which you want to execute the command must satisfy all Remote Shell session prerequisites, except for the 2FA requirement.
As an alternative to using this method, you can initiate a Remote Shell session directly from GravityZone Control Center and execute the command during the session. Refer to Remote Shell.

Parameters

Parameter	Description	Included in request	Type	Value requirements
`targetId`	The ID of the endpoint on which you want to execute a command.	Mandatory	String	The string should be the valid ID of an endpoint protected by BEST within your company. It should contain exactly 24 hexadecimal characters.
`command`	The shell command to execute on the endpoint.	Mandatory	String	Maximum length: 10,000 characters.

General parameters

These are common parameters, available across all public API methods:

Parameter	Description	Included in request	Type	Value requirements
`id`	This parameter adds an identifier to the request, linking it to its corresponding response. The target replies with the same value in the response, allowing easy call tracking.	Mandatory	String	No additional requirements. Example "id": "ad12cb61-52b3-4209-a87a-93a8530d91cb"
`method`	The name of the method you are using to send the request.	Mandatory	String	Must be a valid method name. Example "method": "methodName"
`jsonrpc`	The version of JSON-RPC used by the request and the response.	Mandatory	String	The only possible value is `2.0`. Example "jsonrpc": "2.0"
`params`	An object containing the configuration of the request.	Mandatory	Object	No additional requirements. Example "params": {...}

Return value

Attribute	Type	Description
`result`	String	If the action is initiated successfully, the API responds with the ID of the created task. Tip Use this value as the `activityId` parameter in `getInvestigationFileUrl` to retrieve the download URL for the archive containing the command output log once the task has completed. You can also download the log file directly from GravityZone Control Center, either from the User activity section or from the Remote Shell Connection page after the session has ended.

Example

Request:

{
    "jsonrpc": "2.0",
    "method": "startCommandExecutionOnEndpoint",
    "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f",
    "params": {
        "targetId": "559bd17ab1a43d241b7b23c6",
        "command": "ping -n 5 127.0.0.1"
    }
}

Response:

{
    "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f",
    "jsonrpc": "2.0",
    "result": "559bd17ab1a43d241b7b23d7"
}

In this section: