Authentication
API Tools
API Documentation
Coming Soon
  • - Periodic Scan
  • - Scan History

API Introduction

Authentication

In order to authenticate with the Kleenscan API you will need to generate an API token.

Log in to your account and go to Profile > API > Generate , in order to create a API token.ååå

The API token is your one-way access token towards the Kleenscan API. You can manually regenerate your token by clicking on the Generate button again (this will revoke the previous token).

The easiest way to use the Kleenscan API is to install our Python Library or our Command Line Tool.

The API token is a part of every single API request and should be placed inside of the HTTP header X-Auth-Token for sending low-level API requests.

The Kleenscan API provides a convenient way to perform scans and gather information about scan results from the Kleenscan web service.

API Tools

Installation

To install the Kleenscan Python Library and Command Line tools run in your preferred command line/terminal: 

pip3 install kleenscan

To use any Kleenscan tool you must first generate a API token.

Python Library

To see more information about the python library including examples and documentation, view the Kleenscan PyPi Package

Example retrieval of file and URL scanners

                    # Import kleenscan
from kleenscan import Kleenscan
import json

# Instantiate a Kleenscan object
ks = Kleenscan('Your Authentication Token Here', verbose=False)

# List antivirus engines available (default return value is a JSON string)
result = ks.av_list()
kleenscan_result = json.loads(result)

# Print available file scanners.
print(kleenscan_result['data']['file'])

# Print available URL scanners.
print(kleenscan_result['data']['url'])

Example file, URL and specified antivirus scanning

                    # Import kleenscan
from kleenscan import Kleenscan

# Scan a file (default return value is a JSON string)
result = ks.scan('binary.exe')
print(result)

# Scan a file (default return value is a JSON string)
result = ks.scan_url('Your URL to scan here')
print(result)

# Scan a file (default return value is a JSON string) with list of antivirus engines
result = ks.scan('binary.exe', av_list=['avg', 'microsoftdefender', 'crowdstrike'])
print(result)

# Scan a URL (default return value is a JSON string) with list of antivirus engines
result = ks.scan_url('Your URL to scan here', av_list=['avg', 'microsoftdefender', 'crowdstrike'])
print(result)

Command Line Tool

Usage

Display help

kleenscan -h

List available antivirus engines

kleenscan -t "Your Authentication Token Here" -l

Scan a local file

kleenscan -t "Your Authentication Token Here" --file binary.exe

Scan a URL

kleenscan -t "Your Authentication Token Here" --url https://example.com

Scan a local file with list of antivirus engines

kleenscan -t "Your Authentication Token Here" --file binary.exe --antiviruses avg microsoftdefender avast

Scan a URL with list of antivirus engines

kleenscan -t "Your Authentication Token Here" --url https://google.com --antiviruses avg microsoftdefender avast

Batch Build & Scan Example

Example batch script to build a source.c file using cl.exe and auto scan using the Kleenscan CLI tool.

build.bat 
                    @echo off
CALL "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat"
cl source.c /Fe:binary.exe
python3 -m kleenscan -t "Your Authentication Token Here" -f binary.exe

Low-level API

