Automation

Copy current article URL Share via email

This article (PDF) Whole documentation (PDF)

The Automation API enables you to manage Device tasks. Use the API to trigger actions on target devices through the installed platform.

The ESET PROTECT Web Console refers to Device tasks as Client tasks.

Use the POST /v1/device_tasks (Create task) endpoint to create a new task. The section below provides request body examples and describes the additional parameters required for specific tasks.

Define the task type using the task.action.name attribute.

The following table provides a complete list of Device tasks supported by the Automation API:

Device task	task.action.name
Isolate computer from network	StartNetworkIsolation
End computer isolation from network	EndNetworkIsolation
On-demand scan	OnDemandScan
Shut down computer	ShutdownComputer
Stop managing (Uninstall ESET Management Agent)	StopManaging
Software Uninstall (Third-party antivirus software)	ThirdPartyAVRemove
Operating system update	SystemUpdate
Run command	RunCommand
Kill process by PID	KillProcessByPid
Log Out	LogOffComputerUser

Use the following examples with your own Universally Unique Identifiers (UUIDs) and task settings. Device Management API provides the UUID of groups and devices.

Isolate computer from network

End computer isolation from network

On-demand scan and Shut down computer tasks

For OnDemandScan and ShutdownComputer, configure additional task settings with task.action.params:

{

"@type": "type.googleapis.com/Era.Common.DataDefinition.Task.OS.ShutdownComputer",

"restart": false,

"actions": {

"cancelAction": false,

"postpone": "OneHour"

}

Parameter	Value
restart	If restart is set to true, the computer will restart; if it is set to false, the computer will shut down.
actions	The parameter that specifies which actions device users are allowed to take, such as postponing or canceling.
cancelAction	If true, the user will be able to cancel the action.
postpone	The parameter that specifies the duration to postpone the action. Available postpone values are: Cannot (Default value) OneHour ThreeHours FiveHours OneDay ThreeDays SevenDays FifteenDays TwentyDays ThirtyDays

OnDemandScan parameters:

{

"@type": "type.googleapis.com/Era.Common.DataDefinition.Task.ESS.OnDemandScan",

"scanProfile": "InDepth",

"customProfileName": "",

"scanTargets": [

"cleaningEnabled": false,

"shutdownEnabled": false,

"shutdownLocked": false,

"powerActions": {

"cancelAction": false

"postpone": "OneHour",

}

Parameter	Value
cleaningEnabled	If true, cleaning is enabled.
customProfileName	A custom profile name for a custom scan profile.
scanProfile	The parameter that specifies the scan profile to use during the scan. Available scanProfile values are: InDepth Smart ContextMenu MyProfile Custom
scanTargets	A list of scan targets. An empty list or an item equals eset://AllTargets which means the full scan.
shutdownEnabled	If true, shutdown is enabled after the scan completion.
shutdownLocked	If true, shutdown is enforced after the scan (cannot be canceled).
powerActions	The parameter that specifies which actions device users can do.
cancelAction	If true, the user will be able to cancel the action.
postpone	The parameter that specifies the duration to postpone the action. Available postpone values are: Cannot (Default value) OneHour ThreeHours FiveHours OneDay ThreeDays SevenDays FifteenDays TwentyDays ThirtyDays

Example result of OnDemandScan in task_runs[:]:

"result": {

"scannedTargets": "",

"scanned": 0,

"infected": 0,

"cleaned": 0,

"severity": "LOG_INFORMATION",

"@type": "type.googleapis.com/Era.Common.DataDefinition.Task.OnDemandScanResult"

}

Parameter	Value
scannedTargets	A list of scanned targets separated by semicolon.
scanned	A number of scanned files.
infected	A number of infected files.
cleaned	A number of cleaned files.
severity	A severity of scan task.

Stop managing (Uninstall ESET Management Agent)

Software Uninstall (Third-party antivirus software)

Operating system update task

SystemUpdate parameters:

{

"@type": "type.googleapis.com/Era.Common.DataDefinition.Task.OS.SystemUpdate",

"acceptEula": false,

"installOptionalUpdates": false,

"allowReboot": false,

"rebootActions": {

"cancelAction": false,

"postpone": "OneHour"

}

Parameter	Value
acceptEula	If set to true, the EULA is accepted automatically if any request for updates is made (only for the Windows platform).
installOptionalUpdates	If set to true, optional updates should be installed (only on the Windows platform).
allowReboot	If set to true, a restart is allowed if an update requests it.
rebootActions	The parameter that specifies which reboot actions device users can do.
cancelAction	If true, the user will be able to cancel the reboot.
postpone	The parameter that specifies the duration to postpone the action. Available postpone values are: Cannot (Default value) OneHour ThreeHours FiveHours OneDay ThreeDays SevenDays FifteenDays TwentyDays ThirtyDays

Run command task

RunCommand parameters:

{

"@type": "type.googleapis.com/Era.Common.DataDefinition.Task.OS.RunCommand",

"commandLine": "",

"currentDirectory": ""

}

Parameter	Value
commandLine	A platform dependent command line that will be put into the script file and executed.
currentDirectory	The working directory for the script file.

Kill process by PID task

KillProcessByPid parameters:

{

"@type": "type.googleapis.com/eset.dotnod.os_integration.v1.KillProcessByPidRequest",

"pid": 0,

"executableHashSha1": "",

"executableHashSha2_256": ""

}

Parameter	Value
pid	An integer value of the local Process ID as seen by the operating system.
executableHashSha1	SHA1 hash of the process executable. At least one executable_hash_sha1 or executable_hash_sha2_256 must be set; otherwise, 400 BAD REQUEST will be thrown.
executableHashSha2_256	SHA2-256 hash of the process executable. At least one executable_hash_sha1 or executable_hash_sha2_256 must be set; otherwise, 400 BAD REQUEST will be thrown.

Log Out task

Browse the methods below or in the Table of Contents.

Method	Path	Summary
	/v1/device_tasks	List tasks
	/v1/device_tasks	Create task
	/v1/device_tasks/{taskUuid}	Get task
	/v1/device_tasks/{taskUuid}	Delete task
	/v1/device_tasks/{taskUuid}/runs	List task runs
	/v1/device_tasks/{taskUuid}:updateTaskTargets	Update task targets
	/v1/device_tasks/{taskUuid}:updateTaskTriggers	Update task triggers

˄˅