Alibabacloud Sas Malware Detection

SKILL.md

---
name: alibabacloud-sas-malware-detection
description: |
  Alibaba Cloud Security Center (SAS) malicious file detection skill.
  Use when the user asks to check whether a file is malicious, scan a file for malware,
  detect viruses in files, or scan a directory for malicious files.
  Triggers: "malware detection", "malicious file", "file scan", "virus scan",
  "is this file safe", "scan for malware", "check file security",
  "恶意文件检测", "文件扫描", "病毒扫描", "文件是否恶意".
---

# 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](https://help.aliyun.com/zh/security-center/user-guide/detect-malicious-files) | [Malicious File Detection SDK](https://help.aliyun.com/zh/security-center/user-guide/sdk-for-malicious-file-detection)

> **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

| Variable | Required | Description |
|----------|----------|-------------|
| `ALIBABA_CLOUD_ACCESS_KEY_ID` | Yes (if no CLI profile) | Alibaba Cloud Access Key ID |
| `ALIBABA_CLOUD_ACCESS_KEY_SECRET` | Yes (if no CLI profile) | Alibaba Cloud Access Key Secret |

---

## 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
>
> ```bash
> 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](https://ram.console.aliyun.com/manage/ak)
> 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](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.

| Parameter | Required | Description | Default |
|-----------|----------|-------------|---------|
| File/Directory Path | Yes | Path to the file or directory to scan | None |
| RegionId | No | Alibaba Cloud region for API endpoint | See rule below |

**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:
> ```bash
> 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.
> ```bash
> aliyun configure ai-mode disable
> ```

### Step 0: Network Connectivity Pre-check

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

```bash
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
bash scripts/malware_scan.sh check-service --region <RegionId>
```

**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](https://yundun.console.aliyun.com/?p=sas)
> - **Postpaid**: Enable the SDK module in the postpaid settings in [Security Center Console](https://yundun.console.aliyun.com/?p=sas)
>
> Refer to [official documentation](https://help.aliyun.com/zh/security-center/user-guide/detect-malicious-files) for details.

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

### Step 2: Scan File or Directory

#### Cost Reference

| Billing Mode | Unit Price | Settlement Cycle | Notes |
|--------------|------------|------------------|-------|
| Prepaid | 0.001 CNY/scan/month | Monthly | 100,000 scans minimum |
| Postpaid | 0.0015 CNY/scan | Per calendar day | Based on actual scan count |

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
bash scripts/malware_scan.sh scan <file_path> --region <RegionId>
```

#### 2b: Directory Scan

When the user provides a directory path:

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

```bash
bash scripts/malware_scan.sh list-dir <directory_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
bash scripts/malware_scan.sh scan-dir <directory_path> --region <RegionId>
```

### 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:

| Score Range | Risk Level | Description |
|-------------|------------|-------------|
| 0-60 | Safe | File is safe |
| 61-70 | Risk | File has some risk indicators |
| 71-80 | Suspicious | File is suspicious, further analysis recommended |
| 81-100 | Malicious | File is highly likely malicious |

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:
> ```bash
> aliyun configure ai-mode disable
> ```

---

## Success Verification

See [references/verification-method.md](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](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

| Reference | Description |
|-----------|-------------|
| [references/ram-policies.md](references/ram-policies.md) | RAM permission policy for all APIs |
| [references/related-commands.md](references/related-commands.md) | CLI/SDK commands and script usage |
| [references/verification-method.md](references/verification-method.md) | Steps to verify successful execution |
| [references/acceptance-criteria.md](references/acceptance-criteria.md) | Correct/incorrect code patterns |
| [references/cli-installation-guide.md](references/cli-installation-guide.md) | Aliyun CLI installation guide |
| [Official: Malicious File Detection](https://help.aliyun.com/zh/security-center/user-guide/detect-malicious-files) | Product documentation |
| [Official: SDK Guide](https://help.aliyun.com/zh/security-center/user-guide/sdk-for-malicious-file-detection) | SDK usage documentation |