The API is available at the endpoint: https://kleenscan.com/api/v1

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 API method, you will receive a JSON object of key-pair values. This object will contain available AV engines for scans.

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);
echo $result;

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 JSON response text, containing the key, value pairs of url or file scanner in data looks like this: 

                    {
    "success": true,
    "httpResponseCode": 200,
    "message": "OK",
    "data": {
        "file": {
            "adaware": "AdAware",
            "alyac": "Alyac",
            "amiti": "Amiti",
            "arcabit": "Arcabit",
            "avast": "Avast",
            "avg": "AVG",
            "avira": "Avira",
            "bullguard": "Bullguard",
            "clamav": "ClamAV",
            "comodo": "Comodo",
            "comodolinux": "Comodo Linux",
            "crowdstrike": "Crowdstrike Falcon",
            "drweb": "DrWeb",
            "emsisoft": "Emsisoft",
            "escan": "eScan",
            "fprot": "F-Prot",
            "fsecure": "F-Secure",
            "gdata": "G Data",
            "ikarus": "IKARUS",
            "immunet": "Immunet",
            "kaspersky": "Kaspersky",
            "maxsecure": "Max Secure",
            "mcafee": "McAfee",
            "microsoftdefender": "Microsoft Defender",
            "nano": "NANO",
            "nod32": "NOD32",
            "norman": "Norman",
            "quickheal": "Quick Heal",
            "secureageapex": "SecureAge APEX",
            "seqrite": "Seqrite",
            "sophos": "Sophos",
            "trendmicro": "TrendMicro",
            "vba32": "Vba32",
            "viritexplorer": "VirITExplorer",
            "virusfighter": "VirusFighter",
            "xvirus": "Xvirus",
            "zillya": "Zillya",
            "zonealarm": "ZoneAlarm",
            "zoner": "Zoner"
        },
        "url": {
            "adaware": "AdAware",
            "amiti": "Amiti",
            "arcabit": "Arcabit",
            "avast": "Avast",
            "avg": "AVG",
            "avira": "Avira",
            "bullguard": "Bullguard",
            "clamav": "ClamAV",
            "comodo": "Comodo",
            "drweb": "DrWeb",
            "emsisoft": "Emsisoft",
            "escan": "eScan",
            "fprot": "F-Prot",
            "fsecure": "F-Secure",
            "gdata": "G Data",
            "ikarus": "IKARUS",
            "immunet": "Immunet",
            "kaspersky": "Kaspersky",
            "maxsecure": "Max Secure",
            "mcafee": "McAfee",
            "microsoftdefender": "Microsoft Defender",
            "nano": "NANO",
            "nod32": "NOD32",
            "norman": "Norman",
            "quickheal": "Quick Heal",
            "seqrite": "Seqrite",
            "sophos": "Sophos",
            "trendmicro": "TrendMicro",
            "vba32": "Vba32",
            "virusfighter": "VirusFighter",
            "zillya": "Zillya",
            "zonealarm": "ZoneAlarm"
        },
        "runtime": {
            "avg": "AVG",
            "ikarus": "IKARUS",
            "microsoftdefender": "Microsoft Defender",
            "nod32": "Nod32"
        }
    }
}

Scanning Files

In order to upload files to our service for scanning, you need to retrieve the authentication token mentioned in the previous Authentication 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 endpoint: https://kleenscan.com/api/v1/file/scan via POST request

This route accepts only two HTTP POST parameters avList and path.

The avList's value is a comma separated string of antivirus names without any spaces in between like so: avira,microsoftdefender,trendmicro. You can also provide the valueall to the avList parameter, in which will result in the selection of all available Antivirus scanners.

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);
echo $result;

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 JSON response text, containing the scan_token looks like this: 

                    {
    "success": true,
    "message": "",
    "data": [
        "scan_token": "Scan token md5 hash will be here.."
    ]
}

Retrieving File Results

In order to retrieve your scan results call the https://kleenscan.com/api/v1/file/result/{scan_token} API method via a 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);
echo $result;

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 JSON response text, containing the JSON array data. The data key's value is an array of JSON objects. Each element of the data array is a nested JSON object representing scanners, with the following keys:

avname is the name of the Antivirus software.

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

The flagname key's value represents the actual scan result. Keep in mind that the value of flagname will only show results if the status key's value is equal to ok. Like with the route_token extraction process - you will have to loop over each nested JSON object in data and extract each status key's value and check if the status key's value is equal to ok, timeout, failed incomplete to confirm that all scans are 100% complete. Here's an example of the response when ALL of the scans are fully completed: 

                        {
     "success": true,
     "httpResponseCode": 200,
     "message": "OK",
     "data": [
          {
               "avname": "adaware",
               "status": "ok",
               "flagname": "Trojan.Metasploit.A",
               "lastupdate": "2024-10-31"
          },
          {
               "avname": "alyac",
               "status": "ok",
               "flagname": "Trojan.Metasploit.A",
               "lastupdate": "2024-10-30"
          },
          {
               "avname": "amiti",
               "status": "ok",
               "flagname": "Undetected",
               "lastupdate": "2024-10-30"
          },
          {
               "avname": "arcabit",
               "status": "ok",
               "flagname": "Trojan.Metasploit.A",
               "lastupdate": "2024-10-31"
          }
     ]
}

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 endpoint: https://kleenscan.com/api/v1/url/scan via POST request

