ESET Connect Connect Owner's manual

Brand: ESET

Model: Connect Connect

Type: Owner's manual

ESET Connect Connect

ESET Connect is an API gateway between a client and a collection of ESET backend services. ESET Connect acts as a reverse proxy to accept all application programming interface (API) calls, aggregate the various services required to fulfill them and return the appropriate result.

Capabilities:

Automates monitoring, security, and administration activities
Provides a security layer for the communication between the client and server
Simplifies programming by showing only the objects and actions of the back end program that the user needs to interact with

Possible use cases:

ESET Connect Connect

Capabilities:

Automates monitoring, security, and administration activities
Provides a security layer for the communication between the client and server
Simplifies programming by showing only the objects and actions of the back end program that the user needs to interact with

Possible use cases:

ESET Connect

User guide

Click here to display the online version of this document

ESET Connect was developed by ESET, spol. s r.o.

For more information visit https://www.eset.com.

in any form or by any means, electronic, mechanical, photocopying, recording, scanning, or otherwise without

permission in writing from the author.

ESET, spol. s r.o. reserves the right to change any of the described application software without prior notice.

Technical Support: https://support.eset.com

REV. 10/10/2023

1 About help 1 .........................................................................................................................................

2 Introduction 1 .......................................................................................................................................

2.1 What is an API 2 ............................................................................................................................

2.2 How the API works 2 ......................................................................................................................

3 Network Prerequisites 4 .......................................................................................................................

4 Release notes 5 ....................................................................................................................................

5 Getting started 5 ..................................................................................................................................

5.1 Create API User account 6 ..............................................................................................................

5.2 Authenticate API user 6 .................................................................................................................

5.3 Authorization 7 .............................................................................................................................

6 Using the API with Swagger UI 7 ..........................................................................................................

6.1 Working with Swagger UI 8 ............................................................................................................

7 Error codes 10 ......................................................................................................................................

8 Pagination 11 .......................................................................................................................................

9 Multitenancy 11 ...................................................................................................................................

10 Rate limits 12 .....................................................................................................................................

11 ESET PROTECT Cloud API 12 ..............................................................................................................

About help

This guide was written to help you get familiar with ESET Connect and provides instructions to use it.

For consistency and to help prevent confusion, the terminology used throughout this guide is based on the ESET

Connect parameter names. We also use a set of symbols to highlight topics of specific interest or significance.

Notes can provide valuable information, such as specific features or a link to a related topic.

This requires your attention and it should not be skipped. Usually, it provides non-critical but significant

information.

Critical information you should treat with increased caution. Warnings are placed specifically to deter you

from committing potentially harmful mistakes. Please read and understand text placed in warning brackets,

as it references highly sensitive system settings or something risky.

Example scenario that describes a user case relevant for the topic where it is included. Examples are used

to explain more complicated topics.

Convention Meaning

Bold type Names of interface items such as boxes and option buttons.

Italic type

Placeholders for information you provide. For example, filename or path means you type the

actual path or a name of file.

Courier New Code samples or commands.

Hyperlink Provides quick and easy access to cross-referenced topics or external web location. Hyperlinks

are highlighted in blue and may be underlined.

%ProgramFiles%

The Windows system directory which stores installed programs of Windows and others.

• Online Help is the primary source of help content. The latest version of Online Help will automatically be

displayed when you have a working internet connection.

• Topics in this guide are divided into several chapters and sub-chapters. You can find relevant information

by using the search field at the top.

• The ESET Knowledgebase contains answers to the most frequently asked questions, as well as

recommended solutions for various issues. Regularly updated by ESET technical specialists, the

Knowledgebase is the most powerful tool for resolving various types of problems.

• The ESET Forum provides ESET users with an easy way to get help and to help others. You can post any

problem or question related to your ESET products

Introduction

Welcome to ESET Connect Documentation.

The ESET Connect is an API gateway between a client and a collection of ESET backend services. ESET Connect acts

as a reverse proxy to accept all application programming interface (API) calls, aggregate the various services

required to fulfill them and return the appropriate result.

ESET APIs and future API integrations built on top of the API Gateway will offer the possibility to automate

monitoring, security, and administration activities.

This documentation will help you understand how to start using the API and API integrations, including

authentification, construction of API endpoint URIs, response status codes, error handling, pagination and rate

limits.

What is an API

What is an API?

API, or Application Programming Interface, is the intermediary software that allows two other programs to

communicate. The data transferred through the API is raw data that needs to be interpreted. You can think of the

API as a messenger that sends out calls and receives responses. The separation of the API from its

