REST API

API is based on JSON format.

Authentication

HTTP request:

PUT api/v1/authenticate

POST api/v1/authenticate

Both commands works same way.

URL query: none

Request body: JSON object with username, password and domain fields

Response Header: X-Security-Token

 

List of detections

HTTP request: GET api/v1/detections

URL query:

Pagination:

o$top—system query option requests the number of items in the queried collection to be included in the result

o$skip—system query option requests the number of items in the queried collection that are to be skipped and not included in the result

o$count—system query option allows clients to request a count of the matching resources included with the resources in the response. if set to $count=1, the number of detections is returned.

Sorting:

o$orderBy—system query option allows clients to request resources in either ascending order using asc or descending order using desc. If not specified the order is in ascending way

Filtering:

o$filter—system query option allows clients to filter a collection of resources that are addressed by a request URL. The query supports the following operators eq, ne, gt, ge, lt, le, and, or, and (). Operators can be combined with values to filter data. For instance, “resolved eq 0” will report only unresolved detections.

Example: GET api/v1/detections?$skip=100&$orderBy=creationTime desc

For other examples follow System Query Options

Request header: Authorization token

Request body: none

Response: JSON object with the following properties:

value — an array of detections:

computerId—unique identifier of a computer in EI database

computerName—shows the name of a computer that raised the detection

computerUuid—unique identifier of a computer in EI database

creationTime—the time of the detection

id—unique identifier of detection in EI database

moduleId—unique identifier of the executable in EI database

moduleLgAge—number of days visible in the LiveGrid®

moduleLgPopularity—how many computers reported an executable to LiveGrid®

moduleLgReputation—LiveGrid® reputation is a number from 1 to 9, indicating how safe the file is. 1-2 Red is malicious, 3-7 Yellow is suspicious, 8-9 Green is safe

moduleName—the executable that triggered the detection

moduleSha1—hash of the executable, that triggered the detection

moduleSignatureType—information whether the file is signed or not and how it is signed. Based on its return value:

o90 = Trusted

o80 = Valid

o75 = AdHoc

o70 = None

o60= Invalid

moduleSigner—if the file is signed, here you can see the signer of the file

priority—the priority of the detection( default 0, otherwise set by EEI Administrator)

processCommandLine—show the argument used with the command

processId—unique identifier of a process in EI database

processUser—the user account that was logged on the computer at the time of detection trigger

resolved—true/false depends if the user marked the detection as resolved

ruleName—the name of the rule that triggered the detection

severity—shows the severity of the detection

severityScore—a more precise definition of severity. 1-39 > Info 40-79 > Warning 80 - 100 > Threat

threatName—the name of the threat, that can be found in this list http://www.virusradar.com/en/threat_encyclopaedia

threatUri—the URI(uniform resource identifier) which caused this detection to trigger

type—ESET type of the detections:

oUnknownAlarm = 0

oRuleActivated = 1—rule based detection

oMalwareFoundOnDisk = 2—malware found on disk by Endpoint

oMalwareFoundInMemory = 3—malware found in memory by Endpoint

oExploitDetected = 4—exploit detected by Endpoint

oFirewallDetection = 5

oBlockedAddress = 7—url blocked by firewall

oCryptoBlockerDetection = 8—cryptoBlocker detection

uuid—unique identifier of a detection

 

List of detections - filtering

$filter parameter allows the user to filter detections using an expression built out of:

Fields: id, resolved, creationTime

Operators: eq, ne, gt, ge, lt, le, and, or, and ()

 

Example:
GET api/v1/detections?$filter=resolved eq false and creationTime ge 2020-01-20T20:11:00Z

 

Get detection details

HTTP request: GET api/v1/detections/{id}

URL query:

$idType—if $idType=sha1 {id} in URL is interpreted as sha1 of a module

Request header: Authorization token

Request body: none

Response: JSON object with detection data:

computerId—unique identifier of a computer in EI database

computerName—shows the name of a computer that raised the detection

computerUuid—unique identifier of a computer in EI database

creationTime—the time of the detection

handled—shows whether an action was taken against this detection

