API

The API offers another way to access the ESET Threat Intelligence (ETI) portal. To help you begin using the API, we have written a sample API script in python. Download and extract the script, and then open it in a simple text editor for further instructions.

Usage of our API does not necessarily require implementation in a programming language. The API can be used directly in the address bar of a browser as a REST API. In the syntax description below ETI_URL stands for the URL address leading to the ETI portal.

Authentication is ensured via a token generated in the profile section. Each token is valid for only one hour for security reasons. A token can also be generated using a CURL request:

curl -F name="YOUR-USERNAME" -F pass="YOUR-PASSWORD" ETI_URL/auth/

 


note

Authentication limits

If the authentication fails 10 times within 5 minutes due to a wrong password provided, the user trying to authenticate will be blocked for 15 minutes.

If the authentication fails 20 times within 5 minutes from a certain IP address due to wrong username and/or password, any authentication attempt from the particular IP address within 15 minutes will be blocked.

 

To view reports via the REST API, use the following syntax:

ETI_URL/reports/[all|sample|targeted|botnet|phish]/api

Values in brackets ("[" and "]") represent the desired report type. Only use a single report type in your request.

Mandatory POST parameter:

auth - represents the token you generated.

Optional GET parameters:

pid - represents a time period. Its values can be:  24h, 48h, 1w, 2w

oid - represents the owner ID.

gid - represents the group ID.

datetimefrom - represents the beginning of date range the report was updated/generated in (2017-07-18%2009:34:51 or 2017-07-18 09:34:51 or 2017-07-18 ).

datetimeto - represents the end of date range the report was updated/generated in (2017-07-18%2009:34:51 or 2017-07-18 09:34:51 or 2017-07-18 ).

idfrom - represents the report ID.

idto - represents the report ID.

Retrieve XML content, or short details of a certain report:

ETI_URL/reports/REPORT-ID/[xml|detail]/api

Mandatory POST parameter:

auth - represents the token you generated.

Retrieve reports by type:

ETI_URL/reports/[all|sample|targeted|botnet|phish]/api

Retrieve XML or PDF content, additional data or short details of a certain report:

ETI_URL/reports/REPORT-ID/[xml|pdf|adds|detail]/api

REPORT-ID represents the report ID.

The pdf version works only for reports with finished status.

 

To read YARA matches via the REST API, use the following syntax:

ETI_URL/ymatches/all/api

Optional GET parameters:

tid - represents a time period. Values can be:  24h, 48h, 1w, 2w

rid - represents a ruleset ID. It can be retrieved from the xml output of a Rest API call from the <filter name="rid"> ...</filter>  block, where the ID and name of each rule is listed as <info name="123">Test rule</info>, where '123' is the rule ID.

rst - can be used to list matches marked read or unread. Available values are "0" (lists all matches), "1" (lists only matches marked as unread), and "2" (lists only matches marked as read). The values are used without quotation marks.

detail - used to retrieve a certain match by its ID. Match ID can be found in the <info name="yara_match_id"> field of the xml output of a REST API call.

rsst - can be used to list matches based on their status. Available values are "0" (list all matches), "1" (list only new matches) and "2" (list only updated matches).

owner - can be used to list matches by owner.

gread - used to retrieve matches for groups that have only read access to corresponding ruleset.

gwrite - used to retrieve matches for groups that have write access to corresponding ruleset.

datetimefrom - represents the beginning of date range of Last match(2017-07-18%2009:34:51 or 2017-07-18 09:34:51 or 2017-07-18 ).

datetimeto - represents the end of date range of Last match (2017-07-18%2009:34:51 or 2017-07-18 09:34:51 or 2017-07-18 ).

idfrom - represents the match ID.

idto - represents the match ID.

 

Generate a report from a YARA match:

ETI_URL/ymatches/report/MATCH-ID/auth/YOUR-TOKEN

Preview details of a YARA match:

ETI_URL/ymatches/[detail|read|unread]/MATCH-ID/api

Edit note of a YARA match:

ETI_URL/ymatches/detail/MATCH-ID/auth/YOUR-TOKEN?setnote=NOTE

or send the new note as the value of setnote POST parameter.

 

To upload a suspicious sample file, use the following CURL request:

curl -X POST -H "Content-Type: multipart/form-data" -F "sample_file"=@file.txt ETI_URL/reports/add-file/auth/YOUR-TOKEN

where file.txt is the name of the file to be uploaded.

 

To upload a suspicious sample by hash, either use the following REST API syntax:

ETI_URL/reports/add-hash/auth/YOUR-TOKEN?&hash=HASH

or the following CURL request:

curl -X POST -F "hash"="HASH" ETI_URL/reports/add-hash/auth/YOUR-TOKEN

where HASH is the hash (MD5, SHA1 or SHA256) of the sample to be uploaded.