implementation allows programs written in one programming language to use a library written in a different

programming language.

Web APIs are interfaces for interactions between a user application on the front end (for example, Swagger UI)

and an application on the back-end (for example, ESET PROTECT Cloud). The back end is a remote server that

receives requests and sends responses. The API is an architectural approach that aims to provide a program

interface for a set of services to different applications that serve different consumer needs.

Security

The API also provides a security layer for the communication between the client and server. It simplifies

programming by showing only the objects and actions of the back end program that the user needs to interact

with.

ESET Connect APIs use unique temporary tokens that are included in each call to prove the user's identity.

Using the API

The API simplifies programming by exposing only the objects or actions the developer needs to interact with.

Implementation of API calls to your local application (for example, Postman or similar program and a custom-

made interface) can help you automate interactions with the ESET Connect APIs.

How the API works

About the API

The API facilitates calls from the client and responses from the server. The API service communicates with the

application. The application also has access to the application's database. This separation helps to secure the

communication process by not exposing the database to requests directly.

API call types

There are several types of API calls: GET, POST, PUT, DELETE. The GET, POST and DELETE calls are available in

ESET Connect APIs.

• GET calls do not consist of any input parameters. The request call cannot be modified; only executed.

• POST call is the call type used most frequently in the ESET Connect APIs.

Each call consists of:

• Call type

• Request URL

• Request header (can consist of the authentication token)

• Request body (contains data, especially with POST calls)

Server response structure

Each API call receives a response from the server. The response consists of the server response code and the

response itself formatted as data in JSON or XML.

The response consists of:

• Server code

• Response body

• Response headers

ESET Connect API uses the following sub-set of error codes:

OAuth Service

Error code Reason Returned message

4xx • empty request data

• null/empty/invalid grant_type

• null/empty client_id

• null/empty client_secret

• invalid credentials

• invalid token

415 Request data is not form content type

500 Unknown internal error (stack trace is present in log message)

503 IDS returns empty response

xxx when IDS returns unsuccessful response (HTTP code is copied from the IDS

response)

Domain services, connectors

Error code Explanation

HTTP 403 All user errors

HTTP 500 All backend-side errors

Status codes used in logs

Error code Explanation

0 (OK)

3 (InvalidArgument) invalid access token

7 (PermissionDenied) API not enabled for token

8 (ResourceExhausted) access token expired

13 (Internal) unspecified error

14 (Unavailable) error from IDS

16 (Unauthenticated) token validation failed

Network Prerequisites

Allow the below network prerequisites in your firewall for your API to work correctly.

Domain Description

eu.business-account.iam.eset.systems Location: Europe

eu.automation.eset.systems Location: Europe

eu.device-management.eset.systems Location: Europe

eu.incident-management.eset.systems Location: Europe

eu.policy-management.eset.systems Location: Europe

eu.installer-management.eset.systems Location: Europe

Domain Description

us.business-account.iam.eset.systems Location: USA

us.automation.eset.systems Location: USA

us.device-management.eset.systems Location: USA

us.incident-management.eset.systems Location: USA

us.policy-management.eset.systems Location: USA

us.installer-management.eset.systems Location: USA

Release notes

ESET Connect 2.0

Release date: October, 2023

• ADDED: Support for the following APIs:

oAuthentication

oApplication Management

oAutomation

oDevice Management

oIncident Management

oOS integration

oPolicy Management

oInstaller Management

Getting started

All APIs are RESTful HTTP endpoints.

All ESET APIs use standard authentication (JSON requests and responses with standard HTTP verbs).

Restriction of use:

ESET APIs are available only to users with valid ESET PROTECT license who are using ESET PROTECT console.

Only user accounts with sufficient access rights are allowed to use APIs.

Prerequisites:

1. Create an API user account

2. Authenticate the API user account

3. Authorization

Create API User account

How to create a user account that is allowed to use API:

1. In your ESET Business Account (or ESET MSP Administrator), create a new user account that you want to

use for API.

2. Under the Access Rights section, enable the slider bar next to Integrations.

3. Click Create to apply the changes.

4. Now, you can use this account for operations with API.

Authenticate API user

Once you Create a dedicated API user account, you need to Authenticate this user account with our Identity

Provider (IDS). This will provide you with time-limited and scope-limited authentication token. The authentication

token follows the JSON Web Token (JWT) standard.

How to obtain JSON Web Token (JWT):

Token expiration:

The JSON Web Token (JWT) is valid for 60 minutes. After this period, the user is required to perform a new