This route accepts only two HTTP POST parameters avList and url.

The avList 's value is a comma separated string of antivirus names without any spaces in between like so: avira,microsoftdefender,trendmicro You can also provide the value all to the avList parameter, in which will result in the selection of all available Antivirus scanners.

PHP Example

                    $url = "https://kleenscan.com/api/v1/url/scan";

$params = array(
    "avList" => "all",
    //"avList" => "avast,avg",
    "url" => "Your URL to scan 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);
echo $result;

curl_close($ch);

Python Example

                    import requests

url = 'https://kleenscan.com/api/v1/url/scan'
data = {
    'avList': 'all',
    #'avList': 'avast,avg',
    'url': 'Your URL to scan here'
}

r = requests.post(url, files=None, data=data, headers={'X-Auth-Token': 'Your Authentication Token Here'})
print(r.text)

Successful JSON response text, containing the temporary token looks like this: 

                    {
    "success": true,
    "message": "",
    "data": "bc0890be7133616e68f5d81207cca045"
}

The temporary token is your one-way ticket towards receiving the route_token which will enable you to retrieve your scan results. Your next step is to retrieve your route_token by providing the temporary token to the endpoint: https://kleenscan.com/api/v1/url/status/temporary_token via GET request.

PHP Example

                    $temporary_token = "Your temporary token here";
$url = "https://kleenscan.com/api/v1/url/status/$temporary_token";

$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);
echo $result;

curl_close($ch);

Python Example

                    import requests

temporary_token = 'Your temporary token here'
url = f'https://kleenscan.com/api/v1/url/status/{temporary_token}'

r = requests.get(url, files=None, headers={'X-Auth-Token': 'Your Authentication Token Here'})
print(r.text)

Successful JSON response text, containing the route_token looks like this: 

                    {
    "success": true,
    "message": "".
    "data": [
        "status": 2,
        "step": 5,
        "error": null,
        "route_token": "b29a9a13dc3da4a82ba56c29533d3c80", # Will be null/None until internal checks are finished.
        "abort_code": null
    ]
}

*Note* route_token will not be available immediately and will be null until the internal scans are started. You may have to loop and repeatedly call https://kleenscan.com/api/v1/url/status/your_temporary_token_here for the route_token to eventually be available.

Retrieving URL Results

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

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

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

PHP Example

                    $route_token = "Your scan token here";
$url = "https://kleenscan.com/api/v1/url/result/$route_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);
echo $result;

curl_close($ch);

Python Example

                        import requests

route_token = 'Your scan token here'
url = f'https://kleenscan.com/api/v1/url/result/{route_token}'

r = requests.get(url, headers={'X-Auth-Token': 'Your Authentication Token Here'})
print(r.text)

Successful JSON response text, containing the JSON array data. The data key's value is an array of JSON objects. Each element of the data array is a nested JSON object representing scanners, with the following keys:

avname is the name of the Antivirus software.

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

The flagname key's value represents the actual scan result. Keep in mind that the value of flagname will only show results if the status key's value is equal to ok. Like with the route_token extraction process - you will have to loop over each nested JSON object in data and extract each status key's value and check if the status key's value is equal to ok, timeout, failed incomplete to confirm that all scans are 100% complete. Here's an example of the response when ALL of the scans are fully completed: 

                        {
     "success": true,
     "httpResponseCode": 200,
     "message": "OK",
     "data": [
          {
               "avname": "adaware",
               "status": "ok",
               "flagname": "Trojan.Metasploit.A",
               "lastupdate": "2024-10-31"
          },
          {
               "avname": "alyac",
               "status": "ok",
               "flagname": "Trojan.Metasploit.A",
               "lastupdate": "2024-10-30"
          },
          {
               "avname": "amiti",
               "status": "ok",
               "flagname": "Undetected",
               "lastupdate": "2024-10-30"
          },
          {
               "avname": "arcabit",
               "status": "ok",
               "flagname": "Trojan.Metasploit.A",
               "lastupdate": "2024-10-31"
          }
     ]
}

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.