GetFileDetectResult-阿里云帮助中心

Retrieves file detection results in batches using HashKey values.

Operation description

You can retrieve detection results only for submitted files. Results are retained for 5 hours and can be queried multiple times during this period. To submit a file for detection, call the CreateFileDetect operation.

Unique file identifier

All file detection operations use the HashKey parameter. HashKey is a unique file identifier used to query the corresponding file detection result.

For Skill compressed package detection (when Type is 6), obtain the HashKey from the response of the CreateFileDetect operation.

For malicious file detection (when Type is 0), the HashKey must be the MD5 or SHA-256 hash of the entire file.

Query detection results

In a malicious file detection scenario (when Type is 0), you can filter files by their attributes using the FileLabel field in the Ext field. For example, you can combine the encrypted and Zip attributes to filter for encrypted compressed packages. Supported file tags for compressed packages include: Zip, RAR, 7-Zip, XAR, ZLib, GZip, and tar. You can also use the Highlight field in the Ext field to locate malicious code segments in WebShell files. The Highlight field is a list in which each element represents a code range. The numbers indicate the character offset from the beginning of the file.

In a Skill compressed package detection scenario (when Type is 6), you can retrieve the detection report from the Ext field. This report includes results from deep intent analysis, prompt injection detection, sensitive information recognition, and malicious script detection. To query the details of an individual file within the compressed package, call the ListCompressFileDetectResult operation.

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	An array of up to 100 unique file identifiers.
	string	No	The unique file identifier.	0a212417e65c26ff133cfff28f9c****
Type	integer	Yes	The type of file to detect. Valid values: 0: malicious file detection 6: Skill compressed package detection	0

Response elements

Element	Type	Description	Example
	object	The response object.
RequestId	string	The unique ID of the request, generated by Alibaba Cloud. Use this ID to troubleshoot issues.	24A20733-10A0-4AF6-BE6B-E3322413BB68
ResultList	array<object>	An array of file detection result objects.
	object	A file detection result object.
HashKey	string	The unique file identifier.	0a212417e65c26ff133cfff28f6c****
Result	integer	The file detection result. Valid values: 0: Safe file 1: Suspicious file 3: Detection in progress.	0
Score	integer	The file's detection score. The score ranges and their corresponding risk levels are as follows: 0–60: Safe 61–70: Risk 71–80: Suspicious 81–100: Malicious Important A higher score indicates a higher level of suspicion.	100
VirusType	string	The type of virus. Valid values: Trojan: Trojan horse WebShell: Webshell Backdoor: Backdoor RansomWare: Ransomware Scanner: Scanner Stealer: Information stealer Malbaseware: Contaminated basic software Hacktool: Hacking tool Engtest: Engine test program Downloader: Trojan downloader Virus: Virus Miner: Mining program Worm: Worm DDoS: DDoS Trojan Malware: Malicious program RiskWare: Riskware Proxytool: Proxy tool Suspicious: Suspicious program MalScript: Malicious script Rootkit: Rootkit Exploit: Exploit Note This parameter is not returned when `Result` is `0` or `3`.	WebShell
Code	string	The result code. A value of 200 indicates success. Other values indicate an error. Use this code to determine the cause of the error.	200
Message	string	The detailed message returned.	successful
Ext	string	The extension field, which provides additional details about the detection result.	{ "HighLight": [ [ 23245, 23212 ] ], "FileLabel": [ "PE32", "Zip", "SFX", "encrypted" ] }
Compress	boolean	Indicates whether the file is identified as a compressed package. true: The file is a compressed package. false: The file is not a compressed package. Note This parameter is not returned when `Type` is `6`.	false

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.