Authentication call to obtain a new token.

Once the Admin account removes the API user account, the rights for API calls this user can still

communicate with the API until his token expiration ends.

1. Authenticate with the API User account credentials using the OAuth API endpoint.

2. The token returned to you is used to authorize all subsequent API calls.

Swagger documentation for OAuth is available here.

It is the user's responsibility to store your API user credentials securely. If your API User credentials are lost

or stolen, an attacker will be able to call APIs on your behalf with your API user credentials and steal your

data or cause other forms of damage.

Authorization

To authorize a user, the user must meet the following criteria:

1. The API User account must have the right permissions to make an API call. The API User account follows the

access rights settings in the ESET Business Account or ESET MSP Administrator.

2. Authorization of the API User is performed by adding an Authorization header containing the JWT token to

an API call.

3. The authorization header must have the following format: Authorization: Bearer <JWT>

Using the API with Swagger UI

What is Swagger?

Swagger is an open-source software framework that helps developers design, build, document, and consume

RESTful Web services. You can interact with the API using the Swagger UI. The Swagger UI allows direct

connections to live APIs through a web page. You can create requests on the web page and explore API calls on

live data.

Swagger UI for ESET Connect APIs

The Swagger UI for ESET Connect APIs is available at Swagger UI for the EU and Swagger UI for the US. Swagger UI

provides complete pre-fabricated API calls. You only need to change the parameter values in the calls.

All Swagger (also all API) calls are executed on your real account with your real data. Do not use it as a

playground.

See the next chapter for more information on how to start learning in Swagger UI.

Working with Swagger UI

1.Navigate to the ESET Connect API Swagger UI page.

2.Click on /oauth/token call.

3.Click Try it out to start editing the call.

4.Fill in the client_id (Username) and client_secret (password).

5.Click Execute to send the call.

Save the authentication token

1.After the call is executed, you will receive a response that contains a token. You will need to use this

token to communicate with the server. Copy the token to the clipboard.

2.Navigate to an API you want to use and click Authorize at the top of the page.

3.Paste the access token string to the Value field and click Authorize.

4.The Swagger UI displays a confirmation of authorization. Click Close to close the window.

Error codes

ESET Connect API uses the following sub-set of error codes:

OAuth Service

Error code Reason Returned message

4xx • empty request data

• null/empty/invalid grant_type

• null/empty client_id

• null/empty client_secret

• invalid credentials

• invalid token

415 Request data is not form content type

500 Unknown internal error (stack trace is present in log message)

503 IDS returns empty response

xxx when IDS returns unsuccessful response (HTTP code is copied from the IDS

response)

Domain services, connectors

Error code Explanation

HTTP 403 All user errors

HTTP 500 All backend-side errors

Status codes used in logs

Error code Explanation

0 (OK)

3 (InvalidArgument) invalid access token

7 (PermissionDenied) API not enabled for token

8 (ResourceExhausted) access token expired

13 (Internal) unspecified error

14 (Unavailable) error from IDS

16 (Unauthenticated) token validation failed

Pagination

Most ESET APIs that return multiple resources wrap them in a "page" object. All APIs support a maximum page

size and a default page size of 100 items, but this limit varies between API endpoints. There are two different

styles of paging by different APIs that affect how pages are requested and the page's metadata in the returned

response.

ESET APIs support paging by offset:

The user requests a specific page of data starting from Page 1.

Multitenancy

ESET Connect APIs fully support the multitenancy model. Multiple tenants of one organization share the same API

infrastructure but operate in isolated environments.

To achieve your requirements for a specific resource or section, the required access rights must be granted to the

user in the ESET Business Account or ESET MSP Administrator. For more granular permissions, see the ESET

PROTECT Cloud console.

Rate limits

All ESET Connect APIs are rate-limited. (How many times you can call an API in a time window.)

If you call an API too often, you will see a response code 429 (Too many requests).

Time window Maximum number of calls

1 second 100 API calls

This rate limit fulfills the Denial of Service (DoS) protection.

The rate limit applies to each set of:

• API credentials

• Account

• Originating IP address

So, you cannot split your API calls between different API credentials from the same account or use the same API

credentials from different IP addresses to work around the rate limit.

ESET PROTECT Cloud API

Using the API with Swagger

Swagger UI provides complete pre-fabricated API calls:

• OAuth

• Automation

• Device Management

• Incident Management

Automation API calls support following client tasks:

• Isolate computer from network

• End computer isolation from network

• On-Demand Scan

• Shut down computer

• Stop managing (Uninstall ESET Management Agent)

