POST-Virus Scan
Introduces how to call the interface to perform virus scanning on text content.
Interface Introduction
The Virus Scan interface is used to send content for virus-related security reviews.
Request method
POST
URL
Interface URL
/skg/v1/swg/antivirus/<mode>Request Parameters
| Parameter Name | Parameter Location | Required | Description |
|---|---|---|---|
| <mode> | URL Parameter | Yes | Call mode.
|
| <text request mode> | URL Parameter | Yes | Specifies whether the text content request mode is synchronous or asynchronous. |
Metadata Parameters
Supports scanning of text content
Metadata parameter definitions
| Parameter Name | Type | Applicable Status | Description |
|---|---|---|---|
| queryID | String (Required) | Synchronous and asynchronous | The event query ID associated with this request, must be unique. If no event is generated for the request, the event details cannot be queried. Note: The value of queryid corresponds to the traffic UUID in the third-party cloud service. |
| filename | String (Optional) | Synchronous | File name - can be used for policy matching based on the file name |
| md5 | String (Optional) | Synchronous and asynchronous | File MD5 value, used for recording and caching to speed up the process. Supports sending MD5 together with the document for inspection, as well as sending only the MD5 for inspection. |
| uploadtype | String (Required) | Asynchronous | Only for asynchronous mode. Supports cloud storage such as AWS S3, Alibaba Cloud OSS, Tencent Cloud COS, Swift, as well as local files and download URLs.
|
| callback_url | String (Optional) | Asynchronous | Only for asynchronous mode, fill in the callback function URL |
| objectInfo |
Dict (Optional) |
Asynchronous | Only for asynchronous mode when using object storage. Refer to the table below for specific parameter configurations of objectInfo |
| Parameter | Type | Description |
| The following parameters are applied to s3 (aws) | ||
| s3Region | String(Optional) | In the case of using s3 region name, if it is running on EC2 and AWS IAM role is used, the following three items can be omitted |
| accessKey | String(Optional) | access key in s3 |
| secretKey | String(Optional) | secret key in s3 |
| endpointUrl | String(Optional) | endpoint URL in s3 |
| s3Bucket | String(Optional) | object bucket in s3 |
| s3Key | String(Mandatory) | object key (file name) in s3 |
|
The following parameters are applied to swift (Openstack) |
||
|
X-Auth-Token |
String(Optional) | The authentication token when using swift. If a valid X-Auth-Token is provided, the following three items can be omitted |
|
authUrl |
String(Optional) | Authentication URL in Swift |
| X-Auth-User | String(Optional) | Authentication urser in Swift |
| X-Auth-Key | String(Optional) | Authentication key (password) in Swift |
| objectUrl | String(Mandatory) | Complete object access path in Swift |
|
The following parameters are applied to oss (Aliyun) |
||
|
ossEndpoint |
String(Optional) |
value of endpoint |
|
accessKeyId |
String(Optional) |
value of accessKeyId |
|
accessKeySecret |
String(Optional) |
value of accessKeySecret |
|
ossBucket |
String(Mandatory) |
object bucket |
|
ossKey |
String(Mandatory) |
object key (file name) |
|
The following parameters are applied to cos (Tencent cloud) |
||
|
cosRegion |
String(Mandatory) |
value of region name |
|
secretId |
String(Mandatory) |
value of secretId |
|
secretKey |
String(Mandatory) |
value of secretKey |
|
cosBucket |
String(Mandatory) |
object bucket |
|
cosKey |
String(Mandatory) |
object key (file name) |
Python Request Example - Virus Scan (Synchronous Mode)
# -*- coding: utf-8 -*-
from requests.packages.urllib3.exceptions import InsecureRequestWarning
from ucwi_config import UCWIConfig
from ucwi_auth import get_headers
import requests
import json
import uuid
requests.packages.urllib3.disable_warnings(InsecureRequestWarning)
api = "/skg/v1/swg/antivirus/sync"
url = "{0}{1}".format(UCWIConfig.base_url, api)
file_path = "test.txt"
metadata = {
# The ID associated with this request, must be unique, used for event queries in asynchronous mode
"queryID": str(uuid.uuid4()),
}
headers = get_headers()
data = {"metadata": json.dumps(metadata)}
fd = open(file_path)
files = {
"request": fd
}
response = requests.post(url, headers=headers, data=data, files=files, verify=False)
fd.close()
if response.status_code != 200:
print("Bad request, response code:", response.status_code)
print(response.text)
else:
result = response.json()
if result["responseCode"] != 200:
print("Bad request, response code:", result["responseCode"])
print(result["message"])
else:
if result["hasVirus"]:
print(" virus info:")
for info in result["virus_info"]:
print(json.dumps(info, indent=2).encode('utf-8').decode('raw_unicode_escape'))
else:
print("no virus.")
Python Request Example - Virus Scan (Asynchronous Mode)
The following example demonstrates using Python code to call the interface to perform a virus scan on file content in asynchronous mode.
Note: In the following Python code example, the imported header files ucwi_config and ucwi_auth need to be created beforehand. For detailed reference examples, see Header File Examples.
# -*- coding: utf-8 -*-
from requests.packages.urllib3.exceptions import InsecureRequestWarning
from ucwi_config import UCWIConfig
from ucwi_auth import get_headers
import requests
import json
import uuid
requests.packages.urllib3.disable_warnings(InsecureRequestWarning)
api = "/skg/v1/swg/antivirus/async"
url = "{0}{1}".format(UCWIConfig.base_url, api)
file_path = "test.txt"
metadata = {
"queryID": str(uuid.uuid4()),
# The UUID associated with this request, must be unique, used for event queries in asynchronous mode
"uploadtype": "file",
"callback_url": UCWIConfig.callback_url + "/virus"
}
headers = get_headers()
data = {"metadata": json.dumps(metadata)}
fd = open(file_path)
files = {
"request": fd
}
response = requests.post(url, headers=headers, data=data, files=files, verify=False)
fd.close()
if response.status_code != 200:
print("Bad request, response code:", response.status_code)
print(response.text)
else:
result = response.json()
print(result["message"])
Return Parameters
| Name | Description |
|---|---|
| hasVirus | If the return value is True, it means a virus was detected. If no virus is found, the return value is false. |
| queryID | The event query ID associated with this request, must be unique. If no event is generated for the request, the event details cannot be queried. |
| result | Scan result |
| responseCode | The returned status code |
| localDetectedTime | Local detection event |
| virus_info.VirusName | Virus name |
| virus_info.VirusType | Virus type |
| virus_info.VirusID | Virus ID |
| virus_info.VirusDesc | Virus description |
Return Example
{
"hasVirus": true, // If no virus is found, this is displayed as false
"queryID": "5f08ec98-c948-4e71-b85a-f564e7081572",
"result": 0,
"responseCode": 200,
"localDetectedTime": "2020-02-12T16:10:09.673582",
"virus_info": [ // If no virus is found, this is displayed as an empty value []
{
"VirusName": "HEUR/AGEN.1044737",
"VirusType": "heuristic",
"VirusID": 0,
"VirusDesc": "Contains suspicious code HEUR/AGEN.1044737"
}
]
}