Kaspersky Online File Reputation Service

Kaspersky Online File

Reputation Service

Implementation Guide

Dear User,

Thank you for choosing Kaspersky as your security software provider. We hope that this document will help you to

use our product.

Attention! This document is the property of AO Kaspersky Lab (herein also referred to as Kaspersky): all rights to this

document are reserved by the copyright laws of the Russian Federation and by international treaties. Illegal

reproduction and distribution of this document or parts hereof incur civil, administrative, or criminal liability under

applicable law.

Any type of reproduction or distribution of any materials, including translations, is allowed only with the written

permission of Kaspersky.

This document, and graphic images related to it, may be used for informational, non-commercial, and personal

purposes only.

Kaspersky reserves the right to amend this document without additional notification.

Kaspersky assumes no liability for the content, quality, relevance, or accuracy of any materials used in this document

to which rights are held by third parties, or for any potential harms associated with use of the document.

Document revision date: 19.09.2019

© 2019 AO Kaspersky Lab. All Rights Reserved.

https://www.kaspersky.com

https://help.kaspersky.com

https://support.kaspersky.com

Contents

3

Contents About Kaspersky Online File Reputation Service .................................................................................................... 4

Using Kaspersky Online File Reputation Service .................................................................................................... 5

Making requests to Kaspersky Online File Reputation Service.......................................................................... 5

Receiving responses from Kaspersky Online File Reputation Service .............................................................. 6

Receiving HTTP status codes ....................................................................................................................... 6

Receiving object reputation data ................................................................................................................... 6

Receiving error information ......................................................................................................................... 11

Getting information of a file reputation using digital signature.......................................................................... 12

File reputation checking API using certificate thumbprint ................................................................................. 14

About data provisioning ......................................................................................................................................... 17

AO Kaspersky Lab ................................................................................................................................................. 18

Trademark notices ................................................................................................................................................. 19

About Kaspersky Online File Reputation Service

4

About Kaspersky Online File Reputation Service Kaspersky Online File Reputation Service allows you to determine the reputation of objects by checking object

hashes or certificate thumbprints. Kaspersky Online File Reputation Service operates from a single domain,

https://aws.kaspersky.com/file-reputation, and can be accessed with HTTPS requests.

Subscribe to AWS and get a unique token that provides access to Kaspersky Online File Reputation Service. Access

to Kaspersky Online File Reputation Service is individual to every AWS user and is linked to the unique ID of Amazon

account.

https://aws.kaspersky.com/file-reputation

Using Kaspersky Online File Reputation Service

5


► To start using Kaspersky Online File Reputation Service:

1. Subscribe to the service using Amazon SaaS Marketplace

