Download - 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.
Using Kaspersky Online File Reputation Service
5
Using Kaspersky Online File Reputation Service
► 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"]
Using Kaspersky Online File Reputation Service
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
Using Kaspersky Online File Reputation Service
7
Response field Value
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)).
Using Kaspersky Online File Reputation Service
8
Response field Value
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.
Using Kaspersky Online File Reputation Service
9
Response field Value
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",
Using Kaspersky Online File Reputation Service
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": [
Using Kaspersky Online File Reputation Service
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>"}
Using Kaspersky Online File Reputation Service
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
Using Kaspersky Online File Reputation Service
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.
Using Kaspersky Online File Reputation Service
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.
Using Kaspersky Online File Reputation Service
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
Using Kaspersky Online File Reputation Service
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
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.