• Software Uninstall (Third-party antivirus software)

• Operating system update

• Run command

REST APIs support only manual trigger type, which means starting ASAP. You cannot create tasks with other

trigger types (for example, starting periodically) in REST API. GetDeviceTasks record does not display any

other trigger types other than manual.

You can define task type via task.action.name attribute:

task.action.name task

StartNetworkIsolation Isolate computer from network

EndNetworkIsolation End computer isolation from network

OnDemandScan On-demand scan

ShutdownComputer Shut down computer

StopManaging Stop managing (Uninstall ESET Management Agent)

ThirdPartyAVRemove Software Uninstall (Third-party antivirus software)

SystemUpdate Operating system update

RunCommand Run command

In case of OnDemandScan and ShutdownComputer, you can configure additional task settings via

task.action.params:

{

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

"restart": false,

"actions": {

"cancelAction": false,

"postpone": "OneHour"

}

• restart—if true, computer is restarted, if false computer is shutdown.

• actions—allowed actions for device users, postpone and cancel.

• cancelAction—true if user will be able to cancel the action or false if not.

• postpone—option to postpone action; possible postpone options 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",

}

• cleaningEnabled—true if cleaning is enabled.

• customProfileName—custom profile name for custom scan profile.

• scanProfile—scan profile that will be used during the scan; possible scan profiles are:

InDepth

Smart

ContextMenu

MyProfile

Custom

•

scanTargets—list of scan targets. Empty list or an item equals 'eset://AllTargets', which means the full scan.

• shutdownEnabled—true if shutdown is enabled after scan completion.

• shutdownLocked—true if shutdown is enforced after scan (cannot be canceled).

• powerActions—allowed actions for device users, postpone and cancel; possible postpone options are:

Cannot (Default value)

OneHour

ThreeHours

FiveHours

OneDay

ThreeDays

SevenDays

FifteenDays

TwentyDays

ThirtyDays

You can see the result of OnDemandScan in task_runs[:]result. Example of scan result:

"result": {

"scannedTargets": "",

"scanned": 0,

"infected": 0,

"cleaned": 0,

"severity": "LOG_INFORMATION",

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

}

• scannedTargets—list of scanned targets separated by semicolon.

• scanned—the number of scanned files.

• infected—the number of infected files.

• cleaned—the number of cleaned files.

• severity—severity of scan task.

SystemUpdate parameters:

{

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

"acceptEula": false,

"installOptionalUpdates": false,

"allowReboot": false,

"rebootActions": {

"cancelAction": false,

"postpone": "OneHour"

}

•

acceptEula—true if automatic EULA acceptance is allowed if it is requested by any of the updates (only Windows platform).

• installOptionalUpdates—true if optional updates should be also installed (only Windows platform).

• allowReboot—true if reboot is allowed if it is requested by any of the updates.

• cancelAction—true if user will be able to cancel the reboot action or false if not.

postpone—option to postpone reboot action; possible postpone options are:

Cannot (Default value)

OneHour

ThreeHours

FiveHours

OneDay

ThreeDays

SevenDays

FifteenDays

TwentyDays

ThirtyDays

RunCommand parameters:

{

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

"commandLine": "",

"currentDirectory": ""

}

commandLine—platform dependent command line that will be put into script file and executed.

currentDirectory—working directory for script file.

Task examples

Use the following examples with your own UUIDs and task settings. Device domain calls provide the UUID

of groups and devices.

On-demand scan

# On demand scan

{

"task": {

"description": "OnDemandScanASAP",

"targets": {

"devicesUuids": [

"11111111-2222-3333-4444-555555555555"

"deviceGroupsUuids": [

"11111111-2222-3333-4444-555555555555"

]

"displayName": "ScanAll",

"action": {

"params": {

"cleaningEnabled": True,

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

"scanProfile": "InDepth",

"customProfileName": "",

"scanTargets": [

"eset://AllTargets"

]

"name": "OnDemandScan"

"triggers": [{

"manual": {

"expireTime": "2023-05-31T12:00:00Z"

}

}]

}

Shut down computer

Page is loading ...

ESET Connect Connect Owner's manual

Brand: ESET

Model: Connect Connect

Type: Owner's manual

ESET Connect Connect

Capabilities:

Automates monitoring, security, and administration activities
Provides a security layer for the communication between the client and server
Simplifies programming by showing only the objects and actions of the back end program that the user needs to interact with

Possible use cases:

Download PDF

report

ESET Connect Connect Owner's manual

ESET Connect Connect Owner's manual

Related papers

Other documents