KleenScan API

Getting Started

The KleenScan API provides a convenient way to perform Scans and gather information about Scan Results from the Kleenscan web service.

The API is available via:https://kleenscan.com/api/v1

Authentication

In order to authenticate with the Kleenscan API you will need a temporary X-Auth-Token.

Log in to your account, go to Profile > API > Generate, in order to create a fresh X-Auth-Token

The X-Auth-Token is your one-way access token towards the Kleenscan API. You can manually refresh your token by clicking on Generate button again. Authentication token is a part of every single API request and should be placed inside of a request header.

Retrieving Scanners

Before sending an actual scan request via API you need to provide a list of desired Antivirus scanners.

By using the https://kleenscan.com/api/v1/get/avlist call you will receive an array of key-pair values.

PHP Example

$url = "https://kleenscan.com/api/v1/get/avlist"; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true); curl_setopt($ch, CURLOPT_POST, false); curl_setopt($ch, CURLOPT_HTTPGET, true); curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'X-Auth-Token: Your Authentication Token Here'
)); $result = curl_exec($ch); $result = json_decode($result, true); curl_close($ch);

Python Example

import requests url = 'https://kleenscan.com/api/v1/get/avlist' r = requests.get(url, headers={'X-Auth-Token': 'Your Authentication Token Here'}) print(r.text)

Successful response, containing the list of scanners looks like this:

"success" => true "message" => "" "data" => [
"file" => [
"adaware" => "AdAware", "amiti" => "Amiti", "arcabit" => "Arcabit", "avast" => "Avast", "avg" => "AVG", "kaspersky" => "Kaspersky", "maxsecure" => "Max Secure", "mcafee" => "McAfee", "microsoftdefender" => "Microsoft Defender"
], "url" => [
"adaware" => "AdAware", "amiti" => "Amiti", "arcabit" => "Arcabit", "avast" => "Avast", "avg" => "AVG", "kaspersky" => "Kaspersky", "maxsecure" => "Max Secure", "mcafee" => "McAfee", "microsoftdefender" => "Microsoft Defender"
], "runtime" => [
"amiti" => "Amiti", "arcabit" => "Arcabit", "avast" => "Avast", "avg" => "AVG", "bullguard" => "Bullguard", "gdata" => "G Data", "kaspersky" => "Kaspersky", "nod32" => "Nod32"
],
]

Files

Uploading Files

In order to upload files to our service, you need to retrieve the authentication token mentioned in the previous step.

The maximum number of uploaded files is equivalent to the user subscription package daily and monthly limits.

You can only upload a single file per request by using the following route: https://kleenscan.com/api/v1/file/scan via POST request

This route accepts only two parameters avList and path.

The avList is a coma separated string of antivirus names without any spaces in between like so: avira,microsoftdefender,trendmicro You can also send a wildcard parameterall which will result in selection of all available Antivirus scanners.

The path parameter is a CURLfile object type.

PHP Example

$url = "https://kleenscan.com/api/v1/file/scan"; $path = "your_file_path_here"; $file = new \CURLFile($path); $params = array( "avList" => "avast,avg", "path" => $file ); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_HTTPHEADER, array( 'Content-Type: multipart/form-data',
'X-Auth-Token: Your Authentication Token Here'
)); curl_setopt($ch, CURLOPT_POSTFIELDS, $params); $result = curl_exec($ch); $result = json_decode($result, true); curl_close($ch);

Python Example

import requests url = 'https://kleenscan.com/api/v1/file/scan' files = {'path': open('your_file_path_here', 'rb')} data = {'avList': 'avast,avg'} r = requests.post(url, files=files, data=data, headers={'X-Auth-Token': 'Your Authentication Token Here'}) print(r.text)

Successful response, containing the scan_token looks like this:

"success" => true "message" => ""; "data" => [
"scan_token" => "bc0890be7133616e68f5d81207cca045"
]

Retrieving Results

In order to retrieve your scan results call the https://kleenscan.com/api/v1/file/result/{scan_token} route via GET request.

scan_token is received as a result of a successful scan call.

After receiving your scan_token you are able to perform a GET request like so:

PHP Example

$url = "https://kleenscan.com/api/v1/file/result/{scan_token}"; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($ch, CURLOPT_POST, false); curl_setopt($ch, CURLOPT_HTTPGET, true); curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"X-Auth-Token: Your Authentication Token Here"
)); $result = curl_exec($ch); $result = json_decode($result, true); curl_close($ch);

Python Example

import requests url = 'https://kleenscan.com/api/v1/file/result/{scan_token}' r = requests.get(url, headers={'X-Auth-Token': 'Your Authentication Token Here'}) print(r.text)

Successful response contains an array stored in the data variable. Each member of the data array is an array itself with the following parameters:

avname is the name of the Antivirus software.

status represents the current state of the scan in question. The possible values are pending, scanning, timeout, failed, ok, incomplete

flagname represents the actual scan result. Keep in mind that flagname will only show results in case the status parameter has the ok return value.