(https://aws.amazon.com/marketplace/pp/B07Y5C4K9T).

2. Get a unique token that provides access to the service. This token is linked to your Amazon account.

3. Start making requests to the service.

Making requests to Kaspersky Online File Reputation Service

► To make requests to Kaspersky Online File Reputation Service and obtain object reputations:

1. Create the header with the following fields to prepare a POST request:

Header field Content

Content-Type Type of data in the request body. The type must be "application/json".

Authorization API token for authentication in the HTTP header. The API token must be "Bearer".

2. Create the request body in JSON format with the object hash (or hashes of several objects) that must be

checked.

3. Send a POST request to https://aws.kaspersky.com/file-reputation/api/v1.0.

Kaspersky Online File Reputation Service supports the use of MD5, SHA1, and SHA256 hashes.

Note that a request must not contain the hash of an object more than once.

Hashes are passed into the body of the request. Hashes must be separated with commas and enclosed in square

brackets.

Example:

POST https://aws.kaspersky.com/file-reputation/api/v1.0

Content-Type: application/json

Authorization: Bearer

eyJ0eXAiOiJKV1QiLcJhbGciOIJSUzUxMiJ9.ew0KICAgICAgICJjdXN0b21lcklkIjogIj

["0x38372AA4CC9FBD0EB7A26FC7B5F24562", "AA5EDC3A7E6946DC810353E01D555CD0"]

https://aws.amazon.com/marketplace/pp/B07Y5C4K9T

https://aws.kaspersky.com/file-reputation/api/v1.0


6

Receiving responses from Kaspersky Online File Reputation Service

A response from Kaspersky Online File Reputation Service consists of the following parts:

HTTP standard response code

Use this code to determine the status of the request. You can determine whether there are any errors.

Response body

Object reputation data is passed in the response body in JSON format.

Receiving HTTP status codes

A response from Kaspersky Online File Reputation Service can have one of the following standard HTTP return

codes:

Code Description

2XX The request is successfully processed.

Information about the object reputation is returned in

the response body.

3XX The request to the service is redirected.

4XX or 5XX An error has occurred.

Information about the error is returned in the response

body.

Receiving object reputation data

If Kaspersky Online File Reputation Service successfully handles a request, it returns a 2XX status code and a

response body with object reputation information.

Format of the response body

The body of the response is a JSON object that has the following format:

{

"<checksum1>": {<object_information1>},

"<checksum2>": {<object_information2>},

...

"<checksumN>": {<object_informationN>}

}

Known and unknown objects

In the above pattern, <object_information> can have one of the following values:

Response field Value


7


File hashes MD5

SHA1

SHA256

URL url—Public URL from which the file was downloaded.

File zone zone—

Name of the following zone:

a) Good—File was classified as trusted. Additional scanning is not

required.

b) Bad—File was classified as malicious (not trusted). File can be blocked

without additional scanning.

c) Gray—File classified as RiskWare (KeyLogger, RAdmin, etc.) or signed

by the digital certificate used by RiskWare. File can be additionally

analyzed or blocked/passed according to the user’s security policy.

d) Contradiction—Not enough information about the file to whitelist it.

e) AssumedGood—File is potentially trusted, but there are not enough

factors to declare it trusted.

File category Software Category—File category, according to Kaspersky. For a detailed

list of categories, refer to http://whitelisting.kaspersky.com/catalogue.

Security attributes SecurityTag—Security tags assigned to the file. A file can have several

security tags.

General information

about the file formatType—File format.

size—File size (in bytes).

originalFileName—Original file name extracted from the FileVersionInfo

property (FVI).

fileVersion—File version extracted from FVI.

timeAdded—Time when the file was registered in the Whitelisting database.

Product information Name—Product name extracted from FVI.

Version—Product version.

Vendor information Name—Vendor’s name.

Information about

digital signatures of

the file

TimeStamp—Time and date when the file was signed.

signatureStatus—Status of the digital signature:

a. Discredited

b. Gray

c. Trusted

d. Unknown (no reasons to trust)

e. Not Valid (unknown)

Type—Type of the digital signature (direct or Windows Catalog File (CAT)).

http://whitelisting.kaspersky.com/catalogue


8


Information about

certificate Serial—Serial number of the certificate.

Issued—Date when the certificate was issued.

Expires—Certificate expiration date.

ThumbPrint—Unique identifier of the certificate.

Vendor—Vendor’s name.

Issuer—Name of the certificate issuer.

Results of anti-virus

scanning of the file Verdict—Verdict of the anti-virus scanner.

verdictType—Type of the verdict:

a) Clean—This verdict is returned if the file was successfully extracted and

scanned.

b) Virus—If the file contains more than one type of malware, the verdict with

the highest priority is returned. More dangerous malware has higher priority.

c) Not-A-Virus—Riskware, Adware, etc.

d) Unknown—This verdict can be returned if the file is protected by a

password or is corrupted.

verdictChangeTime—Time and date of the last verdict change.

Statistics day—Popularity of the file on the previous day, according to KL statistics.

Week—Popularity of the file during the last week, according to KL statistics.

twoWeeks—Popularity of the file during the last two weeks, according to KL

statistics.

