VisualThreat RESTful API (v1.1) Documentation

The VisualThreat Mobile Threat API provides a simple, REST-based interface to take your mobile security to a whole new level. With our RESTful API interface, you can query the Mobile Threat Certificate score, or Mobile Threat Report in JSON format. Third parties can use our scalable API to integrate VisualThreat security features with their applications.

You can call it anytime and anywhere!


Introduction

You can choose different web development languages to access our APIs. For example, If you are using Java, the easiest way to get started is to download the VisualThreat VisualThreat REST Java Example and use it as a library within your own application.

Authentication:  need to provide username and password to retrieve an access token which is used for all other subsequent calls to VisualThreat services. This call is through SSL. 

Access token: a blob string to access VisualThreat services and expires in 5 minutes since a client last contact VisualThreat services. A client has to invoke authentication to fetch a new access token after current one expires. 

Upload: upload an APK to VisualThreat through HTTP post, when VisualThreat doesn’t have the APK yet, in order to generate a report.

Summary: get VisualThreat summary report of an APK. A user can provide a list MD5s of APKs to retrieve multiple summary reports in one call.

Detail: get VisualThreat detailed report for an APK. A detailed report contains all data included in VisualThreat report.

Correlation: return the relationships between a specified APK by its MD5 to malware families through code, text or API calls.

 

REST URIs

URIs for VisualThreat's REST API resource have the following structure:

http://www.visualthreat.com/service/{resource-name}

Authentication

VisualThreat supports authentication method using SSL protocal. After authenticated, you will get an access_token. For rest requests, the system only verify the access_token, and no other authentication are required. However, an access token will expire 5 minutes after being idle. This means if a reponse contains session time out error code(-3), you will have to submit another authentication request.

How to generate MD5

MD5 is the file signature and widely used in each system, you can use the following javamethod to generate the md5 if you don't have existing tool.

											

		MessageDigest md = MessageDigest.getInstance("MD5");
		FileInputStream fis = null;
		StringBuffer hexString = new StringBuffer();
		try {
			fis = new FileInputStream(file);
			byte[] dataBytes = new byte[1024];
			int nread = 0;
			while ((nread = fis.read(dataBytes)) != -1) {
				md.update(dataBytes, 0, nread);
			}
			byte[] mdbytes = md.digest();

			for (int i = 0; i < mdbytes.length; i++) {
				int val = ((int) mdbytes[i]) & 0xff;
				if (val < 16)
					hexString.append("0");
				hexString.append(Integer.toHexString(val));
			}
		} catch (FileNotFoundException e) {
			e.printStackTrace();
		} catch (IOException e) {
			e.printStackTrace();
		} finally {
			if (fis != null)
				fis.close();
		}
		return hexString.toString().toUpperCase();
        
											
										

Resource Index

This documents the current REST API provided by VisualThreat.

Resources

https://www.visualthreat.com/service/authentication Payload Exercise

Methods

GET 

/service/authentication?username&password

Returns an access token.

request query parameters

parameter value must description
username string yes the user name of the login account
password string yes the password of the login account

response representations

parameter value description
access_token string The server generated token, use this token to communicate with server instead of password

response examples

  • 200 - application/json (property) [expand]

service/upload Payload Exercise

request query parameters

parameter value must description
access_token string yes The server generated token, use this token to communicate with server instead of password
Methods

POST 

This resource expects a multipart post. The media-type multipart/form-data is defined in RFC 1867. Most client libraries have classes which can compose multipart posts. For instance, in Java the Apache HTTP Components library provides MultiPartEntity which can be used to submit a multipart POST.

response representations

parameter value description
callback_url string The report access url, after upload the apk, you can use the callback_url to access the report

response examples

  • 200 - application/json (property) [expand]

/service/{md5}/summary Payload Exercise

request query parameters

parameter value must description
access_token string yes The server generated token, use this token to communicate with server instead of password
md5 string yes The md5 of the sample
Methods

GET 

Query summary report based on the md5 value.

response representations

parameter value description
advertisementIndex int The advertisement score of the report, use 0-100 integer and 100 means the most advertisement embed
correlationDegree int The correlation score of the report, use 0-100 integer and 100 means the most correlation found
riskScore int The risk score of the report, use 0-100 integer and 100 means the most risky
threatCertScore int The risk score of the report, use 0-100 integer and 100 means the most safety
spy int The count of spy related behaviors
networkingActivities int The count of network activity behaviors
fileOperations int The count of file operation behaviors
smsActivities int The count of sms related behaviors
codeExecution int The count of code execution behaviors
dataLeakage int The count of data leakage behaviors
riskAPI int The count of risky apis
maliciousBehavior int The count of malicious behaviors
procsssTime long The time stamp of report generation
submisionTime long The submission time stamp of sample upload
virus string The virus name of the sample
lastQueryTime long The time stamp of last query report

response examples

  • 200 - application/json (property) [expand]

/service/summary Payload Exercise

request query parameters

parameter value must description
access_token string yes The server generated token, use this token to communicate with server instead of password
Methods

POST 

Submit one or more md5 at the same time and be able to get the list of summuary for each report. Notice: only a newer(when versions a request contains are less than that stored in our store) report will be returned. This prevents from sending duplicate report content back.

response representations

parameter value description
The advertisement score of the report, use 0-100 integer and 100 means the most advertisement embed int description
correlationDegree int The correlation score of the report, use 0-100 integer and 100 means the most correlation found
riskScore int The risk score of the report, use 0-100 integer and 100 means the most risky
threatCertScore int The risk score of the report, use 0-100 integer and 100 means the most safety
spy int The count of spy related behaviors
networkingActivities int The count of network activity behaviors
fileOperations int The count of file operation behaviors
smsActivities int The count of sms related behaviors
codeExecution int The count of code execution behaviors
dataLeakage int The count of data leakage behaviors
riskAPI int The count of risky apis
maliciousBehavior int The count of malicious behaviors
procsssTime long The time stamp of report generation
submisionTime long The submission time stamp of sample upload
virus string The virus name of the sample
lastQueryTime long The time stamp of last query report
message string The friendly error message if exist
code int The error code if exist