*Note* scan results may take up to 5 minutes depending on the size of the file and the current server status.

URLs

Scanning URLs

In order to begin scanning URLs on our service, you need to retrieve the authentication token mentioned in the first step of this documentation.

Maximum number of allowed URL scans per day is equivalent to the user subscription package daily and monthly limits.

You can only scan a single URL per API request by using the following route: https://kleenscan.com/api/v1/url/scan via POST request

This route accepts only two parametersavList and url.

The avList is a coma separated string of antivirus names without any spaces in between like so: avira,microsoftdefender,trendmicro You can also send a wildcard parameterall which will result in selection of all available Antivirus scanners.

The url parameter is a string containing the desired URL as in www.kleenscan.com/index

PHP Example

$url = "https://kleenscan.com/api/v1/url/scan"; $params = array( "avList" => "avast,avg", "url" => "your_url_here"; ); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_HTTPHEADER, array( 'Content-Type: multipart/form-data',
'X-Auth-Token: Your Authentication Token Here'
)); curl_setopt($ch, CURLOPT_POSTFIELDS, $params); $result = curl_exec($ch); $result = json_decode($result, true); curl_close($ch);

Python Example

import requests url = 'https://kleenscan.com/api/v1/url/scan' data = {'avList': 'avast,avg', 'url': 'http://malware.wicar.org/data/eicar.com'} r = requests.post(url, files=None, data=data, headers={'X-Auth-Token': 'Your Authentication Token Here'}) print(r.text)

Successful response, containing the temporary token looks like this:

"success" => true "message" => "" "data" => "bc0890be7133616e68f5d81207cca045"

The temporary token is your one-way ticket towards the receiving of the scan_token which will enable you to retrieve your scan results.

Why the temporary token ? We need to perform series of checks on the URL you've provided and once we've determined that everything is as we expect it to be, the actual scan may begin.

Your next step is to retrieve your scan_token by using the temporary token.

PHP Example

$url = "https://kleenscan.com/api/v1/url/status/your_temporary_token_here"; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true); curl_setopt($ch, CURLOPT_POST, false); curl_setopt($ch, CURLOPT_HTTPHEADER, array( 'Content-Type: multipart/form-data',
'X-Auth-Token: Your Authentication Token Here'
)); $result = curl_exec($ch); $result = json_decode($result, true); curl_close($ch);

Python Example

import requests url = 'https://kleenscan.com/api/v1/url/status/your_temporary_token_here' data = {'avList': 'avast,avg', 'url': 'http://malware.wicar.org/data/eicar.com'} r = requests.get(url, files=None, data=data, headers={'X-Auth-Token': 'Your Authentication Token Here'}) print(r.text)

Successful response, containing the scan_token looks like this:

"success" => true "message" => ""; "data" => [
"status" => 2, "step" => 5, "error" => null, "scan_token" => "your_scan_token_here", "abort_code" => null
]

Retrieving Results

In order to retrieve your scan results call the https://kleenscan.com/api/v1/url/result/{scan_token} route via GET request.

scan_token is received as a result of a successful scan call.

After receiving your scan_token you are able to perform a GET request like so:

PHP Example

$url = "https://kleenscan.com/api/v1/url/result/{scan_token}"; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($ch, CURLOPT_POST, false); curl_setopt($ch, CURLOPT_HTTPGET, true); curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"X-Auth-Token: Your Authentication Token Here"
)); $result = curl_exec($ch); $result = json_decode($result, true); curl_close($ch);

Python Example

import requests url = 'https://kleenscan.com/api/v1/url/result/{scan_token}' r = requests.get(url, headers={'X-Auth-Token': 'Your Authentication Token Here'}) print(r.text)

Successful response contains an array stored in the data variable. Each member of the data array is an array itself with the following parameters:

avname is the name of the Antivirus software.

status represents the current state of the scan in question. The possible values are pending, scanning, timeout, failed, ok, incomplete

flagname represents the actual scan result. Keep in mind that flagname will only show results in case the status parameter has the ok return value.

Quick Summary

In short, in order to successfully scan and retrieve your url scan results you are supposed to follow the following steps:

1. Send the desired scan request containing the URL to the https://kleenscan.com/api/v1/url/scan via POST request.

2. Successful request will result in a response containing a temporary_token.

3. Send the retrieved temporary_token to https://kleenscan.com/api/v1/url/status/your_temporary_token_here via GET request.

4. Successful request will result in a response containing a scan_token.

5. Send the retrieved scan_token to https://kleenscan.com/api/v1/url/result/{scan_token} via GET request and retrieve your results.

Downloadable Content

You can also download fully prepared examples for both URL and FILE scans, in both PHP and Python.

All you have to do is replace your Authentication Token and your desired file or URL with the temporary variable inside the example.

In order to download PHP example for file scan, click here , for URL scan example, click here.

In order to download Python example for file scan, click here , for URL scan example, click here.