Month—Popularity of the file during the last month, according to KL statistics.

FirstSeen—Date when the file was first seen in the Whitelisting database.

lastSeen—Date when the file was last seen in the Whitelisting database.

Statistics by country CountryCode—Code of the country where the file is used.

Percent—Percentage of people who use this file in the country, according to KL

statistics.


9


Information about

the container files

A container file is an archive or installer that the scanned file was extracted from. Such a

file can be downloaded from some outside source.

ParentMD5—MD5 hash of the container file.

ParentSHA1—SHA1 hash of the container file.

ParentSHA256—SHA256 hash of the container file.

ParentOriginalFileName—Original name of the container file.

ParentFileName—Name of the container file.

ParentSignatureType—Type of the digital signature (direct or CAT) of the

container file (if any).

ParentTimeAdded—Time and date when information about the container file

was added to the Whitelisting database.

ParentSize—Size of the container file (in bytes).

ParentFormatType—Format of the container file.

Response body example

Example:

{

"38372AA4CC9FBD0EB7A26FC7B5F24562": {

"data": {

"md5": "0x38372AA4CC9FBD0EB7A26FC7B5F24562",

"sha1": "0xA38BC7506FC264F7D91E5C33715E32060AF9DA51",

"sha256":

"0xC70B8CBB2AC962B343535454E4F2BCB3E48D83A04792C64BC768D59B3C1BF403",


10

Example:

"url":

"https://dl2.pushbulletusercontent.com/IeAa16svDa6XgILQ7zBHl4oX3t71coDM/chr

ome.exe",

"categorization": "Browsers\\Web Browsers",

"summary": {

"formatType": "PE32/EXE",

"size": 945496,

"originalFileName": "chrome.exe",

"fileName": "chrome.exe",

"fileVersion": "56.0.2924.87",

"timeAdded": "2017-02-02T14:13:00",

"product": {

"name": "Google Chrome",

"version": "56.0.2924.87"

},

"vendor": {

"normalizedName": "Google Corporation",

"homepage": "http://www.google.com",

"name": "Google Inc."

}

},

"statistics": {

"day": 5422,

"week": 9532,

"twoWeeks": 9532,

"month": 10398,

"firstSeen": "2017-02-01T23:34:00",

"lastSeen": "2019-07-10T23:00:00"

},

"summaryScanResult": {

"verdict": "Clean",

"verdictType": "Clean"

},

"geography": [

{

"countryCode": "ru",

"percent": 20,

"countryName": "Russian Federation"

},

{

"countryCode": "00",

"percent": 80,

"countryName": "Other"

}

],

"zoneName": "Good",

"signatures": [


11

{

"timeStamp": "2017-02-01T09:01:18",

"status": "Trusted",

"type": "Direct",

"certificate": {

"serial": "2A9C21ACAAA63A3C58A7B9322BEE948D",

"issued": "2015-12-16T00:00:00",

"expires": "2018-12-16T23:59:59",

"thumbPrint": "0x5A9272CE76A9415A4A3A5002A2589A049312AA40",

"vendor": "Google Inc",

"issuer": "Symantec Class 3 SHA256 Code Signing CA"

}

}

],

"packages": [

{

"sha256":

"0x9EA642A1311A7D4C24C2CAB7A0DBDF91A085E9E6483541CEEEC438AAE0DED367",

"fileName":

"9ea642a1311a7d4c24c2cab7a0dbdf91a085e9e6483541ceeec438aae0ded367",

"timeAdded": "2017-02-02T14:12:00",

"size": 166745905,

"formatType": "ARC/7Z",

"signatureType": 0

},

{

"sha256":

"0x36BBFA1A4B2771578F1ECF82699A22D6E889D23DCB5AA0C6E2DF6F9859B33114",

"originalFileName": "",

"fileVersion": "56.0.2924.87"

"timeAdded": "2017-02-12T04:57:00",

"size": 86163968,

"formatType": "PE32/EXE",

"signatureType": 0

}

]

}

}

Receiving error information

If an error has occurred, Kaspersky Online File Reputation Service returns a 4XX or 5XX status code and a response

body with error information.

The response body contains error information in JSON format as follows:

{"message": "<error message text>"}


12

Getting reputation of a file by its digital signature

► To get the reputation of a file by its digital signature in Kaspersky Online File Reputation Service:

1. Get the digital signatures of the file.

A file can contain several digital signatures. Note that Kaspersky Online File Reputation Service might

contain no information about one digital signature, but would contain information about another one instead.

Therefore, you may have to check several digital signatures before you get the information you are seeking

from Kaspersky Online File Reputation Service.

Figure 1: Digital signatures

Use signatures created by using the following algorithms (in descending order of priority:

a. SHA512

Such signatures are rare.

b. SHA256

c. SHA1

d. MD5

e. MD4


13

f. MD2

2. Check that the signature is valid.

Figure 2: Checking digital signature

3. Check the signing time (see the figure above).

If the signing time is not verified, you can use the current date and time in the next step at your own risk.

You are responsible for the information you provide to the service. If you provide incorrect data (for

example, an invalid signature or an invalid time stamp), the response from the service may be incorrect:

a file may be declared valid even though it is malicious.


14

4. Get the thumbprint of the certificate that signs the file.

Figure 3: Certificate thumbprint

Reputation checking API that uses certificate thumbprint of a file

The information collected through reputation checking is provided to Kaspersky Online Reputation Service.

► To check a file,

Make a POST request to https://aws.kaspersky.com/file-reputation/api/v1.0/signature.

The body of the request must be in JSON format. Each item in the request body consists of the following fields:

Field Description

key The key field contains the file hash. This field is

mandatory.

https://aws.kaspersky.com/file-reputation/api/v1.0/signature


15

Field Description

signature The signature field contains two fields:

thumbprint

Contains the thumbprint of the digital

certificate that signs the file.

date

Contains the date and time, in ISO format,

when the file was signed.

This field is optional. If there is no signature field,

the file is checked by its hash. If the signature field is

provided, the file is first checked by its hash; if the file

hash is unknown, the certificate thumbprint is

checked.

Example:

[

{

key: "0000000000000000000000000000000000000000",

signature: {

thumbprint: "1000000000000000000000000000000000000000",

date: "2017-01-01"

}

},

{

key:"0000000000000000000000000000000000000001",

signature: {

thumbprint: "2000000000000000000000000000000000000000",

date: "2017-02-01"

}

},

{

key:"0000000000000000000000000000000000000002"

}

]

Response format

If Kaspersky Online File Reputation Service successfully processes a request (2XX status code), the response body

contains a JSON-formatted array of check results for every object checked and contains the following fields:

Field Description


16

Field Description

data This field is provided only if Kaspersky Online File

Reputation Service has found the information about

the file. The following field is contained in the data

field:

zone

Indicates whether a file is trusted (value 1) or

malicious (value 2).

status Specifies returned status code.

message Specifies error message text.

Example:

{

"0000000000000000000000000000000000000000": {

"data": {

"zone": 1

}

},

"0000000000000000000000000000000000000001": {

"data": {

"zone": 2

}

},

"0000000000000000000000000000000000000002": {

"status": 1,

"message": "Not Found"

}

}

HTTP status codes and error information

The possible HTTP status codes returned by Kaspersky Online File Reputation Service are described in section

"Receiving HTTP status codes (on page 6)". Information returned by Kaspersky Online File Reputation Service in

case of an error is described in section "Receiving error information (on page 11)".

About data provisioning

17

About data provisioning AO Kaspersky Lab handles data, which is provided through Kaspersky Online File Reputation Service, in accordance

with the Privacy Policy of the service. This Privacy Policy describes, in particular, how AO Kaspersky Lab protects

the data, where it processes the data, and the rights of data subjects. AO Kaspersky Lab’s Privacy Policy can be read

at https://www.kaspersky.com/Products-and-Services-Privacy-Policy.

The purpose of data processing is to protect end users from threats to information security.

The provided data is used to do the following:

Determine the reputation of scanned objects.

Discover new threats and their sources.

Increase the efficiency of Kaspersky Online File Reputation Service components.

Reduce false positives.

Obtain information about the number of objects with a known reputation.

Kaspersky Online File Reputation Service will send the following types of data to AO Kaspersky Lab automatically

and on a regular basis:

Checksums of processed files (MD5) and signature thumbprints

https://www.kaspersky.com/Products-and-Services-Privacy-Policy

AO Kaspersky Lab

18

AO Kaspersky Lab Kaspersky is a world-renowned vendor of systems protecting computers against digital threats, including viruses and

other malware, unsolicited email (spam), and network and hacking attacks.

In 2008, Kaspersky was rated among the world’s top four leading vendors of information security software solutions

for end users (IDC Worldwide Endpoint Security Revenue by Vendor). Kaspersky is the preferred vendor of computer

protection systems for home users in Russia (IDC Endpoint Tracker 2014).

Kaspersky was founded in Russia in 1997. It has since grown into an international group of companies with 38 offices

in 33 countries. The company employs more than 3,000 skilled professionals.

Products. Kaspersky products provide protection for all systems, from home computers to large corporate networks.

The personal product range includes security applications for desktop, laptop, and tablet computers, smartphones

and other mobile devices.

The company offers protection and control solutions and technologies for workstations and mobile devices, virtual

machines, file and web servers, mail gateways, and firewalls. The company's portfolio also features specialized

products providing protection against DDoS attacks, protection for industrial control systems, and prevention of

financial fraud. Used in conjunction with centralized management tools, these solutions ensure effective automated

protection for companies and organizations of any size against computer threats. Kaspersky products are certified by

major test laboratories, compatible with software from diverse vendors, and optimized to run on many hardware

platforms.

Kaspersky virus analysts work around the clock. Every day they uncover hundreds of thousands of new computer

threats, create tools to detect and disinfect them, and include their signatures in databases used by Kaspersky

applications.

Technologies. Many technologies that are now part and parcel of modern anti-virus tools were originally developed

by Kaspersky. It is no coincidence that many other developers use the Kaspersky Anti-Virus engine in their products,

including: Alt-N, Asus, BAE Systems, Blue Coat, Check Point, Cisco Meraki, Clearswift, D-Link, Facebook, General

Dynamics, H3C, Juniper Networks, Lenovo, Microsoft, NETGEAR, Openwave Messaging, Parallels, Qualcomm,

Samsung, Stormshield, Toshiba, Trustwave, Vertu, and ZyXEL. Many of the company’s innovative technologies are

patented.

Achievements. Over the years, Kaspersky has won hundreds of awards for its services in combating computer

threats. Following tests and research conducted by the reputed Austrian test laboratory AV-Comparatives in 2014,

Kaspersky ranked among the top two vendors by the number of Advanced+ certificates earned and was ultimately

awarded the Top Rated certificate. But Kaspersky main achievement is the loyalty of its users worldwide. The

company’s products and technologies protect more than 400 million users, and its corporate clients number more

than 270,000.

Kaspersky website: https://www.kaspersky.com

Virus encyclopedia: https://securelist.com

Kaspersky VirusDesk: https://virusdesk.kaspersky.com (for analyzing suspicious files

and websites)

Kaspersky Community: https://community.kaspersky.com

Trademark notices

19

Trademark notices Registered trademarks and service marks are the property of their respective owners.

Firefox and Mozilla are trademarks of the Mozilla Foundation.

Linux is the registered trademark of Linus Torvalds in the United States and other countries.

Windows is a registered trademark of Microsoft Corporation in the United States and other countries.

Documents

Kaspersky Online File Reputation Service