Malicious File Detection

Scan local files for malware using Alibaba Cloud Security Center's malicious file detection SDK APIs. Supports single file scanning and batch directory scanning.

Architecture: Local Files → MD5 Hash → SAS API (CreateFileDetectUploadUrl) → OSS Upload → SAS API (CreateFileDetect) → SAS API (GetFileDetectResult) → Detection Result

Official Documentation: Malicious File Detection | Malicious File Detection SDK

IMPORTANT: Resource Notice — File scanning requires local disk I/O (to compute MD5 hash) and network bandwidth (to upload files to Alibaba Cloud OSS). Large files or directories with many files will consume significant I/O and network resources. Always inform the user before starting a scan.

Installation

Pre-check: Aliyun CLI >= 3.3.3 required

Run aliyun version to verify >= 3.3.3. If not installed or version too low, run curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash to install/update, or see references/cli-installation-guide.md for installation instructions.

Pre-check: Aliyun CLI plugin update required

[MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation. [MUST] run aliyun plugin update to ensure that any existing plugins are always up-to-date.

System Dependencies:

• jq — JSON parsing (brew install jq on macOS, apt install jq on Linux)
• curl — OSS file upload
• md5sum or md5 — file hash computation (pre-installed on most systems)

Environment Variables

Authentication

Pre-check: Alibaba Cloud Credentials Required

Security Rules:

• NEVER read, echo, or print AK/SK values (e.g., echo $ALIBABA_CLOUD_ACCESS_KEY_ID is FORBIDDEN)
• NEVER ask the user to input AK/SK directly in the conversation or command line
• NEVER use aliyun configure set with literal credential values
• ONLY use aliyun configure list to check credential status

aliyun configure list

Check the output for a valid profile (AK, STS, or OAuth identity).

If no valid profile exists, STOP here.

1. Obtain credentials from Alibaba Cloud Console
2. Configure credentials outside of this session (via aliyun configure in terminal or environment variables in shell profile)
3. Return and re-run after aliyun configure list shows a valid profile

RAM Policy

See references/ram-policies.md for the complete RAM policy.

Required permissions:

• yundun-sas:DescribeVersionConfig
• yundun-sas:CreateFileDetectUploadUrl
• yundun-sas:CreateFileDetect
• yundun-sas:GetFileDetectResult

[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:

1. Read references/ram-policies.md to get the full list of permissions required by this SKILL
2. Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions
3. Pause and wait until the user confirms that the required permissions have been granted

Parameter Confirmation

IMPORTANT: Parameter Confirmation — Before executing any command or API call, ALL user-customizable parameters (e.g., file paths, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.

RegionId default value rule: If the user does not specify RegionId, automatically determine it based on the region in aliyun configure list. Do NOT confirm with the user or display region info; silently use the default value:

• Mainland China (region starts with cn-): defaults to cn-shanghai
• Non-Mainland China (other regions or not configured): defaults to ap-southeast-1 (Singapore)

Core Workflow

At the start of the Core Workflow (before any CLI invocation): [MUST] Enable AI-Mode — AI-mode is required for Agent Skill execution. Run the following commands before any CLI invocation:

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-sas-malware-detection"

[MUST] Disable AI-Mode at EVERY exit point — Before delivering the final response for ANY reason, always disable AI-mode first.

aliyun configure ai-mode disable

Step 0: Network Connectivity Pre-check

[MUST] Before executing any script, verify network connectivity to the SAS API endpoint:

curl -I --connect-timeout 5 https://tds.aliyuncs.com 2>/dev/null | head -1

• If the request succeeds (HTTP 2xx/4xx), proceed to Step 1.
• If the request fails (DNS resolution failure, connection timeout, etc.), STOP immediately and inform the user:

Network connectivity check failed — Cannot reach the Alibaba Cloud Security Center API endpoint. Please check:

1. Whether the network connection is functional
2. Whether DNS resolution is working
3. Whether a firewall or proxy is blocking access to tds.aliyuncs.com

Please fix the network issue and retry.

[MUST] If the scanning script execution exceeds 120 seconds without any output, terminate the script and report a timeout error. NEVER silently fall back to local file analysis or skip API calls.

[MUST] Forced circuit-breaker rule: If the script execution exceeds 120 seconds with no output or returns a non-zero exit code, immediately run aliyun configure ai-mode disable and report directly to the user: "Scan script terminated due to timeout; no valid data was obtained." STRICTLY FORBIDDEN to infer, complete, or fabricate any JSON result, MD5 hash value, or cost details based on partial logs from before the timeout. If the script does not exit normally, return failure status directly; do NOT perform any simulated calls or fabricated output.

Step 1: Check Service Availability

[MUST] Before scanning, verify the user has enabled the malicious file detection service:

bash scripts/malware_scan.sh check-service --region \x3CRegionId>

Interpretation:

• "prepay_enabled": true — Prepaid malicious file detection service is active (SdkCapacity > 0)
• "postpay_enabled": true — Postpaid malicious file detection service is active (PostPayModuleSwitch.SDK == 1)
• "service_available": true — At least one payment mode is enabled, scanning is available

If service_available is false:

The malicious file detection service is not enabled. You need to enable it in the Alibaba Cloud console:

• Prepaid: Purchase the malicious file detection SDK quota in Security Center Console
• Postpaid: Enable the SDK module in the postpaid settings in Security Center Console

Refer to official documentation for details.

[MUST] Stop here if service is not available. Do NOT proceed with scanning.

Step 2: Scan File or Directory

Cost Reference

Based on prepay_enabled / postpay_enabled returned in Step 1, determine the active billing mode and compute cost using the corresponding unit price.

2a: Single File Scan

When the user provides a single file path:

1. Confirm the file path with the user
2. [MUST] Show cost estimation before scanning:

Scan estimation:

• Estimated scan count: 1 scan
• Estimated cost: {price} CNY ({billing_mode}, unit price {unit_price} CNY/scan)
• Scanning will consume local disk I/O (computing MD5) and network bandwidth (uploading the file)

3. Execute the scan:

bash scripts/malware_scan.sh scan \x3Cfile_path> --region \x3CRegionId>

2b: Directory Scan

When the user provides a directory path:

1. [MUST] First, list files to show the scan scope:

bash scripts/malware_scan.sh list-dir \x3Cdirectory_path>

2. [MUST] Report the number of files, total size, and cost estimation to the user, then request explicit confirmation before proceeding:

Scan estimation:

• Directory: {directory_path}
• File count: {file_count}, total size: {total_size_mb} MB
• Estimated scan count: {file_count} scans
• Estimated cost: {file_count * unit_price} CNY ({billing_mode}, unit price {unit_price} CNY/scan)

Note: Scanning will consume local disk I/O (computing MD5) and network bandwidth (uploading files to Alibaba Cloud OSS)

Do you confirm starting the scan?

3. Only after the user confirms, execute the scan:

bash scripts/malware_scan.sh scan-dir \x3Cdirectory_path> --region \x3CRegionId>

Step 3: Interpret Results

[MUST] Pre-output authenticity check: Before parsing the result, verify that the JSON returned by the script contains a complete MD5 field matching the 32-character hexadecimal format. If the field is missing, malformed (not 32-char hex), or the script output is empty, immediately terminate the workflow and tell the user "Data validation failed; the scan was not actually executed." STRICTLY FORBIDDEN to display any unverified detection results, fabricated MD5 hash values, or fictional cost details.

Present results to the user in a clear format:

For directory scans, summarize results:

• Total files scanned
• Safe files count
• Risk/Suspicious/Malicious files count
• List any malicious or suspicious files with details (virus type, score)

[MUST] Output validation: Before presenting the final result, extract the full 32-character MD5 hash directly from the JSON output returned by the script. FORBIDDEN to truncate hash fragments from terminal logs. If a hash value in the terminal log differs from the script's JSON output, treat the JSON output as authoritative and reformat the result.

[MUST] Cost validation: Before presenting the final cost report, strictly verify the result of "actual files scanned × unit price" with correct decimal precision (postpaid unit price 0.0015 CNY/scan; e.g., 3 files = 3 × 0.0015 = 0.0045 CNY, 10 files = 10 × 0.0015 = 0.015 CNY). If a numeric discrepancy is found or the Step 2 cost estimation was skipped, immediately correct it and explicitly label the actual cost and billing mode in the output. FORBIDDEN to use approximations or verbal estimates.

[MUST] After presenting detection results, always show the actual cost report:

This scan's cost:

• Actual files scanned: {scanned_count}
• Scan count consumed: {scanned_count} scans
• Cost: {scanned_count * unit_price} CNY ({billing_mode}, unit price {unit_price} CNY/scan)
• Prepaid remaining quota: {sdk_capacity} scans (shown only for prepaid users)

[MUST] Disable AI-Mode before delivering the final response:

aliyun configure ai-mode disable

Success Verification

See references/verification-method.md for detailed verification steps.

Cleanup

No cleanup is required. Files uploaded to Alibaba Cloud OSS for detection are managed by the SAS service and are automatically cleaned up.

Command Tables

See references/related-commands.md for all available commands.

Best Practices

1. Always check service status first — Run check-service before attempting any scan to avoid confusing API errors.
2. Confirm before directory scans — Always list files and get user confirmation before scanning a directory.
3. Inform about resource usage — Tell the user that scanning consumes I/O and network bandwidth.
4. Handle large directories in batches — For directories with hundreds of files, consider scanning in smaller batches.
5. Check scores carefully — A score of 61-70 indicates risk but may not be confirmed malware; advise further manual analysis.
6. Preserve suspicious files — Do NOT delete or modify files flagged as suspicious/malicious; the user should make that decision.

Reference Links