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
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
.
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.
$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);
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"],
]
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.
$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);
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"]
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:
$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);
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.
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
$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);
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
.
$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);
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]
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:
$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);
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.
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.
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.