Obtain file detection results by calling GetFileDetectResult - Security Center - Alibaba Cloud - Security Center

Retrieves file detection results in batches by HashKey.

Operation description

You can retrieve detection results only for files that have been submitted for detection. Detection results are retained for 5 hours and can be queried repeatedly within this period. To submit files for detection, refer to CreateFileDetect.

File unique identifier

All file detection-related operations include the HashKey parameter, which represents the unique identifier of the file being detected and is used to query detection results. Only the MD5 or SHA-256 hash of the complete file content is supported.

Query detection results

You can filter file properties by using the FileLabel field in the Ext extension field. For example, you can combine the encrypted and Zip properties to filter encrypted archives. Supported file labels for compressed file types: Zip, RAR, 7-Zip, XAR, ZLib, GZip, and tar. You can use the Highlight field in the Ext extension field to locate malicious code segments in web shell files. The Highlight field is a list type. Each element in the list corresponds to a code range, and the numbers represent the offset in characters from the beginning of the file.

Before querying file detection results, complete the following steps in order:

Call CreateFileDetectUploadUrl to obtain OSS upload parameters.
Use the returned signature information to upload the file to OSS by using a form. For more information about the upload method, see OSS PostObject form upload documentation.
Call CreateFileDetect to submit a file detection task.
Call GetFileDetectResult to query the detection result.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

yundun-sas:GetFileDetectResult

get

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
SourceIp	string	No	The source IP address of the request.	183.46.XX.XX
HashKeyList	array	Yes	The list of file identifiers. A maximum of 200 elements can be specified.
	string	No	The unique identifier of the file.	0a212417e65c26ff133cfff28f9c****
Type	integer	Yes	The type of file to detect. Valid values: 0: malicious file detection	0

Response elements

Element	Type	Description	Example
	object	The response parameters.
RequestId	string	The request ID, which is a unique identifier generated by Alibaba Cloud for this request. You can use it to troubleshoot issues.	24A20733-10A0-4AF6-BE6B-E3322413BB68
ResultList	array<object>	The list of detection results.
	object	The file detection result information.
HashKey	string	The file identifier.	0a212417e65c26ff133cfff28f6c****
Result	integer	The file detection result. Valid values: 0: Safe file. 1: Suspicious file. 3: Detection in progress. Wait for the detection to complete.	0
Score	integer	The file detection score. The mapping between score ranges and risk levels is as follows: 0–60: Safe. 61–70: Risky. 71–80: Suspicious. 81–100: Malicious. Important A higher score indicates a more suspicious file. This field is returned only when Result is 1 (suspicious file). This field is not returned when Result is 0 or 3.	100
VirusType	string	The virus type. Valid values: Trojan: Trojan. WebShell: Web shell. Backdoor: Backdoor. RansomWare: Ransomware. Scanner: Scanner. Stealer: Credential stealer. Malbaseware: Contaminated base software. Hacktool: Hacking tool. Engtest: DPI engine test program. Downloader: Downloader Trojan. Virus: File infector virus. Miner: Mining programs. Worm: Worms. DDoS: DDoS Trojan. Malware: Malware. RiskWare: Riskware. Proxytool: Proxy tool. Suspicious: Suspicious program. MalScript: Malicious script. Rootkit: Rootkit. Exploit: Vulnerability exploits. Note This parameter is not supported when Result is 0 or 3. This field is returned only when Result is 1 (suspicious file). This field is not returned when Result is 0 or 3.	WebShell
Code	string	The result code. A value of 200 indicates success. Any other value indicates failure. You can use this field to determine the cause of the failure.	200
Message	string	The detailed information about the error code.	successful
Ext	string	The extended information of the detection result.	{ "HighLight": [ [ 23245, 23212 ] ], "FileLabel": [ "PE32", "Zip", "SFX", "encrypted" ] }
Compress	boolean	Indicates whether the file is identified as a compressed archive. true: Yes. false: No. Note This parameter is not supported when Type is 6.	false

The following example shows a single result in the detection result list. Other response fields are omitted.

Safe file (Result is 0). Score and VirusType are not returned:

{"Result": 0}

Suspicious file (Result is 1). Score and VirusType are returned:

{"Result": 1, "Score": 100, "VirusType": "WebShell"}

Examples

Success response

JSON format

{
  "RequestId": "24A20733-10A0-4AF6-BE6B-E3322413BB68",
  "ResultList": [
    {
      "HashKey": "0a212417e65c26ff133cfff28f6c****",
      "Result": 0,
      "Score": 100,
      "VirusType": "WebShell",
      "Code": "200",
      "Message": "successful",
      "Ext": "{\n    \"HighLight\":\n    [\n        [\n            23245,\n            23212\n        ]\n    ],\n    \"FileLabel\":\n    [\n        \"PE32\",\n        \"Zip\",\n        \"SFX\",\n        \"encrypted\"\n    ]\n}",
      "Compress": false
    }
  ]
}

Error codes

HTTP status code	Error code	Error message	Description
400	RequestTooFrequently	Request too frequently, please try again later
400	GetResultFail	Get result fail, found no detect record for this file or result has been expired
400	InvalidApiDetectType	Unsupported Api Detect Type.	The file type is not supported.
500	ServerError	ServerError
500	SystemBusy	System busy, please try again later.
403	NoPermission	caller has no permission	You are not authorized to do this operation.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.