API
For your comfort, we had implemented API in viruscheckmate.com style,
so it is very easy to work with, if you had already worked with this service previously.
All you need is to change apikey and url:
$vcm = new viruscheckmate\scanner("API_KEY", "http://avcheck.net/vhm");
Below is a copy from viruscheckmate api page (all unsupported features are cutted off):
VirusCheckMate Developer Guide
General rules of API v1
POST/vhm/api/{version}/{method}/{submethod}/{another_params/}{response type}
Parameter |
Description |
version |
Version of API interface, for now - v1 |
method |
service or check |
Response (in json format):
{
"status": {status}
"status_t": {message}
"data": {...}
}
Variable |
Description |
status |
Request status, 1 is OK and -1 is error, see status_t for additional information |
status_t |
Additional information, 'OK' or error message |
HTTP Statuses:
Value |
Description |
200 |
OK |
206 |
OK, partial results, task is not finished |
400 |
Incorrect input data (see status_t for more information) |
401 |
Authorization errors |
403 |
Account blocked |
404 |
Task not found |
405 |
Method not allowed |
500 |
Service errors |
503 |
Service closed for maintenance |
Get Service Information
Receiving list of available engines.
POST/vhm/api/v1/service/get/
Request parameters:
Parameter |
Required |
Default |
Description |
apikey |
true |
- |
- |
Response:
{
"status": 1
"status_t": "OK"
"data":{
"engines":{
1:{
"id": 1 // Engine ID
"status": 1 // Status of engine:
// 1 - ready
// 0 - unavailable now
"short_name": "nod32" // Short name of engine
"full_name": "ESET NOD32 Antivirus" // Full name
"version": "" // Latest
"def_time": "" // Latest
"type": 3 // Types of checks possible on this engine:
// 1 - only file and webpages
// 2 - only domain
// 3 - all types
"is_cloud": 0 // Always 0
"in_task": 1 // Always 1
}
2:{
"id": 2
"status": 1
"short_name": "mssec"
"full_name": "Microsoft Security Essentials"
"version": "2.1.1116.0"
"def_time": "27-02-14 13:14"
"type": 1
"in_task": 1
}
...
}
"uaprofiles":{} // Not available
"task_type": 0 // Always null
}
}
Examples:
POST/vhm/api/v1/service/get/
POST/vhm/api/v1/service/get/
apikey |
55de2e769181d9259fc0bc96ab6e34c55ba8b909 |
Get Task Data
POST/vhm/api/v1/check/get/{task_id/}{crc32/}{response type}
Request parameters:
Parameter |
Required |
Default |
Description |
task_id |
true |
- |
Task ID (example : 'EU1ZL9n0O5Ka') |
crc |
false |
- |
Checksum from the previous query. If no new data, the field data is empty in response, to
reduce traffic (example: 'crc-32444234')
|
Response:
HTTP Statuses:
Value |
Description |
200 |
Task finished |
206 |
Task in work, partial results returned |
404 |
Task not found |
Data conteins blocks:
Block name |
Description |
info |
Task information |
results |
Results of checks |
objects |
Information about objects |
warnings |
Errors, warnings, and notifications |
crc32 |
CRC32 of data |
Important fields:
Fields name |
Description |
info.status |
Status of task:
- -1
- Error
- 0
- Task in queue
- 1,2,3
- Task in work
- 4,5,6,7
- Task finished
|
results.{engine}.status |
Status of current engine:
- 0
- Not started yet
- 1
- Started
- 2
- Finished
|
results.{engine}.objects.{object}.status |
Status of current object in current engine:
- 0
- Not started yet
- 1
- Fast check is complete, see
fast_detect for result
- 2
- Slow check is complete or not required, see
slow_detect for result
|
warnings.{number}.level |
Level of risk:
- 0
- Debug message (not displayed without the debug mode)
- 1
- Notifications
- 2
- Warnings
- 3
- Errors
- 4
- Critical errors
|
{
"status":1,
"status_t":"Partial results",
"data":{
"info":{
"check_id":"PY3kN2SXumYU", // Task ID
"status":3, // Status
"object_name":"test.rar", // Name of main object
"objects_count":2, // Objects (files, pages...) in task
"objects_size":238592, // Summary size of unpacked objects
"isfast":0, // Option 'option_fast'
"started_at":"28-02-14 14:24:11", // Time of creation (GMT)
"duration":0 // Duration in seconds, equal null if not finished
},
"results":{
"comodo":{ // Short name of engines
"status":2, // Status of task
"objects":{
"first.exe":{ // Object name
"fast_detect":0, // Status of fast detection:
// 1 - detect
// 0 - clean, or not finished
// ('status' of object must be 1 before using this field)
"slow_detect":0, // Status of slow detection:
// 1 - detect,
// 0 - clean, or not finished
// ('status' of object must be 2 before using this field)
"detect_name":"", // Name of detection or empty
"status":2 // Status of current object in current engine
},
"second.exe":{
"fast_detect":0,
"slow_detect":0,
"detect_name":"",
"status":2
}
}
},
"adaware":{
"status":2,
"objects":{
"first.exe":{
"fast_detect":1,
"slow_detect":1,
"detect_name":"Gen:Variant.Kazy.319707",
"status":2
},
"second.exe":{
"fast_detect":1,
"slow_detect":1,
"detect_name":"Gen:Variant.Kazy.319707",
"status":2
}
}
},
"twister":{
"status":1,
"objects":{
"first.exe":{
"fast_detect":1,
"slow_detect":0,
"detect_name":"",
"status":1
},
"second.exe":{
"fast_detect":1,
"slow_detect":0,
"detect_name":"",
"status":1
}
}
},
...
},
"objects":[
{
"object":"first.exe", // Name of object
"size":119296, // Size of object
"md5":"47c1cad6cf170a695670096dda35d4c6", // MD5
"sha1":"fa33cb459217121c2cb849323ecf80d8f615f248" // SHA1
},
{
"object":"second.exe",
"size":119296,
"md5":"3608b60a453b6c0e9cc55f02768e1d3e",
"sha1":"0761110ffe313dd8ff8e5e5346db0485e03ec492"
}
],
"warnings":{
"1131585":{ // Number of the ticket for the support
"error":"ERROR_FILE_WARNING", // Unlocale error text,
// for full text of error use the file
"level":2, // Level of risk
"engine_id":30, // ID of engine, if null error is a general
"engine_name":"twister", // Engine short name
"object_name":"first.exe" // Object name
}
},
"crc32":893397190
}
}
Examples:
POST/vhm/api/v1/check/get/PY3kN2SXumYU/
POST/vhm/api/v1/check/get/PY3kN2SXumYU/crc-893397190/xml
Create New Task
POST/vhm/api/v1/check/new/
Request parameters:
Parameter |
Required |
Default |
Description |
apikey |
true |
- |
- |
task_type |
false |
file |
Type of check, can be 'file', 'domain' |
file |
false |
- |
File for check, required if task_type is 'file', or not specified |
url |
false |
- |
single domain/ip or array of domains/ips |
engines |
false |
main profile |
Enumeration short names separated by ',' Like "nod32,avg,norman,vba32" |
response_type |
false |
on_close |
Wait until the task finished (do not use a field or 'on_close') or return immediately (any value except
'on_close')
|
Response:
If response_type
set to 'on_close' or not used equal 'Get Task Data' results
Else return immediately, and if no error then HTTP STATUS equal 200
{
"status":1,
"status_t":"Task created",
"data":{
"task_id":"CW0sIiUpL92N" // New task ID
}
}
Examples:
Check file "file_to_check.exe" for all available engines:
POST
/vhm/api/v1/check/new/
apikey |
55de2e769181d9259fc0bc96ab6e34c55ba8b909 |
file |
@C:\file_to_check.exe |
Check domain
POST
/vhm/api/v1/check/new/
apikey |
55de2e769181d9259fc0bc96ab6e34c55ba8b909 |
task_type |
domain |
url |
google.com |