response examples

  • 200 - application/json (property) [expand]

/service/{md5}/detail Payload Exercise

request query parameters

parameter value must description
access_token string yes The server generated token, use this token to communicate with server instead of password
md5 string yes The server generated token, use this token to communicate with server instead of password
Methods

GET 

Query detail report based on the md5 value.

response representations

parameter value description
lastSeen long The time stamp of last sample upload
crc32 string The CRC32 of the sample
sha256 string The SHA256 of the sample
lastAnalysisTime long The time stamp of last analyse report
behavior Map The map of the behaviors
virus string The virus name of the sample
services array The defined array of android services
permission array The defined array of android permissions
activities array The defined array of android activities
sha1 string The SHA1 of the sample
urlList array The array of url used in the sample
flag string the url security information
url string the url string of the website
ip string the ip address of the site
country string the country of the site belongs to
city string the city of the site belongs to
certificate object the certificate information of the sample
Version string the report version of the sample
SerialNumber string the serial number of the certificate
SignAlgorithm string the signature algorithm of the certificate
ValidityBefore string the start validity date of the certificate
ValidityAfter string the end validity date of the certificate
Issuer string the issuer of the certificate
Subject string the subject of the certificate
PubKeyContent string the public key content of the certificate
OldPubKeyHash string the old public key content of the certificate
family string the virus name of the sample
name string the name of the sample
sensitive strings array the array of sensitive string in the sample
path string the file location in the server
lastQueryTime long the time stamp of the first query report
firstSeen string the time stamp of the first time generate report
sourceType string the source type of the sample
files string the files of the sample
riskMatrix object the map of risk in the sample
spy object the spy detail of the sample
networkingActivities object the network activities detail of the sample
fileOperations object the file operation detail of the sample
findings int The count of behavior matches
apiName array The array of apis used in the sample
library array The array of libraries used in the sample
behaviorItem string The name of the behavior item
descriptions string The description of the behavior
codeExecution object The count of code execution behaviors
unix object The unix command used in the sample
category string The type of the command
description string The description of the command
command string The command detail
dynamicBehavior array The dynamic behavior which is run in sandbox
processingTime long The report processing time stamp
size long The sample bytes size
sampleHasPermissions array The permission related to the sample
permission object The permission information
name string The permission name
used boolean The permission useage flag
md5 string The md5 of the sample
fileName string The file name of the sample

response examples

  • 200 - application/json (property) [expand]

/service/{md5}/correlation/family Payload Exercise

request query parameters

parameter value must description
access_token string yes The server generated token, use this token to communicate with server instead of password
md5 string yes description
Methods

GET 

Query family corrleation information based on the md5 value.Here is a typical example of the correlation 
family

response representations

parameter value description
allFamily int The count of family correlation belongs to the sample
allCodeString int The count of code correlation belongs to the sample
name string The virus name of the sample
children array The correlation nodes of the sample
name string The md5 of the correlation node
nodeType string The node type of the correlation node

response examples

  • 200 - application/json (property) [expand]

/service/{md5}/correlation/api-correlation Payload Exercise

request query parameters

parameter value must description
access_token string yes The server generated token, use this token to communicate with server instead of password
md5 string yes The md5 of the sample
Methods

GET 

Query api corrleation information based on the md5 value. Here is a typical example of the correlation.
api

 

response representations

parameter value description
name string The md5 of the sample
children array The correlation nodes of the sample
correlationType int The correlation type of the correlation node
nodeType string The node type of the correlation node

response examples

  • 200 - application/json (property) [expand]

/service/{md5}/correlation/text-correlation Payload Exercise

request query parameters

parameter value must description
access_token string yes The server generated token, use this token to communicate with server instead of password
md5 string yes The md5 of the sample
Methods

GET 

Query text corrleation information based on the md5 value. Here is a typical example of the correlation 
text

response representations

parameter value description
name string The md5 of the sample
children array The correlation nodes of the sample
correlationType int The correlation type of the correlation node
nodeType string The node type of the correlation node

response examples

  • 200 - application/json (property) [expand]

 

Payload Exercise

You can use this build-in RESTful client to run the webservice.

Request

Resource:
url:
Jquery call real time parameter
																			
																				
$.ajax({
	type: "",
	headers : {
		"Accept" : "application/json; charset=utf-8",
		"Content-Type" : "application/json; charset=utf-8"
	},
	dataType: "json",
	contentType:"application/json; charset=utf-8",
	url : "",
	data : 
}
											
																			
																			

Response

											

											
												

 

Handling Errors

Requests made to our APIs can result in a number of different error responses, the following section describes the list of error codes with their messages.

Receiving Error Codes

The following represents a common error response resulting from a failed API request:

											
												    
{
    "error": {
        "message": "Invalid username or password",
        "code": -2
    }
}
											
										

Error Codes

Code Description

-1

unknown error

-2

Invalid username or password

-3

Your access token is expired

-4

Your access token is invalid

-5

Your md5 is incorrect

-6

Unable to find your md5 report

-7

Not supported file type

-8

Invalid request

-9

The report is in the processing, please try again later

-10

Invalid licence configured, please contact the site admin

-11

Not valid MD5 value

-12

you are only allowed to view 5 reports per day without login

-13

You are only allowed to view 5 reports per day, Upgrade to the Premium account today to access hundreds of reports per day! See more details please visit our service at http://www.visualthreat.com/our_service.action