id—unique identifier of detection in EI database

moduleFirstSeenLocally—when an executable was first seen on any computer

moduleId—unique identifier of the executable in EI database

moduleLastExecutedLocally—when was executable executed last time on any computer

moduleLgAge—number of days visible in the LiveGrid®

moduleLgPopularity—how many computers reported an executable to LiveGrid®

moduleLgReputation—LiveGrid® reputation is a number from 1 to 9, indicating how safe the file is. 1-2 Red is malicious, 3-7 Yellow is suspicious, 8-9 Green is safe

moduleName—the executable that triggered the detection

moduleSha1—hash of the executable, that triggered the detection

moduleSignatureType—information whether the file is signed or not and how it is signed (Trusted/Valid/None/Invalid/Unknown)

moduleSigner—if the file is signed, here you can see the signer of the file

priority—the priority of the detection( default 0, otherwise set by EEI Administrator)

processCommandLine—show the argument used with the command

processId—unique identifier of a process in EI database

processPath —path on the disk where the executable is located

processUser—the user account that was logged on the computer at the time of detection trigger

resolved—true/false depends if the user marked the detection as resolved

ruleName—the name of the rule that triggered the detection

severity—shows the severity of the detection

severityScore—a more precise definition of severity. 1-39 > Info 40-79 > Warning 80 - 100 > Threat

threatName—the name of the threat, that can be found in this list http://www.virusradar.com/en/threat_encyclopaedia

threatUri—the URI(uniform resource identifier) which caused this detection to trigger

type—ESET type of the detections:

oUnknownAlarm = 0,

oRuleActivated

oMalwareFoundOnDisk

oMalwareFoundInMemory

oExploitDetected

oFirewallDetection

oBlockedAddress

oCryptoBlockerDetection

uuid—unique identifier of a detection

Update detection

HTTP request: PATCH api/v1/detections/{id}

URL query:

$idType—if $idType=sha1 {id} in URL is interpreted as sha1 of a module

Request header: Authorization token

Request body: JSON object with the following properties:

resolved—when set to true the detection is marked as resolved

priority

 

Remediation

Allows the user to block or unblock an executable and kill running processes

 

HTTP request:

POST api/v1/executables/{id}/block

POST api/v1/executables/{id}/unblock

URL query:

$idType—if $idType=sha1 {id} in URL is interpreted as sha1 of a module

Request header: Authorization token

Request body: JSON object with the following properties:

clean—when set to true, running processes will be killed, and module moved to the quarantine

comment

Example:

example

Example

https://192.168.197.200/api/v1/executables/066F8964A44161825BE6F4E10B05CD66F3C115FC/block?$idType=sha1 which is eq with https://192.168.197.200/api/v1/executables/1605/block (so id = sha1 or ID of module in database)

At the moment, this is all that our API provides. In a future release, ESET plans to expand the possibilities.

 

Example:

example

Example

import json

import requests

import warnings

 

warnings.filterwarnings('ignore')

 

EEI_USER = "Administrator" # Use your credentials here

EEI_PASSWORD = "admin123"

EEI_SERVER = 'localhost'

 

response = requests.put(f"https://{EEI_SERVER}/api/v1/authenticate", json.dumps({"username": EEI_USER, "password": EEI_PASSWORD, "domain":False}), verify=False)

if response.status_code == 200:

   session = requests.Session()

   session.headers={"Authorization": f"Bearer {response.headers['X-Security-Token']}"}

   session.verify=False

 

   UNRESOLVED_FILTER = "resolved eq 0"

   response = session.get(f"https://{EEI_SERVER}/api/v1/detections", params={"$count": 1, "$filter": UNRESOLVED_FILTER})

   count = response.json()["count"]

 

   PAGE_SIZE = 100

   for i in range(0, count, PAGE_SIZE):

       response = session.get(f"https://{EEI_SERVER}/api/v1/detections", params ={"$skip": i, "$top": PAGE_SIZE, "$filter": UNRESOLVED_FILTER})

       detections = response.json()["value"]

       for d in detections:

           print(d)