--- name: alibabacloud-sas-install-agent description: > Alibaba Cloud Security Center (SAS) agent onboarding and management assistant. Use this skill when the user wants to onboard servers to Security Center, install the security agent, deploy cloud security protection, connect via proxy, troubleshoot agent offline or installation failures, create image templates with pre-installed agent, view Security Center version and expiration, check authorization quota, upgrade or switch server protection versions, toggle pay-as-you-go feature modules, uninstall the Security Center agent from a server, find servers with specific software installed (e.g. Nginx, MySQL, Redis), or detect security risks (vulnerability scanning, baseline checks, security alert queries). --- # Security Center Agent Onboarding and Management Manage Alibaba Cloud Security Center agent installation, version authorization, asset queries, and security risk detection via the `aliyun` CLI. **Architecture**: `Security Center (SAS) + ECS + Cloud Assistant + Proxy Cluster (optional)` Execution model: read operations execute directly (ReAct), write operations display details and require user confirmation before execution (Command). Keep analysis concise -- output a brief reasoning for each action. > **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. > Then [MUST] run `aliyun configure set --auto-plugin-install true` to enable automatic plugin installation. > Then [MUST] run `aliyun plugin update` to ensure that any existing plugins on your local machine are always up-to-date. > **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 ## Security Guidelines - Never expose sensitive information (AccessKey, passwords) in output, because leaking credentials could compromise the account - Never call any Delete-class API, because delete operations are irreversible and may disrupt protection - Write operations (create install codes, create clusters, install proxies, run commands via cloud assistant, bind authorization, modify switches) must display operation details and wait for user confirmation before execution, because these operations modify live resources - Display the full command content before dispatching commands via cloud assistant, because executing arbitrary commands on production servers is high-risk ## RAM Policy Detailed permissions required by this skill: `references/ram-policies.md` > **[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 > **IMPORTANT: Parameter Confirmation** — Before executing any command or API call, > ALL user-customizable parameters (e.g., RegionId, instance names, CIDR blocks, > passwords, domain names, resource specifications, etc.) MUST be confirmed with the > user. Do NOT assume or use default values without explicit user approval. 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-install-agent" ``` **[MUST] Disable AI-Mode at EVERY exit point** — Before delivering the final response for ANY reason, always disable AI-mode first. This applies to ALL exit paths: workflow success, workflow failure, error/exception, user cancellation, session end, or any other scenario where no further CLI commands will be executed. AI-mode is only used for Agent Skill invocation scenarios and MUST NOT remain enabled after the skill stops running. ```bash aliyun configure ai-mode disable ``` --- ## Tool Inventory All APIs are invoked via the `aliyun` CLI. Every `aliyun` command MUST include `--user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent`. | CLI Command | Purpose | |-------------|---------| | `aliyun sas describe-cloud-center-instances` | Query server client status by instance ID/IP | | `aliyun ecs describe-instances` | Query ECS instance info and running status | | `aliyun ecs describe-cloud-assistant-status` | Check if cloud assistant is online | | `aliyun ecs run-command` | Remote install command execution (write) | | `aliyun ecs invoke-command` | Trigger existing command on instances (write) | | `aliyun ecs describe-invocation-results` | Query command execution results | | `aliyun sas refresh-assets` | Sync latest asset data | | `aliyun sas describe-install-codes` | Get existing install code list | | `aliyun sas add-install-code` | Generate new install code (write) | | `aliyun sas create-or-update-asset-group` | Create or update asset group (write) | | `aliyun sas get-auth-summary` | Get authorization quota and usage per version | | `aliyun sas describe-version-config` | Get version, feature modules, expiration | | `aliyun sas get-serverless-auth-summary` | Get pay-as-you-go serverless status | | `aliyun sas modify-post-pay-module-switch` | Toggle pay-as-you-go module switches (write) | | `aliyun sas bind-auth-to-machine` | Bind/unbind authorization version (write) | | `aliyun sas update-post-paid-bind-rel` | Change pay-as-you-go version binding or downgrade to free version (write) | | `aliyun sas describe-property-sca-detail` | Query software info on servers | | `aliyun sas add-uninstall-clients-by-uuids` | Uninstall agent from specified servers (write) | | `aliyun sas modify-push-all-task` | Dispatch security check tasks to servers (write) — use this for targeted single-server scans | | `aliyun sas modify-start-vul-scan` | Trigger global full-scan across ALL servers (write) — NEVER use for targeted single-server scans | | `aliyun sas describe-grouped-vul` | Query grouped vulnerability statistics | | `aliyun sas exec-strategy` | Execute baseline check strategy (write) | | `aliyun sas describe-strategy` | Query baseline check strategy list | | `aliyun sas list-check-item-warning-summary` | Get baseline check risk statistics | | `aliyun sas describe-susp-events` | Query security alert events | | `aliyun sas generate-once-task` | Trigger full asset fingerprint collection (write) | | `aliyun sas create-asset-selection-config` | Create virus scan asset selection (write) | | `aliyun sas add-asset-selection-criteria` | Add assets to selection config (write) | | `aliyun sas update-selection-key-by-type` | Associate selection to virus scan (write) | | `aliyun sas create-virus-scan-once-task` | Create one-time virus scan task (write) | | `aliyun sas get-virus-scan-latest-task-statistic` | Query latest virus scan task stats | | `aliyun sas list-virus-scan-machine` | Query machines involved in virus scan | | `aliyun sas list-virus-scan-machine-event` | Query virus events on a specific machine | | `aliyun sas describe-once-task` | Poll vulnerability scan task progress | > Detailed API parameters: `references/api-reference.md`. RAM permissions: `references/ram-policies.md`. Full command list: `references/related-commands.md`. --- ## Common Flow: Get or Create Install Code When any installation scenario requires an install code, follow this unified flow. **Step 1: Query existing install codes** ```bash aliyun sas describe-install-codes --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Display as table: install code, OS, vendor, group, image flag, expiration. **Step 2: Ask user to choose** User can select an existing matching unexpired code, or request a new one. **Step 3: Confirm new install code config (creation only)** | Config | Parameter | Notes | |--------|-----------|-------| | OS | `--os` | linux or windows | | Vendor | `--vendor-name` | Determined by network access method (see below) | | Asset Group | `--group-id` | Target group; create via create-or-update-asset-group if needed | | Expiration | `--expired-date` | 13-digit timestamp; defaults if omitted | | Image Install | `--only-image` | Whether for image template creation | **VendorName and network access method mapping:** The vendor parameter determines the connection domain used by the install command. Using the wrong value causes the agent to fail connecting to the server: | Network Access | VendorName | Reason | |---------------|-----------|--------| | Direct line (leased line) | **ALIYUN** | Uses internal domain jsrv2.aegis.aliyun.com | | Public network (Alibaba Cloud ECS) | **ALIYUN** | ECS uses internal network | | Public network (third-party cloud/IDC) | **OTHER** | Uses public domain jsrv.aegis.aliyun.com | > When the scenario already identifies the network access method, auto-fill VendorName without asking the user. After confirmation, execute creation (pass only user-specified parameters). This is a write operation requiring confirmation. **Step 4: Get install command** After creation, re-query the install code list to get the new CaptchaCode for building the install command. --- ## Scenario Routing ### Scenario 0: Initial Consultation **Trigger**: User vaguely says "onboard to Security Center", "install security agent", "deploy cloud security". **Strategy**: Do not call any tools. Collect information through questions, then route: 1. **Server type**: - Alibaba Cloud ECS -> Scenario 1 - Third-party cloud / On-premises IDC -> Continue to question 2 2. **Network access method**: - Public or leased-line direct -> Scenario 2 3. **Image deployment** -> Scenario 3 --- ### Scenario 1: Alibaba Cloud ECS Onboarding **Trigger**: User confirms the server is an Alibaba Cloud ECS instance. **Summary**: 1. Get ECS info, query instance and client status 2. Based on ClientStatus + ClientSubStatus: online = no action needed, uninstalled = install, offline = troubleshoot 3. Get or create install code (common flow) 4. If cloud assistant is online, dispatch remotely; otherwise provide manual install command 5. Verify onboarding > Detailed steps and CLI commands: `references/install-scenarios.md#scenario-1-alibaba-cloud-ecs-onboarding` --- ### Scenario 2: On-Premises IDC Direct Connection (Public/Leased Line) **Trigger**: On-premises IDC or third-party cloud server with public or leased-line connectivity. **Summary**: 1. Get or create install code (common flow, VendorName auto-determined by network type) 2. Select install command based on network situation (public/leased-line/overseas), refer to `references/agent-install-guide.md` 3. Verify onboarding > Detailed steps: `references/install-scenarios.md#scenario-2-on-premises-idc-direct-connection` --- ### Scenario 3: Image-Based Batch Installation **Trigger**: User mentions image deployment, batch server creation with pre-installed agent, template creation. **Summary**: 1. Confirm template server info, remind about clean environment requirement 2. Get or create image-specific install code (OnlyImage=true) 3. Provide install command; emphasize: after execution, only shutdown is allowed -- restarting activates the agent and occupies the UUID 4. Warn about UUID conflict risk: every image creation requires repeating this process 5. Verify new instance onboarding > Detailed steps and caveats: `references/install-scenarios.md#scenario-3-image-based-batch-installation` --- ### Scenario 4: Network Troubleshooting **Trigger**: User reports installation failure, agent offline, or connection issues. **Strategy**: Do not call tools; provide troubleshooting guidance directly: - Confirm required domains and ports (public: jsrv.aegis.aliyun.com:80, leased-line: jsrv2.aegis.aliyun.com:80) - Provide network connectivity test commands - Common cause analysis (firewall, DNS, no public network) > Detailed troubleshooting steps: `references/install-scenarios.md#scenario-4-network-troubleshooting` --- ### Scenario 5: Query Version and Feature Info **Trigger**: User wants to know about **account-level** version, authorization quota, enabled features, or pay-as-you-go status. > **[MUST] Routing distinction**: Scenario 5 is for **account-level** queries ("我们的版本是什么", "配额还剩多少", "过期时间"). When the user asks about **specific servers** ("哪些服务器未授权", "哪些机器是免费版", "未绑定付费版本的服务器"), route to `describe-cloud-center-instances` with AuthVersion filter instead — this is an asset query, NOT a version query. **Summary**: 1. Query version details (describe-version-config) 2. Query authorization usage (get-auth-summary) 3. Optionally query Serverless status (get-serverless-auth-summary) 4. Optionally modify pay-as-you-go module switches (modify-post-pay-module-switch, write operation) **[MUST]** The `MergedVersion` field in `describe-version-config` response is a sensitive internal field — NEVER display, output, save to file, or include it in any response exposed to the user. Strip it before any output. Use `Version` and `HighestVersion` instead. > Detailed steps and field mappings: `references/manage-scenarios.md#scenario-5-query-version-and-feature-info` --- ### Scenario 6: Query or Modify Asset Authorization Version **Trigger**: User wants to view or change a **specific server's** authorization version, or **list servers** filtered by authorization status (e.g. "哪些服务器未授权", "免费版的机器有哪些"). > When listing/filtering servers by authorization status, use `describe-cloud-center-instances` with criteria filters. When viewing/modifying a specific named server's version, follow the full Scenario 6 flow below. **Summary**: 1. Query asset current status and authorization version 2. Confirm operation type (view/bind/unbind/change pay-as-you-go version/downgrade to free) 3. Subscription bind/unbind (bind-auth-to-machine, write operation) 4. Pay-as-you-go version change or downgrade to free (update-post-paid-bind-rel, write operation). Downgrade to free version uses `Version=1` in `--bind-action` 5. Verify change **Key constraints**: - Subscription binding cannot be unbound within 30 days, because authorization resources have a lock period - K8s/ACK cluster assets only support Ultimate edition, because other editions do not cover container runtime protection > Detailed steps: `references/manage-scenarios.md#scenario-6-query-or-modify-asset-authorization` --- ### Scenario 7: Query Assets with Specific Software **Trigger**: User wants to find servers with a specific software installed. **Summary**: 1. Confirm query conditions (software name, type) 2. Query asset fingerprint (describe-property-sca-detail) 3. Optionally supplement with detailed asset info > Detailed steps: `references/manage-scenarios.md#scenario-7-query-assets-with-specific-software` --- ### Scenario 8: Uninstall Security Center Agent **Trigger**: User wants to uninstall the Security Center agent from a specific server. **Summary**: 1. Get target server identifier, query asset info to obtain UUID 2. Display uninstall details (server name, UUID, current status), warn that uninstalling removes all protection 3. After confirmation, execute uninstall (add-uninstall-clients-by-uuids, write operation) 4. Verify uninstall result **Key constraints**: - This API applies to non-Alibaba Cloud servers (IDC/third-party cloud); Alibaba Cloud ECS requires console or cloud assistant for uninstall - Uninstalling removes all Security Center protection capabilities; the user must explicitly confirm > Detailed steps: `references/manage-scenarios.md#scenario-8-uninstall-security-center-agent` --- ### Scenario 9: Security Risk Detection and Query **Trigger**: User wants to detect security risks, trigger vulnerability scans, execute baseline checks, view security alerts, or get risk results. **Summary**: 1. Confirm detection type (query existing risk results / trigger new scan) 2. Query risk results: vulnerabilities (describe-grouped-vul), baseline (list-check-item-warning-summary), security alerts (describe-susp-events) 3. Trigger new scans — two distinct modes: - **Targeted scan** (specific server): Use `modify-push-all-task` with the target UUID for ALL scan types (vulnerability + baseline + fingerprint). **NEVER use `modify-start-vul-scan` for targeted scans.** - **Full scan** (all servers): Use `modify-start-vul-scan` (vulnerability), `exec-strategy` (baseline), `generate-once-task` (fingerprint), `create-virus-scan-once-task` (virus) 4. For targeted asset scans, automatically execute prerequisite chain: authorization check -> client check -> auto-install -> dispatch scan + virus scan 5. After dispatching, poll progress: vulnerability scan (describe-once-task), baseline check (describe-strategy.ExecStatus), virus scan (get-virus-scan-latest-task-statistic); query risk results after all complete **Key constraints**: - **[HARD GATE] NEVER use `modify-start-vul-scan` for targeted scans**: `modify-start-vul-scan` triggers a **global full-scan across ALL servers in the entire account**, not just the target. When scanning a specific server (targeted scan), you MUST use `modify-push-all-task` with the server's UUID — this is the ONLY correct command for targeted vulnerability scans. `modify-start-vul-scan` is reserved exclusively for full-scan scenarios where no specific target is specified. - **[HARD GATE] Client online required for ALL scans**: ALL scan dispatch operations (modify-push-all-task, modify-start-vul-scan, exec-strategy, create-virus-scan-once-task) are host-based and require the target server's Security Center agent `ClientStatus=online`. If the agent is not installed or offline, scans CANNOT be dispatched and WILL produce NO results. There is NO agentless scanning mode in this skill. Do NOT proceed with any scan dispatch if the client is not online — instead, guide the user to install or bring the agent online first - **[HARD GATE] Paid authorization required for scans**: The target server must be bound to a paid authorization version (`AuthVersion > 1`); free version (`AuthVersion <= 1`) servers cannot be scanned - Querying existing risk results (describe-grouped-vul, list-check-item-warning-summary, describe-susp-events) is a READ operation that queries historical data in Security Center's database — this does NOT trigger new scans and does NOT require the agent to be online - Before full scan, query all asset statuses first, show the user ready/not-ready asset breakdown, and confirm before dispatching - Targeted asset scans are fully automated with the prerequisite chain (authorization + client), only authorization binding requires user confirmation - Baseline detection (HEALTH_CHECK / exec-strategy) requires a pre-paid host protection version (Version > 1) or enabled Cloud Security Posture Management (CSPM); skip baseline detection if neither is met - Scan operations are write operations; full scans require confirmation before execution > Detailed steps: `references/manage-scenarios.md#scenario-9-security-risk-detection-and-query` --- ### Fallback Scenario **Trigger**: No scenario matched, or the request exceeds this skill's capability. **Strategy**: Honestly inform the user this is not currently supported; recommend referring to official documentation or submitting a support ticket. --- ## Execution Rules ### Read Operations (Execute Directly) describe-cloud-center-instances, describe-instances, describe-cloud-assistant-status, describe-invocation-results, describe-install-codes, refresh-assets, get-auth-summary, describe-version-config, get-serverless-auth-summary, describe-property-sca-detail, describe-grouped-vul, list-check-item-warning-summary, describe-susp-events, describe-strategy, get-virus-scan-latest-task-statistic, list-virus-scan-machine, list-virus-scan-machine-event, describe-once-task Briefly state intent (1-2 sentences) before calling. ### Write Operations (Confirm Before Execution) add-install-code, run-command, invoke-command, create-or-update-asset-group, modify-post-pay-module-switch, bind-auth-to-machine, update-post-paid-bind-rel, add-uninstall-clients-by-uuids, modify-push-all-task, modify-start-vul-scan, exec-strategy, generate-once-task, create-asset-selection-config, add-asset-selection-criteria, update-selection-key-by-type, create-virus-scan-once-task Flow: Display operation details -> Wait for user confirmation -> Execute -> Report result. ### Observation Phase - Briefly describe the returned result - Determine if it matches expectations - Decide next action ### Iteration Principles 1. If the agent is already online, immediately inform the user no action is needed 2. Limit to 8 CLI tool calls per scenario (proxy scenarios may extend moderately) 3. Do not call APIs without confirmed server information, because wrong parameters return meaningless results 4. Do not skip steps, because each step's output is the next step's input 5. Do not fabricate API return results, because this misleads the user into wrong decisions ### Cost Estimation Rules - When displaying pay-as-you-go module status, include billing method and unit price references for each module - Before the user enables pay-as-you-go modules, include cost estimates in the confirmation details - Fetch pricing from the official billing documentation page: https://help.aliyun.com/zh/security-center/product-overview/billing-overview - Fetch once on the first pricing need per session, then reuse - If unable to fetch, provide the billing page link for the user to check - Base service fee: when any pay-as-you-go module is enabled, a base service fee applies (~0.05 CNY/hour, approx. 36 CNY/month) - If no modules are currently enabled, remind the user about this fee when first enabling > Module classification, estimation formulas, and display formats: `references/manage-scenarios.md` cost estimation section. --- ## Termination and Summary Enter summary when any of the following conditions is met: - Agent has successfully come online - Install command has been provided to the user - Version/authorization/software info has been queried and displayed - Authorization bind/unbind/change operation has completed - Agent uninstall operation has completed - Security risk detection has completed or risk results have been displayed - Issue has been identified and solution provided - Scenario is unsupported and support ticket has been recommended Summary format adapts to the scenario. Core elements: operation result, key information (server/version/status), follow-up recommendations. --- ## Best Practices 1. Always verify CLI version and credentials before any operation 2. Use the correct VendorName based on network access method to avoid connection failures 3. For batch installations, prefer image-based approach to reduce manual effort 4. Check authorization quota before binding new servers to avoid exceeding limits 5. When troubleshooting offline agents, verify network connectivity to Security Center endpoints first 6. For proxy scenarios, ensure proxy server meets requirements (Linux, ports 80/443/8080) before proceeding 7. Always verify agent online status after installation before considering the task complete --- ## References This skill references the following documents, loaded on demand: | Reference | Description | |-----------|-------------| | `references/install-scenarios.md` | Detailed execution steps for installation scenarios (1, 2, 3, 4) | | `references/manage-scenarios.md` | Detailed execution steps for management/query scenarios (5, 6, 7, 8, 9) | | `references/agent-install-guide.md` | Agent install commands and verification methods | | `references/api-reference.md` | All API parameter details and CLI examples | | `references/ram-policies.md` | RAM permission manifest | | `references/cli-installation-guide.md` | Alibaba Cloud CLI installation guide | | `references/related-commands.md` | Complete CLI command reference table | | `references/verification-method.md` | Success verification methods for each scenario | | `references/acceptance-criteria.md` | Skill acceptance criteria and test patterns | FILE:references/acceptance-criteria.md # Acceptance Criteria Test patterns and verification criteria for the alibabacloud-sas-install-agent skill. ## Prerequisites - Aliyun CLI >= 3.3.1 installed and configured - Valid Alibaba Cloud credentials (`aliyun configure list` shows active profile) - Security Center (SAS) service activated - Necessary RAM permissions granted (see `references/ram-policies.md`) ## Test Scenarios ### Scenario 1: Alibaba Cloud ECS Onboarding **Given**: A running Alibaba Cloud ECS instance that is not yet onboarded to Security Center. **Expected flow**: 1. Skill queries ECS instance info via `describe-instances` 2. Skill queries client status via `describe-cloud-center-instances` 3. If uninstalled: Skill gets/creates install code via `describe-install-codes` / `add-install-code` 4. Skill checks cloud assistant via `describe-cloud-assistant-status` 5. If cloud assistant online: Skill dispatches install via `run-command` (after user confirmation) 6. Skill verifies agent comes online **Acceptance**: Agent `ClientStatus` = `online` after installation. ### Scenario 2: On-Premises IDC Direct Connection **Given**: An IDC server with public network or leased-line access to Alibaba Cloud. **Expected flow**: 1. Skill gets/creates install code with correct VendorName (OTHER for public, ALIYUN for leased-line) 2. Skill provides appropriate install command based on network method 3. User executes manually; skill verifies onboarding **Acceptance**: Server appears in Security Center asset list with `ClientStatus` = `online`. ### Scenario 5: Version and Feature Query **Given**: An active Security Center subscription or pay-as-you-go instance. **Expected flow**: 1. Skill queries version via `describe-version-config` 2. Skill queries authorization via `get-auth-summary` 3. Skill displays version, quota, expiration, module switches in readable format **Acceptance**: All version info displayed correctly with timestamps converted to human-readable format. ### Scenario 6: Authorization Version Change **Given**: A server with Security Center agent online, needing version upgrade. **Expected flow**: 1. Skill queries asset status and current auth version 2. Skill confirms operation type and billing mode 3. For subscription: Skill executes `bind-auth-to-machine` (after secondary confirmation) 4. For pay-as-you-go: Skill executes `update-post-paid-bind-rel` (after secondary confirmation with cost estimate) 5. Skill verifies version change **Acceptance**: Asset's `AuthVersion` updated to target version. ### Scenario 8: Agent Uninstall **Given**: A server with Security Center agent online. **Expected flow**: 1. Skill queries asset info to get UUID 2. Skill displays uninstall details with warnings 3. After explicit confirmation, executes `add-uninstall-clients-by-uuids` 4. Verifies agent is offline/removed **Acceptance**: Agent `ClientStatus` changes to `offline` or asset removed from list. ### Scenario 9: Security Risk Detection **Given**: A server with Security Center agent online and paid version bound. **Expected flow**: 1. For targeted scan: Skill auto-checks prerequisites (auth + client) 2. Skill dispatches security check via `modify-push-all-task` 3. Skill dispatches virus scan via `create-virus-scan-once-task` chain 4. Skill polls progress via `describe-once-task` / `get-virus-scan-latest-task-statistic` 5. After completion, skill queries and displays risk results **Acceptance**: Risk results displayed (vulnerabilities, baseline, alerts, virus scan) after scan completion. ## Cross-Cutting Checks | Check | Criteria | |-------|----------| | CLI format | All commands use plugin mode (kebab-case), not PascalCase | | User-agent | All `aliyun` commands include `--user-agent AlibabaCloud-Agent-Skills` | | Write confirmation | All write operations display details and wait for user confirmation | | Credential safety | No AK/SK values are ever printed or exposed | | Permission errors | On 403/NoPermission, skill reads `ram-policies.md` and guides user | | Parameter confirmation | User-customizable parameters are confirmed before execution | FILE:references/agent-install-guide.md # Security Center Agent Install Guide ## TOC - [Prerequisites and Preparation](#prerequisites-and-preparation) - [Installation Method Selection](#installation-method-selection) - [Installation Steps](#installation-steps) - [Verify Installation Status](#verify-installation-status) - [Network Connectivity Requirements](#network-connectivity-requirements) - [Common Issues and Troubleshooting](#common-issues-and-troubleshooting) --- ## Prerequisites and Preparation 1. **System requirements**: OS must be within the supported range. 2. **Account restriction**: Only supports servers under the current Alibaba Cloud account; cross-account requires multi-account management. 3. **Resource estimate**: Single installation takes approximately 5 minutes; CPU/memory may briefly spike during high-load tasks; no business restart required. 4. **Clean residuals**: If previously installed, uninstall first and manually delete directories: - Linux: `/usr/local/aegis` - Windows: `C:\Program Files (x86)\Alibaba\Aegis` 5. **Network policy**: Ensure firewall/security group allows outbound traffic to Security Center service IPs or domains (ports 80/443). --- ## Installation Method Selection | Method | Applicable Scenario | Core Advantage | |--------|---------------------|----------------| | One-click install | Running ECS with cloud assistant, VPC network, supported region | Console operation, no server login needed | | General install | Any server with public network access (Alibaba Cloud ECS or external hosts) | Compatible with mainstream OS, flexible configuration | | Image batch install | Scale-out creation of new servers with pre-installed agent | One-time setup, batch reuse | | Network-restricted install | Cannot connect to public network directly, requires proxy or custom endpoint | Adapts to complex network environments | --- ## Installation Steps ### 1. One-Click Install (via Cloud Assistant) **Prerequisites**: - ECS status is "Running" with cloud assistant installed - Network type is VPC (Virtual Private Cloud) - Region is in the supported list (e.g. Hangzhou, Shanghai, Beijing, Shenzhen, Singapore, Frankfurt, etc.) - Third-party security software has been closed **Procedure**: 1. Log into the Security Center console 2. Left navigation: **System Settings > Feature Settings**, select region (Mainland China / Non-Mainland China) 3. **Client > Uninstalled Client** tab, click **Install Client** in the target server's action column 4. Multi-select servers and click **One-Click Install** for batch deployment ### 2. General Install (Manual Command Execution) **Procedure**: 1. Obtain install command (via console or API `describe-install-codes` / `add-install-code`) 2. Select the corresponding command based on server OS and network access method 3. Log into the server and execute the command with admin privileges > Install code (`-k=` parameter) is obtained via the describe-install-codes API. Different access methods correspond to different install codes. > **Installation process note**: The install command takes some time to execute. Intermediate error messages during the process can be ignored. Success is determined by the final output -- as long as it shows installation succeeded, the process is complete. #### Linux Install Commands **Alibaba Cloud internal network access**: ```bash wget "https://update2.aegis.aliyun.com/download/install/2.0/linux/AliAqsInstall.sh" && chmod +x AliAqsInstall.sh && ./AliAqsInstall.sh -k= ``` **Public network access**: ```bash wget "https://aegis.alicdn.com/download/install/2.0/linux/AliAqsInstall.sh" && chmod +x AliAqsInstall.sh && ./AliAqsInstall.sh -k= ``` #### Windows Install Commands **CMD - Alibaba Cloud internal network access**: ```cmd powershell -executionpolicy bypass -c "(New-Object Net.WebClient).DownloadFile('https://update2.aegis.aliyun.com/download/install/2.0/windows/AliAqsInstall.exe', $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath('.\AliAqsInstall.exe'))"; "./AliAqsInstall.exe -k=" ``` **CMD - Public network access**: ```cmd powershell -executionpolicy bypass -c "(New-Object Net.WebClient).DownloadFile('https://aegis.alicdn.com/download/install/2.0/windows/AliAqsInstall.exe', $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath('.\AliAqsInstall.exe'))"; "./AliAqsInstall.exe -k=" ``` **PowerShell - Alibaba Cloud internal network access**: ```powershell (New-Object Net.WebClient).DownloadFile('https://update2.aegis.aliyun.com/download/install/2.0/windows/AliAqsInstall.exe', $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath('.\AliAqsInstall.exe')); ./AliAqsInstall.exe -k= ``` **PowerShell - Public network access**: ```powershell (New-Object Net.WebClient).DownloadFile('https://aegis.alicdn.com/download/install/2.0/windows/AliAqsInstall.exe', $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath('.\AliAqsInstall.exe')); ./AliAqsInstall.exe -k= ``` #### Download Domain Reference | Access Method | Download Domain | Description | |--------------|-----------------|-------------| | Alibaba Cloud internal | `update2.aegis.aliyun.com` | Via Alibaba Cloud internal network or leased line | | Public network | `aegis.alicdn.com` | Via public internet | ### 3. Image Batch Install **Procedure**: 1. Prepare a clean template server (no third-party security software) 2. When obtaining install command, configure **Create Image System: Yes** (`OnlyImage=true`) 3. Execute the command on the template server (downloads files but does not start the service) 4. **Shut down immediately** (do not restart); create a custom image from this server 5. New instances created from this image will automatically activate and generate a unique ID on first boot > Warning: Before making multiple images from the same template, you must uninstall, clean, and re-obtain the command each time to avoid UUID conflicts. ### 4. Network-Restricted or Complex Environment Install #### A. Overseas Hosts or Unstable Network **Linux**: ```bash wget "https://update6.aegis.aliyun.com/download/install/2.0/linux/AliAqsInstall.sh" && chmod +x AliAqsInstall.sh && ./AliAqsInstall.sh "-j=jsrv-abroad.aegis.aliyuncs.com|jsrv.aegis.aliyun.com" "-u=aegis.alicdn.com|update6.aegis.aliyun.com|update.aegis.aliyun.com" -k= ``` **Windows CMD**: ```cmd powershell -executionpolicy bypass -c "(New-Object Net.WebClient).DownloadFile('https://update6.aegis.aliyun.com/download/install/2.0/windows/AliAqsInstall.exe', $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath('.\AliAqsInstall.exe'))"; "./AliAqsInstall.exe '-j=jsrv-abroad.aegis.aliyuncs.com|jsrv.aegis.aliyun.com' '-u=aegis.alicdn.com|update6.aegis.aliyun.com|update.aegis.aliyun.com' -k=" ``` #### B. Alibaba Cloud Internal Leased Line Access **Linux**: ```bash wget "https://update2.aegis.aliyun.com/download/install/2.0/linux/AliAqsInstall.sh" && chmod +x AliAqsInstall.sh && ./AliAqsInstall.sh "-j=jsrv2.aegis.aliyun.com|jsrv3.aegis.aliyun.com|jsrv4.aegis.aliyun.com|jsrv5.aegis.aliyun.com|jsrv.aegis.aliyun.com" "-u=update2.aegis.aliyun.com|update4.aegis.aliyun.com|update5.aegis.aliyun.com|update3.aegis.aliyun.com|aegis.alicdn.com|update.aegis.aliyun.com" -k= ``` **Windows CMD**: ```cmd powershell -executionpolicy bypass -c "(New-Object Net.WebClient).DownloadFile('https://update2.aegis.aliyun.com/download/install/2.0/windows/AliAqsInstall.exe', $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath('.\AliAqsInstall.exe'))"; "./AliAqsInstall.exe '-j=jsrv2.aegis.aliyun.com|jsrv3.aegis.aliyun.com|jsrv4.aegis.aliyun.com|jsrv5.aegis.aliyun.com|jsrv.aegis.aliyun.com' '-u=update2.aegis.aliyun.com|update4.aegis.aliyun.com|update5.aegis.aliyun.com|update3.aegis.aliyun.com|aegis.alicdn.com|update.aegis.aliyun.com' -k=" ``` #### C. Multi-Cloud Environment with Internal IP Conflicts **Linux**: ```bash wget "https://aegis.alicdn.com/download/install/2.0/linux/AliAqsInstall.sh" && chmod +x AliAqsInstall.sh && ./AliAqsInstall.sh "-j=jsrv.aegis.aliyun.com" "-u=aegis.alicdn.com|update.aegis.aliyun.com" -k= ``` --- ## Verify Installation Status ### Console Verification (approximately 5-minute delay) - Alibaba Cloud servers: **Client** column icon changes from "Unprotected" to "Protected" - Non-Alibaba Cloud servers: Appears in the list with icon change; if not showing, click **Sync Latest Assets** ### Local Server Verification (real-time) **Check processes**: Linux: ```bash ps -ef | grep -E 'AliYunDun|YunDunMonitor|YunDunUpdate' systemctl status aegis ``` Windows (PowerShell): ```powershell Get-Process | Where-Object {$_.Name -match '^(AliYunDun|AliYunDunMonitor|AliYunDunUpdate)$'} Get-Service | Where-Object {$_.Name -match 'Aegis|AliYunDun'} ``` **Check network connectivity**: ```bash telnet jsrv.aegis.aliyun.com 443 telnet update.aegis.aliyun.com 443 ``` --- ## Network Connectivity Requirements ### Aegis Server (Message Channel) The agent uses TCP protocol to connect to port 80 for message channel dispatch and data reporting. At least one group of domains must have port 80 connectivity. | Domain | VIP | Description | |--------|-----|-------------| | jsrv.aegis.aliyun.com | 47.117.157.227, 8.153.161.116, 8.153.86.12, 106.14.18.21 | China mainland public domain | | jsrv2.aegis.aliyun.com | 100.100.30.25, 100.100.30.26 | China mainland Alibaba Cloud internal (leased line) domain | --- ## Common Issues and Troubleshooting - **Third-party software conflict**: Close antivirus/EDR software before installation; can be restored after installation. - **Self-protection process interference**: If prompted "self-protection is running", restart the server and reinstall. - **Agent offline troubleshooting**: - Restart processes (Linux: `killall` + start latest version; Windows: restart service) - Check DNS, firewall ACL, security group outbound rules - Check disk/CPU/memory resources - Verify `aegis_client.conf` does not have duplicate UUIDs - Check logs: Linux `/usr/local/aegis/aegis_client/aegis_12_xx/data/`, Windows `C:\Program Files (x86)\Alibaba\Aegis\aegis_client\aegis_12_xx\data\` FILE:references/api-reference.md # Security Center Onboarding - API Reference This document lists all Alibaba Cloud OpenAPIs used by this skill and their invocation via aliyun CLI. > **Every `aliyun` CLI command MUST include `--user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent`.** ## Table of Contents - [1. describe-cloud-center-instances - Query Asset Information](#1-describe-cloud-center-instances---query-asset-information) - [2. describe-instances - Query ECS Instances](#2-describe-instances---query-ecs-instances) - [3. describe-cloud-assistant-status - Query Cloud Assistant Status](#3-describe-cloud-assistant-status---query-cloud-assistant-status) - [4. invoke-command / run-command - Execute Command via Cloud Assistant](#4-invoke-command--run-command---execute-command-via-cloud-assistant) - [4b. describe-invocation-results - Query Command Execution Results](#4b-describe-invocation-results---query-command-execution-results) - [5. refresh-assets - Sync Asset Status](#5-refresh-assets---sync-asset-status) - [6. describe-install-codes - Query Install Codes](#6-describe-install-codes---query-install-codes) - [7. add-install-code - Create Install Code](#7-add-install-code---create-install-code) - [8. create-or-update-asset-group - Create/Update Asset Group](#8-create-or-update-asset-group---createupdate-asset-group) - [9. describe-version-config - Query Version Details](#9-describe-version-config---query-version-details) - [10. get-auth-summary - Query Authorization Summary](#10-get-auth-summary---query-authorization-summary) - [11. get-serverless-auth-summary - Query Serverless Authorization](#11-get-serverless-auth-summary---query-serverless-authorization) - [12. modify-post-pay-module-switch - Toggle Pay-as-you-go Module Switch](#12-modify-post-pay-module-switch---toggle-pay-as-you-go-module-switch) - [13. bind-auth-to-machine - Bind Authorization to Server](#13-bind-auth-to-machine---bind-authorization-to-server) - [14. update-post-paid-bind-rel - Change Pay-as-you-go Version](#14-update-post-paid-bind-rel---change-pay-as-you-go-version) - [15. describe-property-sca-detail - Query Asset Fingerprint Software](#15-describe-property-sca-detail---query-asset-fingerprint-software) - [16. add-uninstall-clients-by-uuids - Uninstall Client](#16-add-uninstall-clients-by-uuids---uninstall-client) - [17. modify-push-all-task - One-click Security Check](#17-modify-push-all-task---one-click-security-check) - [18. modify-start-vul-scan - Vulnerability Scan](#18-modify-start-vul-scan---vulnerability-scan) - [19. describe-grouped-vul - Query Vulnerability Information](#19-describe-grouped-vul---query-vulnerability-information) - [20. exec-strategy - Execute Baseline Check](#20-exec-strategy---execute-baseline-check) - [21. list-check-item-warning-summary - Query Baseline Risks](#21-list-check-item-warning-summary---query-baseline-risks) - [22. describe-susp-events - Query Security Alerts](#22-describe-susp-events---query-security-alerts) - [23. generate-once-task - Asset Fingerprint Collection](#23-generate-once-task---asset-fingerprint-collection) - [24. describe-strategy - Query Baseline Policies and Execution Status](#24-describe-strategy---query-baseline-policies-and-execution-status) - [25. create-asset-selection-config - Create Asset Selection Config](#25-create-asset-selection-config---create-asset-selection-config) - [26. add-asset-selection-criteria - Add Assets to Selection Config](#26-add-asset-selection-criteria---add-assets-to-selection-config) - [27. update-selection-key-by-type - Associate Asset Selection to Business](#27-update-selection-key-by-type---associate-asset-selection-to-business) - [28. create-virus-scan-once-task - Create Virus Scan Task](#28-create-virus-scan-once-task---create-virus-scan-task) - [29. get-virus-scan-latest-task-statistic - Query Virus Scan Progress](#29-get-virus-scan-latest-task-statistic---query-virus-scan-progress) - [30. list-virus-scan-machine - Query Virus Scan Machine List](#30-list-virus-scan-machine---query-virus-scan-machine-list) - [31. list-virus-scan-machine-event - Query Machine Virus Events](#31-list-virus-scan-machine-event---query-machine-virus-events) - [32. describe-once-task - Query Scan Task Status](#32-describe-once-task---query-scan-task-status) --- ## 1. describe-cloud-center-instances - Query Asset Information **Purpose**: Query server client status (online/offline). **CLI invocation**: ```bash aliyun sas describe-cloud-center-instances \ --criteria '[{"name":"instanceId","value":"i-xxx"}]' \ --machine-types ecs \ --page-size 20 \ --current-page 1 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Common query conditions (criteria field)**: - `instanceId`: Instance ID - `instanceName`: Instance name - `internetIp`: Public IP - `intranetIp`: Private IP - `uuid`: Asset UUID **Key response fields**: - `ClientStatus`: Client status (`online` / `offline` / `pause`) - `Status`: Running status (`Running` / `notRunning`) - `InstanceId`: Instance ID - `Uuid`: Asset UUID - `Os`: Operating system --- ## 2. describe-instances (ECS) - Query ECS Instance Status **Purpose**: Query ECS instance basic information and running status. **CLI invocation**: ```bash aliyun ecs describe-instances \ --region cn-hangzhou \ --biz-region-id cn-hangzhou \ --instance-ids '["i-xxx"]' \ --page-size 10 \ --page-number 1 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` > **[MUST] ECS API Region parameter rules** (applies to ALL ECS API calls in this skill): > - The parameter name is `--biz-region-id` (NOT `--RegionId`, `--region-id`, or `--Region`). Using wrong parameter names causes `unknown flag` errors. > - When the region comes from a SAS `describe-cloud-center-instances` response, use the **`RegionId`** field (e.g. `cn-hangzhou`), NOT the **`Region`** field (e.g. `cn-hangzhou-dg-a01`). The `Region` field is a physical availability zone identifier for dedicated clusters — standard ECS API endpoints do not recognize it, causing `InvalidInstance.NotFound` or `RegionId.ApiNotSupported` errors. > - **[MUST] Endpoint routing**: When the target instance's region differs from the CLI's default configured region, you MUST also add `--region ` to route the request to the correct ECS endpoint. `--biz-region-id` only sets the RegionId in the request body but does NOT change the API endpoint. Without `--region`, the request goes to the wrong endpoint and returns `InvalidOperation.NotSupportedEndpoint`. **Key response fields**: - `InstanceId`: Instance ID - `InstanceName`: Instance name - `Status`: Running status - `PublicIpAddress`: Public IP - `InnerIpAddress`: Private IP - `OSType`: OS type (linux/windows) - `RegionId`: Region --- ## 3. describe-cloud-assistant-status (ECS) - Query Cloud Assistant Status **Purpose**: Check whether Cloud Assistant Agent is installed and online on ECS instances, to determine if remote command dispatch is possible. **CLI invocation**: ```bash aliyun ecs describe-cloud-assistant-status \ --region cn-hangzhou \ --biz-region-id cn-hangzhou \ --instance-id "i-xxx" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --biz-region-id | string | Yes | Region where the instance resides | | --instance-id | list | Yes | Instance ID list (space-separated: `--instance-id i-xxx1 i-xxx2`) | **Key response fields**: - `InstanceCloudAssistantStatus[]`: - `InstanceId`: Instance ID - `CloudAssistantStatus`: Cloud Assistant status (`true` = heartbeat within 2 minutes, online; `false` = offline) - `CloudAssistantVersion`: Cloud Assistant version (empty means not installed) --- ## 4. invoke-command / run-command (ECS) - Execute Command via Cloud Assistant **Purpose**: Remotely execute installation commands on ECS instances via Cloud Assistant (requires Cloud Assistant to be online). **CLI invocation**: ```bash aliyun ecs invoke-command \ --region cn-hangzhou \ --biz-region-id cn-hangzhou \ --command-id "c-xxx" \ --instance-id "i-xxx" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` > Note: You need to first create a command via `create-command`, or use an existing command ID. Alternatively, use `run-command` for a one-step approach. **run-command alternative**: ```bash aliyun ecs run-command \ --region cn-hangzhou \ --biz-region-id cn-hangzhou \ --type RunShellScript \ --command-content "$(echo 'wget "https://update.aegis.aliyun.com/download/install.sh" && chmod +x install.sh && ./install.sh -k=' | base64)" \ --instance-id "i-xxx" \ --content-encoding Base64 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` --- ## 4b. describe-invocation-results (ECS) - Query Command Execution Results **Purpose**: Query execution results of cloud assistant commands dispatched via invoke-command or run-command, used to poll whether remote installation completed successfully. **CLI invocation**: ```bash aliyun ecs describe-invocation-results \ --region cn-hangzhou \ --biz-region-id cn-hangzhou \ --invoke-id "" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --biz-region-id | string | Yes | Region where the instance resides | | --invoke-id | string | No | Command execution ID (returned by invoke-command or run-command) | | --instance-id | string | No | Filter by instance ID | | --command-id | string | No | Filter by command ID | | --invoke-record-status | string | No | Filter by status: Running, Finished, Success, Failed, PartialFailed, Stopped | | --content-encoding | string | No | Output encoding: PlainText (raw) or Base64 (default) | | --max-results | integer | No | Max results per page, max 50, default 10 | | --next-token | string | No | Pagination token from previous response | **Key response fields**: - `Invocation.InvocationResults.InvocationResult[]`: - `InvokeId`: Command execution ID - `InstanceId`: Instance ID - `InvocationStatus`: Execution status (`Running`, `Success`, `Failed`, `Stopped`, `Stopping`) - `ExitCode`: Command exit code (0 = success) - `Output`: Command output (Base64 encoded by default) - `ErrorInfo`: Error info if failed - `StartTime`: Execution start time - `FinishedTime`: Execution end time > **Polling pattern**: After dispatching a command via run-command, use the returned InvokeId to poll describe-invocation-results. Check `InvocationStatus`: when it is no longer `Running`, execution is complete. Recommended polling interval: 30 seconds. --- ## 5. refresh-assets - Sync Asset Status **Purpose**: Sync asset data when servers are not found in the asset list. **CLI invocation**: ```bash aliyun sas refresh-assets \ --asset-type ecs \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: - `--asset-type`: Asset type to sync (`ecs` = servers, `cloud_product` = cloud products, `container_image` = container images) - `--vendor`: Server vendor (0 = Alibaba Cloud, 1 = non-cloud, 2 = IDC) --- ## 6. describe-install-codes - Query Install Code List **Purpose**: Query generated install codes and their corresponding installation commands. **CLI invocation**: ```bash aliyun sas describe-install-codes \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Key response fields**: - `InstallCodes` (array): - `CaptchaCode`: Install verification code (the key used in install commands) - `Os`: Operating system (linux/windows) - `VendorName`: Vendor name - `GroupId` / `GroupName`: Group information - `OnlyImage`: Whether image-based installation - `ExpiredDate`: Expiration time (13-digit timestamp) --- ## 7. add-install-code - Create Install Code **Purpose**: Generate a new install code and installation command. **CLI invocation**: ```bash aliyun sas add-install-code \ --os linux \ --vendor-name "ALIYUN" \ --expired-date 1735689600000 \ --only-image false \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --os | string | No | Operating system, defaults to linux. Values: linux, windows | | --vendor-name | string | No | Vendor, defaults to ALIYUN | | --group-id | long | No | Asset group ID to bind | | --expired-date | long | No | Validity period, 13-digit timestamp | | --only-image | boolean | No | Whether image-based installation, defaults to false | --- ## 8. create-or-update-asset-group - Create/Update Asset Group **Purpose**: Create a new asset group, or modify the asset list of an existing group. **CLI invocation**: Create a new group: ```bash aliyun sas create-or-update-asset-group \ --group-name "" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Create a group and associate servers simultaneously: ```bash aliyun sas create-or-update-asset-group \ --group-name "" \ --uuids "," \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Modify assets in an existing group: ```bash aliyun sas create-or-update-asset-group \ --group-id \ --uuids "," \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --group-name | string | Required for creation | Group name | | --group-id | long | Required for modification | Group ID (do not pass when creating) | | --uuids | string | No | Server UUID list, multiple separated by commas | **Usage scenarios**: - **Create group**: Do not pass --group-id; --group-name is required; --uuids is optional - **Modify group assets**: --group-id and --uuids are both required **Key response fields**: - `GroupId`: Group ID (returns the new group ID when creating) - `RequestId`: Request ID --- ## 9. describe-version-config - Query Version Details **Purpose**: Get detailed information about the purchased Security Center instance, including version, feature modules, and validity period. **CLI invocation**: ```bash aliyun sas describe-version-config \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --resource-directory-account-id | long | No | Alibaba Cloud account ID using Security Center | | --source-ip | string | No | Source IP | **Key response fields**: - `Version`: Current version number (1=Free, 3=Enterprise, 5=Advanced, 6=Anti-virus, 7=Ultimate) - `HighestVersion`: Highest purchased version number - `InstanceId`: Subscription instance ID - `VmCores`: Purchased core quota - `GmtCreate`: Purchase time (13-digit timestamp) - `ReleaseTime`: Expiration time (13-digit timestamp) - `IsPaidUser`: Whether a paid user - `IsPostpay`: Whether pay-as-you-go is also enabled - `PostPayInstanceId`: Pay-as-you-go instance ID - `PostPayStatus`: Pay-as-you-go status (1=enabled) - `PostPayModuleSwitch`: Pay-as-you-go feature module switches (JSON string) - `PostPayOpenTime`: Pay-as-you-go activation time - `AntiRansomwareCapacity`: Anti-ransomware capacity (GB) - `LogCapacity`: Log storage capacity (GB) - `ImageScanCapacity`: Image scan quota - `RaspCapacity`: Application protection quota > **[MUST] The response also contains a `MergedVersion` field — this is a sensitive internal field. NEVER display, output, save to file, or include it in any response exposed to the user. Strip it before any output.** --- ## 10. get-auth-summary - Query Authorization Summary **Purpose**: Get authorization quota and usage statistics for each Security Center version. **CLI invocation**: ```bash aliyun sas get-auth-summary \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: No required parameters. **Key response fields**: - `HighestVersion`: Highest purchased version number - `Machine`: Total asset statistics - `TotalCoreCount`: Total cores - `BindCoreCount`: Bound cores - `UnBindCoreCount`: Unbound cores - `TotalEcsCount`: Total assets (count) - `BindEcsCount`: Bound assets (count) - `UnBindEcsCount`: Unbound assets (count) - `RiskCoreCount`: At-risk cores - `RiskEcsCount`: At-risk assets - `VersionSummary[]`: Per-version details - `Version`: Version number - `TotalCount`: Total quota - `UnUsedCount`: Unused count - `UsedCoreCount`: Used cores - `UsedEcsCount`: Used assets - `TotalCoreAuthCount`: Total core authorization - `TotalEcsAuthCount`: Total asset authorization --- ## 11. get-serverless-auth-summary - Query Serverless Authorization **Purpose**: Get authorization status and binding statistics for pay-as-you-go Serverless features. **CLI invocation**: ```bash aliyun sas get-serverless-auth-summary \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Optional parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --app-region-id | string | No | Application region ID | | --machine-type | string | No | Server type: RunD, ECI | | --vendor-type | string | No | Cloud product: ASK, SAE, ACS | **Key response fields** (within `Data` object): - `IsPostPaid`: Whether pay-as-you-go - `IsServerlessPostPaidValid`: Whether Serverless pay-as-you-go is active - `PostPaidStatus`: Pay-as-you-go status - `PostPaidModuleSwitch`: Module switches (JSON string) - `PostPaidOpenTime`: Activation time - `AutoBind`: Whether auto-binding is enabled - `TotalBindAppCount`: Bound application count - `TotalBindCoreCount`: Bound core count - `TotalBindInstanceCount`: Bound instance count --- ## 12. modify-post-pay-module-switch - Toggle Pay-as-you-go Module Switch **Purpose**: Enable or disable pay-as-you-go feature modules. **CLI invocation**: ```bash aliyun sas modify-post-pay-module-switch \ --post-pay-instance-id "" \ --post-pay-module-switch '{"VUL": 1, "CSPM": 0}' \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --post-pay-instance-id | string | No | Pay-as-you-go instance ID (obtained via describe-version-config) | | --post-pay-module-switch | string | No | Module switch JSON. Key = module code, Value = 0 (off) or 1 (on) | | --post-paid-host-auto-bind | integer | No | Auto-bind new assets switch (0=off, 1=on) | | --post-paid-host-auto-bind-version | integer | No | Auto-bind version (1=Free, 3=Enterprise, 5=Advanced, 6=Anti-virus, 7=Ultimate) | **Module code reference**: | Code | Module Name | |------|-------------| | POST_HOST | Host & Container Security | | VUL | Vulnerability Fix | | CSPM | Cloud Security Posture Management | | AGENTLESS | Agentless Detection | | SERVERLESS | Serverless Security | | CTDR | Agent SOC | | SDK | Malicious File Detection SDK | | RASP | Application Protection | | CTDR_STORAGE | Log Management | | ANTI_RANSOMWARE | Anti-ransomware | | AI_DIGITAL | Agent SOC - Security Operations Agent | | WEB_LOCK | Web Tamper Proofing | | IMAGE_SCAN | Image Scan | > BASIC_SERVICE is an internal base service module and is not exposed to users. Modules not included in the request remain unchanged. --- ## 13. bind-auth-to-machine - Bind Authorization to Server **Purpose**: Bind or unbind a specific version authorization for servers. **CLI invocation**: Bind authorization: ```bash aliyun sas bind-auth-to-machine \ --auth-version 7 \ --bind "" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Unbind authorization: ```bash aliyun sas bind-auth-to-machine \ --un-bind "" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Batch bind: ```bash aliyun sas bind-auth-to-machine \ --auth-version 7 \ --bind "" "" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --auth-version | integer | No | Authorization version: 5=Advanced, 3=Enterprise, 6=Anti-virus, 7=Ultimate, 10=Value-added Service | | --bind | list | No | UUIDs to bind (space-separated; --bind and --un-bind cannot both be empty) | | --un-bind | list | No | UUIDs to unbind (space-separated; --bind and --un-bind cannot both be empty) | | --bind-all | boolean | No | Whether to bind all, defaults to false | | --auto-bind | integer | No | Auto-bind switch (0=off, 1=on) | | --criteria | string | No | Search criteria JSON | | --logical-exp | string | No | Multi-condition logic (OR/AND) | **Important constraints**: - In subscription (pre-paid) mode, any paid version binding cannot be unbound within 30 days - K8s / ACK cluster assets only support binding to Ultimate edition (--auth-version 7) --- ## 14. update-post-paid-bind-rel - Change Pay-as-you-go Version **Purpose**: Change the protection version binding relationship for pay-as-you-go service. **CLI invocation**: Bind / upgrade to paid version: ```bash aliyun sas update-post-paid-bind-rel \ --bind-action '[{"Version": "7", "UuidList": [""]}]' \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Unbind / downgrade to free version (Version=1): ```bash aliyun sas update-post-paid-bind-rel \ --bind-action '[{"UuidList": [""], "Version": 1}]' \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --bind-action | structure list | No | Binding actions JSON array. Each element: `{"Version": "", "UuidList": [""], "BindAll": false}`. Use `Version=1` to downgrade to free version | | --auto-bind | integer | No | Auto-bind new assets (0=off, 1=on) | | --auto-bind-version | integer | No | Auto-bind version number | | --update-if-necessary | boolean | No | Whether to force version upgrade | --- ## 15. describe-property-sca-detail - Query Asset Fingerprint Software **Purpose**: Query software information installed on servers, including middleware, databases, and web services. **CLI invocation**: Query by software name: ```bash aliyun sas describe-property-sca-detail \ --search-item name \ --search-info "nginx" \ --current-page 1 \ --page-size 20 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Query by software type: ```bash aliyun sas describe-property-sca-detail \ --search-item type \ --search-info "web_container" \ --current-page 1 \ --page-size 20 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Query database type: ```bash aliyun sas describe-property-sca-detail \ --biz sca_database \ --search-item name \ --search-info "mysql" \ --current-page 1 \ --page-size 20 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --biz | string | No | Query type: sca (middleware, default), sca_database (database), sca_web (web service) | | --biz-type | string | No | Sub-type: system_service, software_library, docker_component, database, web_container, jar, web_framework | | --search-item | string | No | Query condition type: name (by name), type (by type) | | --search-info | string | No | Query content (used together with --search-item) | | --sca-name | string | No | Asset fingerprint name | | --sca-version | string | No | Software version | | --remark | string | No | Search condition (server name or IP, supports fuzzy search) | | --uuid | string | No | Specific server UUID | | --port | string | No | Process listening port | | --pid | string | No | Process ID | | --user | string | No | Running user | | --current-page | integer | No | Page number, defaults to 1 | | --page-size | integer | No | Items per page, defaults to 10 | **Key response fields**: - `PageInfo`: Pagination info - `TotalCount`: Total count - `CurrentPage`: Current page - `PageSize`: Page size - `Propertys[]`: Software list - `InstanceName`: Server name - `InstanceId`: Instance ID - `InternetIp`: Public IP - `IntranetIp`: Private IP - `Name`: Software name - `Version`: Software version - `Port`: Listening port - `Pid`: Process ID - `User`: Running user - `BizType`: Software type - `BizTypeDispaly`: Type display name --- ## 16. add-uninstall-clients-by-uuids - Uninstall Client **Purpose**: Uninstall the Security Center client from specified servers. Applicable to any server with an online client. **CLI invocation**: Uninstall from a single server: ```bash aliyun sas add-uninstall-clients-by-uuids \ --uuids "" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Batch uninstall from multiple servers: ```bash aliyun sas add-uninstall-clients-by-uuids \ --uuids ",," \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --uuids | string | Yes | Server UUIDs to uninstall client from, multiple separated by commas. Obtained via describe-cloud-center-instances | | --biz-region | string | No | Server region | | --call-method | string | No | Method name, defaults to init | | --feedback | string | No | Feedback info (e.g., reinstall) | | --source-ip | string | No | Source IP, auto-detected by the system | **Key response fields**: - `RequestId`: Request ID **Important constraints**: - Client status must be `online` to execute uninstallation; offline clients cannot be uninstalled via this API - After uninstallation, the server loses all Security Center protection capabilities - Insufficient permissions return `403 NoPermission`; contact the primary account to configure RAM permissions --- ## 17. modify-push-all-task - One-click Security Check **Purpose**: Dispatch security check tasks to specified servers. **CLI invocation**: ```bash aliyun sas modify-push-all-task \ --uuids "," \ --tasks "OVAL_ENTITY,CMS,SYSVUL,SCA,HEALTH_CHECK,WEBSHELL,PROC_SNAPSHOT,PORT_SNAPSHOT,ACCOUNT_SNAPSHOT,SOFTWARE_SNAPSHOT,SCA_SNAPSHOT" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --uuids | string | Yes | Server UUID list, multiple separated by commas | | --tasks | string | Yes | Check items list, multiple separated by commas | | --source-ip | string | No | Source IP, auto-detected by the system | **Tasks check item descriptions**: *Vulnerability scanning*: | Check Item | Description | |------------|-------------| | OVAL_ENTITY | Linux vulnerability detection (CVE) | | CMS | Web-CMS vulnerability detection | | SYSVUL | Windows system vulnerability detection | *Security detection*: | Check Item | Description | |------------|-------------| | HEALTH_CHECK | Baseline check (requires subscription host protection Version>1 or pay-as-you-go CSPM=1; otherwise do not include) | | WEBSHELL | Web shell detection | *Asset fingerprint collection*: | Check Item | Description | |------------|-------------| | SCA | Middleware fingerprint collection | | SCA_SNAPSHOT | Middleware snapshot | | PROC_SNAPSHOT | Process snapshot | | PORT_SNAPSHOT | Port snapshot | | ACCOUNT_SNAPSHOT | Account snapshot | | SOFTWARE_SNAPSHOT | Software snapshot | > This API performs a comprehensive security check covering vulnerability scanning, baseline detection, and asset fingerprint collection. It is suitable for thorough security inspection of specified assets. HEALTH_CHECK (baseline check) should only be included in Tasks when the user has subscription host protection (Version>1) or has enabled Cloud Security Posture Management pay-as-you-go (CSPM=1); otherwise exclude it. **Key response fields**: - `RequestId`: Request ID - `PushTaskRsp.PushTaskResultList[]`: Task execution results - `Uuid`: Server UUID - `InstanceName`: Server name - `Success`: Whether execution succeeded - `Online`: Whether client is online - `Message`: Detailed failure information **Important constraints**: - Target servers must be bound to a paid version (not Free edition); Free edition returns `FreeVersionNotPermit` error - Servers with offline clients cannot execute check tasks - Check results are obtained by polling the corresponding APIs (describe-once-task / describe-strategy / get-virus-scan-latest-task-statistic) --- ## 18. modify-start-vul-scan - Vulnerability Scan **Purpose**: Trigger one-click vulnerability scanning. **CLI invocation**: Scan all vulnerability types: ```bash aliyun sas modify-start-vul-scan \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Specify vulnerability types and servers: ```bash aliyun sas modify-start-vul-scan \ --types "cve,sys,cms" \ --uuids "," \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --types | string | No | Vulnerability types, multiple separated by commas. Omit to scan all types. Values: cve (Linux), sys (Windows), cms (Web-CMS), app (application vulnerability - scan), sca (application vulnerability - component analysis) | | --uuids | string | No | Server UUID list. Omit to scan all servers | **Key response fields**: - `RequestId`: Request ID --- ## 19. describe-grouped-vul - Query Vulnerability Information **Purpose**: Query vulnerability risk statistics grouped by vulnerability. **CLI invocation**: Query unhandled Linux vulnerabilities: ```bash aliyun sas describe-grouped-vul \ --type cve \ --dealed n \ --current-page 1 \ --page-size 20 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Query high-priority vulnerabilities: ```bash aliyun sas describe-grouped-vul \ --necessity asap \ --dealed n \ --current-page 1 \ --page-size 20 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --type | string | No | Vulnerability type, defaults to cve. Values: cve (Linux), sys (Windows), cms (Web-CMS), app (application - scan), sca (application - component analysis) | | --dealed | string | No | Whether handled: y (handled), n (unhandled) | | --necessity | string | No | Fix priority, multiple separated by commas: asap (high), later (medium), nntf (low) | | --alias-name | string | No | Vulnerability alias (fuzzy search) | | --cve-id | string | No | CVE ID | | --uuids | string | No | Server UUIDs, multiple separated by commas | | --group-id | string | No | Asset group ID | | --current-page | integer | No | Page number, defaults to 1 | | --page-size | integer | No | Items per page, defaults to 10 | | --lang | string | No | Language: zh (Chinese), en (English), defaults to zh | **Key response fields**: - `TotalCount`: Total count - `GroupedVulItems[]`: Vulnerability information list - `AliasName`: Vulnerability alias - `Name`: Vulnerability name - `Type`: Vulnerability type - `AsapCount`: High-priority count - `LaterCount`: Medium-priority count - `NntfCount`: Low-priority count - `HandledCount`: Handled count - `GmtFirst`: First discovery time (13-digit timestamp) - `GmtLast`: Last discovery time (13-digit timestamp) - `Related`: Related CVE list - `Tags`: Vulnerability tags (e.g., "remote exploitation", "code execution") --- ## 20. exec-strategy - Execute Baseline Check **Purpose**: Execute a specified baseline check policy. **CLI invocation**: ```bash aliyun sas exec-strategy \ --strategy-id \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --strategy-id | integer | No | Baseline check policy ID | | --exec-action | string | No | Execution action, defaults to exec | | --lang | string | No | Language: zh (Chinese), en (English), defaults to zh | **Key response fields**: - `RequestId`: Request ID --- ## 21. list-check-item-warning-summary - Query Baseline Risks **Purpose**: Get risk statistics for baseline check items. **CLI invocation**: Query failed check items: ```bash aliyun sas list-check-item-warning-summary \ --check-warning-status 1 \ --current-page 1 \ --page-size 20 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Query high-risk items: ```bash aliyun sas list-check-item-warning-summary \ --check-warning-status 1 \ --check-level high \ --current-page 1 \ --page-size 20 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --check-warning-status | integer | No | Risk status: 1 (failed), 3 (passed), 6 (whitelisted), 8 (fixed). Defaults to all | | --check-level | string | No | Risk level: high, medium, low. Defaults to all | | --check-type | string | No | Check item category name | | --check-item-fuzzy | string | No | Check item name fuzzy match | | --group-id | long | No | Asset group ID | | --current-page | integer | No | Page number, defaults to 1 | | --page-size | integer | No | Items per page, defaults to 20 | | --lang | string | No | Language: zh (Chinese), en (English), defaults to zh | **Key response fields**: - `PageInfo`: Pagination info - `TotalCount`: Total count - `CurrentPage`: Current page - `List[]`: Check item risk list - `CheckItem`: Check item description - `CheckLevel`: Risk level (high/medium/low) - `CheckType`: Check item category - `Status`: Risk status (1=failed, 3=passed, 6=whitelisted, 8=fixed) - `WarningMachineCount`: Number of affected machines - `Advice`: Remediation advice - `Description`: Detailed description - `CheckId`: Check item ID --- ## 22. describe-susp-events - Query Security Alerts **Purpose**: Query security alert event list. **CLI invocation**: Query pending alerts: ```bash aliyun sas describe-susp-events \ --dealed N \ --current-page 1 \ --page-size 20 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Query critical alerts: ```bash aliyun sas describe-susp-events \ --dealed N \ --levels serious \ --current-page 1 \ --page-size 20 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Query alerts for a specific server: ```bash aliyun sas describe-susp-events \ --uuids "" \ --dealed N \ --current-page 1 \ --page-size 20 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --dealed | string | No | Whether handled: N (pending), Y (handled) | | --levels | string | No | Alert level, multiple separated by commas: serious (critical), suspicious (suspicious), remind (informational) | | --parent-event-types | string | No | Alert type (e.g., abnormal process behavior, web shell, abnormal login) | | --remark | string | No | Alert name or asset info (supports fuzzy query) | | --uuids | string | No | Server UUIDs, multiple separated by commas | | --group-id | long | No | Asset group ID | | --name | string | No | Affected asset name | | --status | string | No | Event status: 1 (pending), 2 (ignored), 4 (confirmed), 32 (resolved) | | --current-page | string | No | Page number, defaults to 1 | | --page-size | string | No | Items per page, defaults to 20, max 100 | | --lang | string | No | Language: zh (Chinese), en (English), defaults to zh | **Key response fields**: - `TotalCount`: Total alert event count - `SuspEvents[]`: Alert event list - `AlarmEventNameDisplay`: Alert name - `AlarmEventTypeDisplay`: Alert type - `Level`: Severity level (serious/suspicious/remind) - `InstanceName`: Affected instance name - `InstanceId`: Instance ID - `InternetIp`: Public IP - `IntranetIp`: Private IP - `Uuid`: Instance UUID - `OccurrenceTime`: First occurrence time - `LastTime`: Last occurrence time - `EventStatus`: Event status (1=pending, 4=confirmed, 32=resolved) - `Desc`: Alert description - `AlarmUniqueInfo`: Alert unique identifier - `Details[]`: Alert detail list - `NameDisplay`: Detail display name - `ValueDisplay`: Detail display value --- ## 23. generate-once-task - Asset Fingerprint Collection **Purpose**: Trigger a one-time asset fingerprint collection task across all servers, collecting account, port, process, software, cron job, and other information. **CLI invocation**: ```bash aliyun sas generate-once-task \ --task-type "ASSETS_COLLECTION" \ --task-name "ASSETS_COLLECTION" \ --param '{"items":"ACCOUNT_SNAPSHOT,PORT_SNAPSHOT,PROC_SNAPSHOT,SOFTWARE_SNAPSHOT,CROND_SNAPSHOT,SCA_SNAPSHOT,LKM_SNAPSHOT,AUTORUN_SNAPSHOT,SCA_PROXY_SNAPSHOT"}' \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --task-type | string | Yes | Task type, fixed as `ASSETS_COLLECTION` for asset fingerprint collection | | --task-name | string | Yes | Task name, fixed as `ASSETS_COLLECTION` for asset fingerprint collection | | --param | string | Yes | Task parameter JSON. The `items` field specifies collection items, comma-separated | **Collection items**: | Item | Description | |------|-------------| | ACCOUNT_SNAPSHOT | Account snapshot | | PORT_SNAPSHOT | Port snapshot | | PROC_SNAPSHOT | Process snapshot | | SOFTWARE_SNAPSHOT | Software snapshot | | CROND_SNAPSHOT | Cron job snapshot | | SCA_SNAPSHOT | Middleware snapshot | | LKM_SNAPSHOT | Kernel module snapshot | | AUTORUN_SNAPSHOT | Auto-start item snapshot | | SCA_PROXY_SNAPSHOT | Proxy middleware snapshot | **Key response fields**: - `RequestId`: Request ID --- ## 24. describe-strategy - Query Baseline Policies and Execution Status **Purpose**: Query baseline check policy list to obtain policy IDs for exec-strategy, and check execution progress via ExecStatus. **CLI invocation**: Query all policies: ```bash aliyun sas describe-strategy \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Query standard policies: ```bash aliyun sas describe-strategy \ --custom-type common \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Query custom policies: ```bash aliyun sas describe-strategy \ --custom-type custom \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --custom-type | string | No | Policy type: common (standard), custom (custom). Omit to query all | | --strategy-ids | string | No | Policy ID list, multiple separated by commas | | --lang | string | No | Language: zh (Chinese), en (English), defaults to zh | **Key response fields**: - `Strategies[]`: Policy list - `Id`: Policy ID (the --strategy-id parameter for exec-strategy) - `Name`: Policy name - `CustomType`: Policy type (common=standard / custom=custom) - `CycleDays`: Check cycle (days) - `StartTime`: Execution start time - `EndTime`: Execution end time - `EcsCount`: Associated server count - `RiskCount`: Risk item count - `PassRate`: Pass rate (percentage) - `ExecStatus`: Execution status (1=not executed/completed, 2=in progress) - `Percent`: Check progress percentage (only returned when ExecStatus=2) > **Polling baseline check progress**: After triggering exec-strategy, poll describe-strategy to check the corresponding policy's ExecStatus. When ExecStatus=2, the check is in progress and you can get progress via Percent. When ExecStatus returns to 1, execution is complete. Recommended polling interval: 30 seconds. --- ## 25. create-asset-selection-config - Create Asset Selection Config **Purpose**: Create an asset selection configuration for virus scanning and other business operations, and obtain a SelectionKey. **CLI invocation**: Specify instances: ```bash aliyun sas create-asset-selection-config \ --business-type "VIRUS_SCAN_ONCE_TASK" \ --target-type "instance" \ --platform "all" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` All instances: ```bash aliyun sas create-asset-selection-config \ --business-type "VIRUS_SCAN_ONCE_TASK" \ --target-type "all_instance" \ --platform "all" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --business-type | string | Yes | Business type, must be the exact string value: `VIRUS_SCAN_ONCE_TASK` (one-time virus scan) or `VIRUS_SCAN_CYCLE_CONFIG` (periodic virus scan). Do NOT use numeric codes | | --target-type | string | Yes | Target type: `all_instance` (all servers), `instance` (by instance), `group` (by group), `vpc` (by VPC) | | --platform | string | No | OS platform: `all`, `windows`, `linux`. Defaults to all | **Key response fields**: - `Data.SelectionKey`: Asset selection unique identifier (used in subsequent steps) - `Data.BusinessType`: Business type - `Data.TargetType`: Target type --- ## 26. add-asset-selection-criteria - Add Assets to Selection Config **Purpose**: When TargetType is `instance`, add specific target assets to the SelectionKey. **CLI invocation**: Add a single asset: ```bash aliyun sas add-asset-selection-criteria \ --selection-key "" \ --target-operation-list Target="" Operation=add \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Add multiple assets: ```bash aliyun sas add-asset-selection-criteria \ --selection-key "" \ --target-operation-list Target="" Operation=add \ --target-operation-list Target="" Operation=add \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --selection-key | string | Yes | Asset selection identifier returned by create-asset-selection-config | | --target-operation-list | struct list | No | Each entry: `Target= Operation=`. Repeat for multiple assets | **Key response fields**: - `RequestId`: Request ID --- ## 27. update-selection-key-by-type - Associate Asset Selection to Business **Purpose**: Associate an asset selection configuration (SelectionKey) to a specified business type. **CLI invocation**: ```bash aliyun sas update-selection-key-by-type \ --business-type "VIRUS_SCAN_ONCE_TASK" \ --selection-key "" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --business-type | string | No | Business type, same as create-asset-selection-config | | --selection-key | string | No | Asset selection identifier | **Key response fields**: - `RequestId`: Request ID --- ## 28. create-virus-scan-once-task - Create Virus Scan Task **Purpose**: Create a one-time virus scan task. **CLI invocation**: ```bash aliyun sas create-virus-scan-once-task \ --scan-type "system" \ --selection-key "" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --scan-type | string | No | Scan type: `system` (system scan, full-disk key paths), `user` (custom scan, requires --scan-path) | | --selection-key | string | No | Asset selection identifier | | --scan-path | list | No | Custom scan paths (only used when --scan-type=user, space-separated) | **Key response fields**: - `RequestId`: Request ID **Invocation flow**: Complete create-asset-selection-config -> [add-asset-selection-criteria] -> update-selection-key-by-type before calling this API. --- ## 29. get-virus-scan-latest-task-statistic - Query Virus Scan Progress **Purpose**: Query the progress and statistics of the most recent virus scan task. **CLI invocation**: ```bash aliyun sas get-virus-scan-latest-task-statistic \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: No required parameters. **Key response fields**: - `Data.TaskId`: Task ID - `Data.Status`: Task status (10=in progress, 20=completed) - `Data.Progress`: Progress percentage - `Data.ScanType`: Scan type (system / user) - `Data.ScanTime`: Scan start time (13-digit timestamp) - `Data.ScanMachine`: Total machines scanned - `Data.CompleteMachine`: Completed machine count - `Data.UnCompleteMachine`: Incomplete machine count - `Data.SafeMachine`: Safe machine count (no virus found) - `Data.SuspiciousMachine`: Machine count with viruses found - `Data.SuspiciousCount`: Total virus count found --- ## 30. list-virus-scan-machine - Query Virus Scan Machine List **Purpose**: Query the list of machines involved in virus scanning. **CLI invocation**: ```bash aliyun sas list-virus-scan-machine \ --current-page 1 \ --page-size 20 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Filter by asset: ```bash aliyun sas list-virus-scan-machine \ --current-page 1 \ --page-size 20 \ --uuid "" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --current-page | integer | Yes | Current page number | | --page-size | integer | Yes | Items per page | | --uuid | string | No | Filter by asset UUID | | --remark | string | No | Fuzzy search by asset name or IP | **Key response fields**: - `Data[]`: Machine list - `PageInfo.TotalCount`: Total count --- ## 31. list-virus-scan-machine-event - Query Machine Virus Events **Purpose**: Query virus scan event details for a specified machine. **CLI invocation**: ```bash aliyun sas list-virus-scan-machine-event \ --current-page 1 \ --page-size 20 \ --uuid "" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --current-page | integer | Yes | Current page number | | --page-size | integer | Yes | Items per page | | --uuid | string | No | Asset UUID | | --lang | string | No | Language: zh (Chinese), en (English) | **Key response fields**: - `Data[]`: Virus event list - `PageInfo.TotalCount`: Total count --- ## 32. describe-once-task - Query Scan Task Status **Purpose**: Query execution status and progress of one-time tasks such as vulnerability scans and asset collection, used for polling task completion. **CLI invocation**: Query vulnerability scan task: ```bash aliyun sas describe-once-task \ --task-type "VUL_CHECK_TASK" \ --current-page 1 \ --page-size 5 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --task-type | string | No | Task type: `VUL_CHECK_TASK` (vulnerability scan), `CLIENT_PROBLEM_CHECK` (client check), `CLIENT_DEV_OPS` (cloud operations), `ASSET_SECURITY_CHECK` (asset collection). Cannot be empty simultaneously with --root-task-id | | --root-task-id | string | No | Root task ID. Cannot be empty simultaneously with --task-type | | --task-id | string | No | Task ID | | --source | string | No | Task source: `schedule` (auto-scheduled), `console` (one-click check) | | --start-time-query | long | No | Root task start timestamp (milliseconds) | | --end-time-query | long | No | Root task end timestamp (milliseconds) | | --current-page | integer | No | Current page number, defaults to 1 | | --page-size | integer | No | Items per page, defaults to 20 | **Key response fields**: - `TaskManageResponseList[]`: Task list - `TaskId`: Task ID - `TaskType`: Task type - `TaskName`: Task name - `TaskStatus`: Task status number (1=in progress) - `TaskStatusText`: Task status text (`PROCESSING`=in progress) - `Progress`: Progress percentage (e.g., "40%") - `TotalCount`: Total machine count - `SuccessCount`: Completed machine count - `FailCount`: Failed machine count - `TaskStartTime`: Task start timestamp (milliseconds) - `Source`: Task source (schedule / console) - `Context`: Task context (JSON string, contains scan type info) - `PageInfo.TotalCount`: Total task count > **Polling vulnerability scan progress**: After triggering modify-start-vul-scan, poll describe-once-task (--task-type=VUL_CHECK_TASK) and check the latest task's TaskStatusText. When it is no longer `PROCESSING`, the scan is complete. Recommended polling interval: 30 seconds. FILE:references/cli-installation-guide.md # Aliyun CLI Installation & Configuration Guide Complete guide for installing and configuring Aliyun CLI. > **Aliyun CLI 3.3.3+**: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.3 or later for full plugin ecosystem coverage. ## Installation ### macOS **Using Homebrew (Recommended)** ```bash brew install aliyun-cli # Upgrade to latest brew upgrade aliyun-cli # Verify version (>= 3.3.3) aliyun version ``` **Using Binary** ```bash # Download wget https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-amd64.tgz # Extract tar -xzf aliyun-cli-macosx-latest-amd64.tgz # Move to PATH sudo mv aliyun /usr/local/bin/ # Verify aliyun version ``` ### Linux **Debian/Ubuntu** ```bash # Download wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz # Extract and install tar -xzf aliyun-cli-linux-latest-amd64.tgz sudo mv aliyun /usr/local/bin/ # Verify aliyun version ``` **CentOS/RHEL** ```bash # Download wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz # Extract and install tar -xzf aliyun-cli-linux-latest-amd64.tgz sudo mv aliyun /usr/local/bin/ # Verify aliyun version ``` **ARM64 Architecture** ```bash # Download ARM64 version wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz # Extract and install tar -xzf aliyun-cli-linux-latest-arm64.tgz sudo mv aliyun /usr/local/bin/ ``` ### Windows **Using Binary** 1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip 2. Extract the ZIP file 3. Add the directory to your PATH environment variable 4. Open new Command Prompt or PowerShell 5. Verify: `aliyun version` **Using PowerShell** ```powershell # Download Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip" # Extract Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli # Add to PATH (requires admin privileges) $env:Path += ";C:\aliyun-cli" [Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::Machine) # Verify aliyun version ``` ## Configuration ### Quick Start ```bash aliyun configure set \ --mode AK \ --access-key-id \ --access-key-secret \ --region cn-hangzhou ``` All `aliyun configure` commands support non-interactive flags, which is the recommended approach — it works in scripts, CI/CD pipelines, and agent-driven automation without hanging on stdin prompts. **Where to Get Access Keys** 1. Log in to Aliyun Console: https://ram.console.aliyun.com/ 2. Navigate to: AccessKey Management 3. Create a new AccessKey pair 4. Save the secret immediately — it's only shown once ### Configuration Modes Aliyun CLI supports 6 authentication modes. All examples below use non-interactive flags. #### 1. AK Mode (Access Key) Most common mode for personal accounts and scripts. ```bash aliyun configure set \ --mode AK \ --access-key-id LTAI5tXXXXXXXX \ --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \ --region cn-hangzhou ``` Configuration is stored in `~/.aliyun/config.json`: ```json { "current": "default", "profiles": [ { "name": "default", "mode": "AK", "access_key_id": "LTAI5tXXXXXXXX", "access_key_secret": "8dXXXXXXXXXXXXXXXXXXXXXXXX", "region_id": "cn-hangzhou", "output_format": "json", "language": "en" } ] } ``` #### 2. StsToken Mode (Temporary Credentials) For short-lived access (tokens expire in 1-12 hours). ```bash aliyun configure set \ --mode StsToken \ --access-key-id LTAI5tXXXXXXXX \ --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \ --sts-token v1.0:XXXXXXXXXXXXXXXX \ --region cn-hangzhou ``` Use cases: CI/CD pipelines, temporary access for external contractors, cross-account access. #### 3. RamRoleArn Mode (Assume RAM Role) Assume a RAM role for elevated or cross-account access. ```bash aliyun configure set \ --mode RamRoleArn \ --access-key-id LTAI5tXXXXXXXX \ --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \ --ram-role-arn acs:ram::123456789012:role/AdminRole \ --role-session-name my-session \ --region cn-hangzhou ``` Use cases: cross-account resource access, temporary elevated privileges, role-based access control. #### 4. EcsRamRole Mode (ECS Instance RAM Role) Use the RAM role attached to an ECS instance — no credentials needed. ```bash aliyun configure set \ --mode EcsRamRole \ --ram-role-name MyEcsRole \ --region cn-hangzhou ``` Requirements: must be running on an ECS instance with a RAM role attached. Use cases: scripts and automation running on ECS instances. #### 5. RsaKeyPair Mode (RSA Key Pair) Use RSA key pair for authentication (generate key pair in Aliyun Console first). ```bash aliyun configure set \ --mode RsaKeyPair \ --private-key /path/to/private-key.pem \ --key-pair-name my-key-pair \ --region cn-hangzhou ``` #### 6. RamRoleArnWithEcs Mode (ECS + RAM Role) Combine ECS instance role with RAM role assumption for cross-account access from ECS. ```bash aliyun configure set \ --mode RamRoleArnWithEcs \ --ram-role-name MyEcsRole \ --ram-role-arn acs:ram::123456789012:role/TargetRole \ --role-session-name my-session \ --region cn-hangzhou ``` ### Environment Variables **Highest priority** - overrides config file **Access Key Mode** ```bash export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret export ALIBABA_CLOUD_REGION_ID=cn-hangzhou ``` **STS Token Mode** ```bash export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret export ALIBABA_CLOUD_SECURITY_TOKEN=your_sts_token export ALIBABA_CLOUD_REGION_ID=cn-hangzhou ``` **ECS RAM Role Mode** ```bash export ALIBABA_CLOUD_ECS_METADATA=role_name ``` **Use Case**: - CI/CD pipelines - Docker containers - Temporary credential override ### Managing Multiple Profiles **Create Named Profiles** ```bash aliyun configure set --profile projectA \ --mode AK \ --access-key-id LTAI5tAAAAAAAA \ --access-key-secret 8dAAAAAAAAAAAAAAAAAAAAAAAA \ --region cn-hangzhou aliyun configure set --profile projectB \ --mode AK \ --access-key-id LTAI5tBBBBBBBB \ --access-key-secret 8dBBBBBBBBBBBBBBBBBBBBBBBB \ --region cn-shanghai ``` **Use Specific Profile** ```bash aliyun ecs describe-instances --profile projectA export ALIBABA_CLOUD_PROFILE=projectA aliyun ecs describe-instances # Uses projectA ``` **List and Switch Profiles** ```bash aliyun configure list # List all profiles aliyun configure set --current projectA # Switch default profile ``` ### Credential Priority Credentials are loaded in this order (first found wins): 1. **Command-line flag**: `--profile ` 2. **Environment variable**: `ALIBABA_CLOUD_PROFILE` 3. **Environment credentials**: `ALIBABA_CLOUD_ACCESS_KEY_ID`, etc. 4. **Configuration file**: `~/.aliyun/config.json` (current profile) 5. **ECS Instance RAM Role**: If running on ECS with attached role ## Verification ### Test Authentication ```bash # Basic test - list regions aliyun ecs describe-regions # Expected output: JSON array of regions ``` **If successful**, you'll see: ```json { "Regions": { "Region": [ { "RegionId": "cn-hangzhou", "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com", "LocalName": "华东 1（杭州）" }, ... ] }, "RequestId": "..." } ``` **If failed**, you'll see error messages: - `InvalidAccessKeyId.NotFound` - Wrong Access Key ID - `SignatureDoesNotMatch` - Wrong Access Key Secret - `InvalidSecurityToken.Expired` - STS token expired (for StsToken mode) - `Forbidden.RAM` - Insufficient permissions ### Debug Configuration ```bash # Show current configuration aliyun configure get # Test with debug logging aliyun ecs describe-regions --log-level=debug # Check credential provider aliyun configure get mode ``` ## Security Best Practices ### 1. Use RAM Users (Not Root Account) ❌ **Don't**: Use Aliyun root account credentials ✅ **Do**: Create RAM users with specific permissions ```bash # Create RAM user in console # Attach only necessary policies # Use RAM user's access keys ``` ### 2. Principle of Least Privilege Grant only the minimum permissions needed: ```bash # Example: Read-only ECS access # Attach policy: AliyunECSReadOnlyAccess ``` ### 3. Rotate Access Keys Regularly ```bash # Create new access key in RAM Console, then update configuration aliyun configure set --access-key-id NEW_KEY --access-key-secret NEW_SECRET # Delete old access key from console ``` ### 4. Use STS Tokens for Temporary Access ```bash aliyun configure set --mode StsToken \ --access-key-id XXXX --access-key-secret XXXX \ --sts-token XXXX --region cn-hangzhou ``` ### 5. Use ECS RAM Roles When Possible ```bash aliyun configure set --mode EcsRamRole --ram-role-name MyRole --region cn-hangzhou ``` ### 6. Never Commit Credentials ```bash # Add to .gitignore echo "~/.aliyun/config.json" >> .gitignore # Use environment variables in CI/CD instead ``` ### 7. Secure Config File ```bash # Restrict permissions chmod 600 ~/.aliyun/config.json ``` ## Troubleshooting ### Issue: Command Not Found ```bash # Check installation which aliyun # Check PATH echo $PATH # Reinstall or add to PATH ``` ### Issue: Authentication Failed ```bash # Verify configuration aliyun configure get # Test with debug aliyun ecs describe-regions --log-level=debug # Check credentials in console # Verify access key is active ``` ### Issue: Permission Denied ```bash # Error: Forbidden.RAM # Check RAM user permissions # Attach necessary policies in RAM console # Example: AliyunECSFullAccess for ECS operations ``` ### Issue: STS Token Expired ```bash # Error: InvalidSecurityToken.Expired # Reconfigure with new token aliyun configure set --mode StsToken \ --access-key-id XXXX --access-key-secret XXXX \ --sts-token NEW_TOKEN --region cn-hangzhou ``` ### Issue: Wrong Region ```bash # Some resources may not exist in the specified region # Check available regions aliyun ecs describe-regions # Update default region aliyun configure set region cn-shanghai ``` ## Advanced Configuration ### Custom Endpoint ```bash # Use custom or private endpoint export ALIBABA_CLOUD_ECS_ENDPOINT=ecs-vpc.cn-hangzhou.aliyuncs.com ``` ### Proxy Settings ```bash # HTTP proxy export HTTP_PROXY=http://proxy.example.com:8080 export HTTPS_PROXY=http://proxy.example.com:8080 # No proxy for specific domains export NO_PROXY=localhost,127.0.0.1,.aliyuncs.com ``` ### Timeout Settings ```bash # Connection timeout (default: 10s) export ALIBABA_CLOUD_CONNECT_TIMEOUT=30 # Read timeout (default: 10s) export ALIBABA_CLOUD_READ_TIMEOUT=30 ``` ## Next Steps After installation and configuration: 1. **Install plugins** for services you need (v3.3.3+ supports all published product plugins): ```bash aliyun plugin install --names ecs vpc rds # List all available plugins aliyun plugin list-remote ``` 2. **Explore commands**: ```bash aliyun ecs --help aliyun fc --help ``` 3. **Read documentation**: - [Command Syntax Guide](./command-syntax.md) - [Global Flags Reference](./global-flags.md) - [Common Scenarios](./common-scenarios.md) ## References - Official Documentation: https://help.aliyun.com/zh/cli/ - RAM Console: https://ram.console.aliyun.com/ - Access Key Management: https://ram.console.aliyun.com/manage/ak - Plugin Repository: https://github.com/aliyun/aliyun-cli FILE:references/install-scenarios.md # Installation Scenario Detailed Steps ## TOC - [Scenario 1: Alibaba Cloud ECS Onboarding](#scenario-1-alibaba-cloud-ecs-onboarding) - [Scenario 2: On-Premises IDC Direct Connection](#scenario-2-on-premises-idc-direct-connection) - [Scenario 3: Image-Based Batch Installation](#scenario-3-image-based-batch-installation) - [Scenario 4: Network Troubleshooting](#scenario-4-network-troubleshooting) --- ## Scenario 1: Alibaba Cloud ECS Onboarding ### Step 1: Get User's ECS Information Ask the user for ECS details (instance ID, IP address, region, etc.), then query instance status: ```bash aliyun ecs describe-instances --region --biz-region-id --instance-ids '[""]' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` > **[MUST] ECS API Region parameter rules**: > - The parameter name is `--biz-region-id` (NOT `--RegionId`, `--region-id`, or `--Region`). Using the wrong parameter name causes `unknown flag` errors. > - When the region comes from a SAS `describe-cloud-center-instances` response, use the `RegionId` field (e.g. `cn-hangzhou`), NOT the `Region` field (e.g. `cn-hangzhou-dg-a01`). The `Region` field contains the physical availability zone identifier which is not recognized by standard ECS APIs and causes `InvalidInstance.NotFound` or `RegionId.ApiNotSupported` errors. > - **[MUST] Endpoint routing**: When the target instance's region differs from the CLI's default configured region, you MUST also add `--region ` to route the request to the correct ECS endpoint. `--biz-region-id` only sets the RegionId parameter in the request body but does NOT change the API endpoint. Without `--region`, the request goes to the default region's endpoint and returns `InvalidOperation.NotSupportedEndpoint`. Example: `aliyun ecs describe-instances --region cn-hangzhou --biz-region-id cn-hangzhou ...` > - These rules apply to ALL ECS API calls in this skill: `describe-instances`, `describe-cloud-assistant-status`, `run-command`, `describe-invocation-results`. ### Step 2: Query Client Status ```bash aliyun sas describe-cloud-center-instances --criteria '[{"name":"instanceId","value":""}]' --machine-types ecs --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Evaluate based on `ClientStatus` and `ClientSubStatus`: - **Instance not found** -> Execute `refresh-assets` to sync assets, then re-query: ```bash aliyun sas refresh-assets --asset-type ecs --vendor 0 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` - **`ClientStatus` = `online`** -> Inform the user this ECS is already onboarded and online; no action needed. - **`ClientStatus` = `offline`, `ClientSubStatus` = `uninstalled`** -> Agent was never installed; proceed to Step 3. - **`ClientStatus` = `offline`, `ClientSubStatus` is not `uninstalled`** (empty or other values) -> Agent is installed but offline. Suggest: 1. Check network connectivity (refer to Scenario 4) 2. Check if agent processes exist 3. If unable to self-resolve, recommend submitting a support ticket - **Not installed** (ClientStatus is empty or missing) -> Proceed to Step 3 ### Step 3: Get or Create Install Code Follow the "Common Flow: Get or Create Install Code" in SKILL.md. Recommended matching criteria: Os matches the ECS system, VendorName=ALIYUN, OnlyImage=false. ### Step 4: Determine Installation Method Query cloud assistant status: ```bash aliyun ecs describe-cloud-assistant-status --region --biz-region-id --instance-id "" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Cloud assistant online** (`CloudAssistantStatus=true`) -> Display install command content, dispatch remotely via cloud assistant after confirmation: Linux: ```bash aliyun ecs run-command \ --region \ --biz-region-id \ --type RunShellScript \ --command-content "" \ --instance-id "" \ --content-encoding Base64 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Windows: ```bash aliyun ecs run-command \ --region \ --biz-region-id \ --type RunPowerShellScript \ --command-content "" \ --instance-id "" \ --content-encoding Base64 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Cloud assistant not online** -> Display install command and guide the user to log into the server and execute manually: Linux (root privileges, Alibaba Cloud internal network): ```bash wget "https://update2.aegis.aliyun.com/download/install/2.0/linux/AliAqsInstall.sh" && chmod +x AliAqsInstall.sh && ./AliAqsInstall.sh -k= ``` Windows CMD (administrator privileges, Alibaba Cloud internal network): ```cmd powershell -executionpolicy bypass -c "(New-Object Net.WebClient).DownloadFile('https://update2.aegis.aliyun.com/download/install/2.0/windows/AliAqsInstall.exe', $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath('.\AliAqsInstall.exe'))"; "./AliAqsInstall.exe -k=" ``` Windows PowerShell (administrator privileges, Alibaba Cloud internal network): ```powershell (New-Object Net.WebClient).DownloadFile('https://update2.aegis.aliyun.com/download/install/2.0/windows/AliAqsInstall.exe', $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath('.\AliAqsInstall.exe')); ./AliAqsInstall.exe -k= ``` > Alibaba Cloud ECS defaults to internal network access (`update2.aegis.aliyun.com`). For public network access, replace the download domain with `aegis.alicdn.com`. > **Installation process note**: The install command takes some time to execute. Intermediate error messages during the process can be ignored. Success is determined by the final output -- as long as it shows installation succeeded, the process is complete. ### Step 5: Verify Onboarding Guide the user to wait approximately 5 minutes, then re-query client status to confirm it is online. --- ## Scenario 2: On-Premises IDC Direct Connection ### Step 1: Get or Create Install Code Follow the "Common Flow: Get or Create Install Code". Recommended matching criteria: Os matches user's server system, VendorName auto-determined by network type (leased line=ALIYUN, public=OTHER), OnlyImage=false. ### Step 2: Provide Install Command Select the appropriate install command based on network situation (refer to `agent-install-guide.md`): - **Public network direct** -> Standard install command - **Leased line access** -> Install command using internal domain - **Overseas / unstable network** -> Install command using overseas domain Display the full command and guide the user to execute with admin privileges. ### Step 3: Verify Onboarding Ask the user to provide the installed server's IP, then query status: ```bash aliyun sas describe-cloud-center-instances --criteria '[{"name":"internetIp","value":""}]' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` If not found, sync assets first then retry: ```bash aliyun sas refresh-assets --asset-type ecs --vendor 1 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` --- ## Scenario 3: Image-Based Batch Installation ### Step 1: Confirm Template Server Info Ask the user to confirm: template server instance ID/IP/region, OS, server type, network access method. Remind the user: - Template server must be a **clean environment**; close third-party security software (antivirus/EDR) beforehand - If the agent was previously installed, **uninstall and clean residual directories** first: - Linux: `/usr/local/aegis` - Windows: `C:\Program Files (x86)\Alibaba\Aegis` ### Step 2: Get or Create Image-Specific Install Code Follow the "Common Flow: Get or Create Install Code". Recommended matching criteria: Os matches template server system, VendorName matches server type, `OnlyImage=true`. ### Step 3: Provide Install Command with Critical Caveats Select the appropriate install command based on network access method (refer to `agent-install-guide.md`). Display the full command and **emphasize these key points**: 1. Execute the install command on the template server with admin privileges 2. The command **only downloads files without starting the service** (`OnlyImage=true` install code achieves this) 3. **Shut down immediately after execution -- do not restart the template server** 4. Create a custom image from this server 5. New instances created from this image will automatically activate the agent and generate a unique ID on first boot ### Step 4: Important Warnings Clearly inform the user about these risks: - If making multiple images from the same template, each time you must **re-uninstall, clean, get new install code, and re-execute the install command** -- otherwise UUID conflicts will occur - After executing the install command on the template server, it can **only be shut down**, never restarted, because restarting activates the agent and occupies the UUID - If the template server is accidentally restarted, uninstall the agent, clean residual directories, get a new install code, and redo the process ### Step 5: Verify Onboarding After the new instance created from the image boots up, wait approximately 5 minutes. Once the user provides the new instance info, query client status: ```bash aliyun sas describe-cloud-center-instances --criteria '[{"name":"instanceId","value":""}]' --machine-types ecs --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` --- ## Scenario 4: Network Troubleshooting ### Required Network Access Servers must reach the Security Center service endpoint via TCP port 80: | Domain | VIP | Description | |--------|-----|-------------| | jsrv.aegis.aliyun.com | 47.117.157.227, 8.153.161.116, 8.153.86.12, 106.14.18.21 | China mainland public domain | | jsrv2.aegis.aliyun.com | 100.100.30.25, 100.100.30.26 | China mainland Alibaba Cloud internal (leased line) domain | ### Network Connectivity Test Commands ```bash telnet jsrv.aegis.aliyun.com 80 telnet update.aegis.aliyun.com 443 ``` ### Common Causes - Firewall / security group not allowing outbound traffic - DNS unable to resolve domain - Server cannot access public network and no leased line configured ### Further Troubleshooting - Check agent processes: `ps -ef | grep -E 'AliYunDun|YunDunMonitor'` - Check logs: `/usr/local/aegis/aegis_client/aegis_12_xx/data/` - If unable to self-resolve, recommend submitting a support ticket FILE:references/manage-scenarios.md # Management and Query Scenario Detailed Steps ## TOC - [Scenario 5: Query Version and Feature Info](#scenario-5-query-version-and-feature-info) - [Scenario 6: Query or Modify Asset Authorization](#scenario-6-query-or-modify-asset-authorization) - [Scenario 7: Query Assets with Specific Software](#scenario-7-query-assets-with-specific-software) - [Scenario 8: Uninstall Security Center Agent](#scenario-8-uninstall-security-center-agent) - [Scenario 9: Security Risk Detection and Query](#scenario-9-security-risk-detection-and-query) - [General Reference: Version Number Mapping](#general-reference-version-number-mapping) - [General Reference: Pay-As-You-Go Module Codes](#general-reference-pay-as-you-go-module-codes) - [General Reference: Cost Estimation Methods](#general-reference-cost-estimation-methods) --- ## Scenario 5: Query Version and Feature Info ### Step 1: Query Version Details ```bash aliyun sas describe-version-config --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Extract and display the following key information: | Info Item | Field | Notes | |-----------|-------|-------| | Current version | `Version` | Subscription version number, see version mapping table below | | Highest version | `HighestVersion` | Highest purchased subscription version | | Instance ID | `InstanceId` | Subscription instance ID | | Authorized cores | `VmCores` | Purchased core quota | | Purchase time | `GmtCreate` | 13-digit timestamp, convert to YYYY-MM-DD HH:mm:ss | | Expiration time | `ReleaseTime` | 13-digit timestamp, convert to YYYY-MM-DD HH:mm:ss | | Pay-as-you-go enabled | `IsPostpay` / `PostPayStatus` | Whether pay-as-you-go is also enabled | | Pay-as-you-go instance ID | `PostPayInstanceId` | Pay-as-you-go instance ID | | Pay-as-you-go protection level | `PostPayHostVersion` | Pay-as-you-go host protection level (version number) | | Pay-as-you-go activation time | `PostPayOpenTime` | 13-digit timestamp, convert to YYYY-MM-DD HH:mm:ss | | Pay-as-you-go modules | `PostPayModuleSwitch` | JSON string, each module's switch status | > Timestamp fields (GmtCreate, ReleaseTime, PostPayOpenTime) are converted to "YYYY-MM-DD HH:mm:ss" format, because raw 13-digit timestamps are unreadable. > Subscription info (InstanceId, HighestVersion, VmCores, GmtCreate, ReleaseTime) is only displayed when a subscription order exists (IsPaidUser=true or InstanceId has a value). > Pay-as-you-go info (PostPayInstanceId, PostPayHostVersion, PostPayOpenTime, PostPayModuleSwitch) is only displayed when pay-as-you-go is enabled (IsPostpay=true). > > **[MUST] `MergedVersion` is a sensitive internal field — NEVER display, output, save, or include it in any response, file, or variable exposed to the user. When processing the `describe-version-config` response, strip `MergedVersion` before any output. Use `Version` and `HighestVersion` instead.** When displaying `PostPayModuleSwitch` module switch statuses, fetch current prices from the billing documentation page. Add "Billing Method" and "Unit Price Reference" columns to the module status table. For disabled modules, only mark "Disabled" without showing price details. Modules that do not support pay-as-you-go (WEB_LOCK, IMAGE_SCAN) are marked "Subscription only". See "Cost Estimation Methods" below for pricing retrieval and module classification. ### Step 2: Query Authorization Usage ```bash aliyun sas get-auth-summary --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Extract and display: | Info Item | Field | Notes | |-----------|-------|-------| | Total authorization quota (cores) | `Machine.TotalCoreCount` | Total core quota | | Bound cores | `Machine.BindCoreCount` | Used core count | | Unbound cores | `Machine.UnBindCoreCount` | Remaining available cores | | Total assets (servers) | `Machine.TotalEcsCount` | Total asset count | | Bound servers | `Machine.BindEcsCount` | Servers with authorization bound | | Version breakdown | `VersionSummary[]` | Quota and usage per version | > Note: GetAuthSummary returns Machine and VersionSummary under the response root object, not wrapped in a Data object. ### Step 3: Query Pay-As-You-Go Serverless Status (on demand) Execute only when the user asks about Serverless / pay-as-you-go feature status: ```bash aliyun sas get-serverless-auth-summary --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Display pay-as-you-go module switch status (`PostPaidModuleSwitch` JSON field), showing each module with its name and switch status in a table. Module codes are listed in the reference table below. Also display SERVERLESS module tiered pricing for reference (prices fetched from billing documentation page). ### Step 4: Modify Pay-As-You-Go Module Switches (on demand) Execute only when the user explicitly requests enabling or disabling a pay-as-you-go feature module. This is a **write operation** requiring confirmation. First obtain `PostPayInstanceId` from Step 1, then: ```bash aliyun sas modify-post-pay-module-switch \ --post-pay-instance-id "" \ --post-pay-module-switch '{"": <0-or-1>}' \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` > Modules not included in the request remain unchanged. #### Cost Estimation (when enabling modules) When the user requests to **enable** a module, include cost estimates in the confirmation details: **Data preparation**: Ensure get-auth-summary data (server cores/count) from Step 2 and billing page prices are available. If Step 2 has not been executed, run it first. Prices are dynamically fetched from the billing documentation (see "Cost Estimation Methods" below). **Display costs by module category** (categories in "Cost Estimation Methods" below): - **Estimable monthly cost modules** (POST_HOST, SERVERLESS): - POST_HOST requires confirming the protection level first, because pricing differs up to 30x between levels. Display level-specific unit prices for the user to choose; if already specified in conversation, use directly - Virus Protection: bound cores x unit price/core/month - Advanced Edition (legacy): bound servers x unit price/server/month. **Only show this option when user's current `PostPayHostVersion` corresponds to Advanced Edition**; otherwise hide it (this version is no longer available for new activation) - Host Comprehensive Protection: bound servers x unit price/server/month - Host & Container Comprehensive Protection: bound servers x unit price/server/month + bound cores x unit price/core/month - SERVERLESS: display tiered ranges, estimate monthly cost based on the tier matching current core count - **Usage-based billing modules** (VUL, CSPM, AGENTLESS, etc.): display unit price and billing unit, note "cost depends on actual usage, monthly fee cannot be estimated" - **Subscription-only modules** (WEB_LOCK, IMAGE_SCAN): inform that pay-as-you-go is not supported, must be purchased via console **Base service fee check**: If all modules in `PostPayModuleSwitch` are currently disabled (value 0), remind the user that the first activation will also incur a base service fee (~0.05 CNY/hour, approx. 36 CNY/month). **Confirmation details**: Display the module to be modified, target status, estimated cost (or unit price reference), note "estimates are based on current asset data; actual fees are subject to the Alibaba Cloud bill". Execute after user confirmation. --- ## Scenario 6: Query or Modify Asset Authorization ### Step 1: Query Asset Current Status Obtain the server identifier from the user (instance ID, IP, name, etc.) and query asset info: ```bash aliyun sas describe-cloud-center-instances \ --criteria '[{"name":"instanceId","value":""}]' \ --page-size 20 --current-page 1 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Extract and display: | Info Item | Field | Notes | |-----------|-------|-------| | Instance ID | `InstanceId` | Server instance ID | | Instance name | `InstanceName` | Server name | | UUID | `Uuid` | Asset UUID (used for bind/unbind) | | Client status | `ClientStatus` | online / offline | | Current auth version | `AuthVersion` | Currently bound version number | | Auth modification time | `AuthModifyTime` | Last auth change timestamp | | OS | `Os` | Operating system type | | Asset type | `MachineType` | ecs / cloud_vm etc. | | Cluster ID | `ClusterId` | K8s/ACK cluster ID (if applicable) | ### Step 2: Confirm Operation Type and Billing Mode - **View authorization**: Step 1 is sufficient; display results directly - **Bind/upgrade authorization**: - If subscription order exists (`IsPaidUser=true` or `InstanceId` has value) -> Step 3 (subscription binding) - If only pay-as-you-go (`IsPostpay=true` with no subscription) -> Step 4 (pay-as-you-go binding) - If both exist, ask which billing mode the user wants - **Unbind authorization (subscription)**: Go to Step 3 - **Unbind / downgrade to free version (pay-as-you-go)**: Go to Step 4 - **Change pay-as-you-go version**: Go to Step 4 ### Step 3: Bind or Unbind Authorization (Subscription) **Important constraints** (inform the user, because these operations have irreversible implications): - Under subscription mode, assets bound to any paid version **cannot be unbound within 30 days**; premature unbinding wastes authorization - K8s / ACK cluster assets **only support Ultimate Edition** (Version=7); binding other versions will return an error - Bind/unbind operations use the asset's UUID, not the instance ID #### 3a: Version Selection If the user has not specified a target version, display available versions: | Version | Version Number | Description | |---------|---------------|-------------| | Advanced | 5 | Basic host security protection | | Enterprise | 3 | Enhanced security detection | | Anti-virus | 6 | Virus scanning capabilities | | Ultimate | 7 | Host and container comprehensive protection | > If the user has already specified a version in conversation (e.g. "bind Ultimate"), use the corresponding version number directly without asking again. #### 3b: Secondary Confirmation Display operation details and obtain **explicit confirmation** before executing: ``` About to execute bind operation: - Server name: - Instance ID: - UUID: - Current version: (AuthVersion=) - Target version: (AuthVersion=) - Billing mode: Subscription - Constraint: Cannot unbind within 30 days after binding Proceed? (yes/no) ``` After confirmation, execute binding: ```bash aliyun sas bind-auth-to-machine \ --auth-version \ --bind "" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Unbind authorization (also requires secondary confirmation): ```bash aliyun sas bind-auth-to-machine \ --un-bind "" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` ### Step 4: Change Pay-As-You-Go Version Binding #### 4a: Protection Level Selection and Cost Estimation Pay-as-you-go protection levels differ from the subscription version system. If the user has not specified a protection level, confirm it first by displaying unit prices for each level. **Data preparation**: Ensure `get-auth-summary` has been executed for asset data, and billing page prices have been fetched (see "Cost Estimation Methods" below). Display available protection levels and corresponding costs: | Protection Level | Billing Dimension | Estimated Incremental Cost | |-----------------|-------------------|---------------------------| | Virus Protection | Per core | cores x /core/month | | Advanced (legacy) | Per server | servers x /server/month | | Host Comprehensive | Per server | servers x /server/month | | Host & Container Comprehensive | Per server + per core | x /server/month + x /core/month | > **Advanced Edition is a legacy version**: Only display the "Advanced" option when the user currently holds pay-as-you-go Advanced Edition (check `PostPayHostVersion` from `describe-version-config`). If not held, remove the Advanced row -- this version is no longer available for new activation. > Cost estimates are based on the incremental cost of binding this asset (i.e., the asset's cores/servers x corresponding unit price), not total cost. > If the user has already specified a level in conversation (e.g. "bind Ultimate"), display cost estimates for that level only. > If real-time prices cannot be fetched, display billing dimension descriptions and provide the billing page link. #### 4b: Secondary Confirmation Display operation details and cost estimates, obtain **explicit confirmation** before executing: ``` About to execute pay-as-you-go version binding: - Server name: - Instance ID: - UUID: - Current version: (AuthVersion=) - Target version: (AuthVersion=) - Billing mode: Pay-as-you-go - Estimated incremental cost: x = approx. /month - Disclaimer: Estimates based on current asset data and real-time pricing; actual fees subject to Alibaba Cloud bill Proceed? (yes/no) ``` After confirmation, execute: ```bash aliyun sas update-post-paid-bind-rel \ --bind-action '[{"Version": "", "UuidList": [""]}]' \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` #### 4c: Unbind / Downgrade to Free Version (Pay-as-you-go) If the user requests to downgrade a pay-as-you-go server to free version (unbind authorization), use `update-post-paid-bind-rel` with `Version=1`: Display operation details and obtain **explicit confirmation** before executing: ``` About to downgrade pay-as-you-go server to free version: - Server name: - Instance ID: - UUID: - Current version: (AuthVersion=) - Target version: Free (AuthVersion=1) - Note: Server will lose paid protection features after downgrade Proceed? (yes/no) ``` After confirmation, execute: ```bash aliyun sas update-post-paid-bind-rel \ --bind-action '[{"UuidList": [""], "Version": 1}]' \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` ### Step 5: Verify Change After the operation completes, re-query asset status to confirm the authorization version has changed: ```bash aliyun sas describe-cloud-center-instances \ --criteria '[{"name":"instanceId","value":""}]' \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` --- ## Scenario 7: Query Assets with Specific Software ### Step 1: Confirm Query Conditions Confirm with the user: - **Software name**: The middleware/database/web service name to query (e.g. nginx, mysql, redis) - **Software type** (optional): - `sca` (default): Middleware - `sca_database`: Database - `sca_web`: Web service - **Subtype** (optional): system_service, software_library, docker_component, database, web_container, jar, web_framework ### Step 2: Query Asset Fingerprint ```bash aliyun sas describe-property-sca-detail \ --search-item name \ --search-info "" \ --biz \ --current-page 1 \ --page-size 20 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` > Only pass parameters the user has specified. If --biz is not specified, omit it (defaults to sca). > **Common software type mapping**: Redis, MySQL, PostgreSQL, MongoDB, MariaDB -> `sca_database`; Nginx, Apache, Tomcat -> `sca` (default); if the default type returns no results, retry with other types (`sca_database`, `sca_web`). Extract and display: | Info Item | Field | Notes | |-----------|-------|-------| | Server name | `InstanceName` | Server with the software installed | | Instance ID | `InstanceId` | Server instance ID | | Public IP | `InternetIp` | Public IP address | | Private IP | `IntranetIp` | Private IP address | | Software name | `Name` | Detected software name | | Software version | `Version` | Software version number | | Listening port | `Port` | Process listening port | | Process ID | `Pid` | Running process ID | | Running user | `User` | Process owner | If `TotalCount` exceeds the current `PageSize`, inform the user there are more results and ask whether to view the next page. ### Step 3: Query Detailed Asset Info (on demand) If the user needs further information about a server's client status, authorization version, etc.: ```bash aliyun sas describe-cloud-center-instances \ --criteria '[{"name":"instanceId","value":""}]' \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` --- ## Scenario 8: Uninstall Security Center Agent ### Step 1: Get Target Server Info Obtain the server identifier from the user (instance ID, IP, name, etc.) and query asset info to get the UUID: ```bash aliyun sas describe-cloud-center-instances \ --criteria '[{"name":"instanceName","value":""}]' \ --page-size 20 --current-page 1 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Extract and display: | Info Item | Field | Notes | |-----------|-------|-------| | Instance name | `InstanceName` | Server name | | UUID | `Uuid` | Unique identifier required for uninstall | | Client status | `ClientStatus` | online / offline / pause | | OS | `Os` | Operating system type | | Public IP | `InternetIp` | Public IP address | | Private IP | `IntranetIp` | Private IP address | | Asset type | `MachineType` | ecs / cloud_vm etc. | ### Step 2: Display Uninstall Details and Confirm Display the server information to be uninstalled in table format, with warnings: **Uninstall confirmation info**: - Server name: {InstanceName} - UUID: {Uuid} - Current client status: {ClientStatus} - OS: {Os} **Important warnings** (must inform user): - After uninstalling, the server will **lose all Security Center protection capabilities**, including intrusion detection, vulnerability scanning, baseline checks, etc. - Client status must be `online` to execute uninstall; offline agents cannot be uninstalled via this API > This is a write operation; explicit user confirmation is required before execution. ### Step 3: Execute Uninstall After confirmation, execute the uninstall command: ```bash aliyun sas add-uninstall-clients-by-uuids \ --uuids "" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` To uninstall multiple servers simultaneously, separate UUIDs with commas: ```bash aliyun sas add-uninstall-clients-by-uuids \ --uuids "," \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` ### Step 4: Verify Uninstall Result Wait approximately 30 seconds, then re-query asset status to confirm the agent has been uninstalled: ```bash aliyun sas describe-cloud-center-instances \ --criteria '[{"name":"uuid","value":""}]' \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Check if `ClientStatus` has changed to `offline` or if the asset has been removed from the list. --- ## Scenario 9: Security Risk Detection and Query > **[HARD GATE] ALL scan dispatch operations in this scenario are host-based (agent-dependent).** The target server's Security Center agent MUST be `ClientStatus=online` before ANY scan can be dispatched. If the agent is not installed or offline, scans CANNOT execute and WILL produce NO results. There is NO agentless scanning mode. Do NOT bypass this requirement under any circumstances — guide the user to install or bring the agent online first. > > Additionally, the target server MUST be bound to a paid authorization version (`AuthVersion > 1`). Free version servers (`AuthVersion <= 1`) cannot be scanned. > > **Exception**: Querying existing risk results (Step 2: describe-grouped-vul, list-check-item-warning-summary, describe-susp-events) is a READ operation that retrieves historical data from Security Center's database. This does NOT trigger new scans, does NOT require the agent to be online, and does NOT require paid authorization. ### Step 1: Confirm Detection Type Route to the corresponding sub-flow based on user intent: - User wants to **view existing risk results** (vulnerabilities, baseline, alerts) -> Step 2 - User wants to **trigger a new security scan** -> Step 3 - User vaguely says "detect security risks" -> Ask whether to view existing results or trigger a new scan ### Step 2: Query Risk Results Execute the corresponding query based on the risk types the user is interested in. Multiple types can be queried simultaneously. #### 2a: Query Vulnerability Risks ```bash aliyun sas describe-grouped-vul \ --type cve \ --dealed n \ --current-page 1 \ --page-size 20 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Vulnerability type (--type) options: - `cve`: Linux vulnerabilities - `sys`: Windows vulnerabilities - `cms`: Web-CMS vulnerabilities - `app`: Application vulnerabilities (scanning) - `sca`: Application vulnerabilities (composition analysis) Extract and display: | Info Item | Field | Notes | |-----------|-------|-------| | Vulnerability name | `AliasName` | Vulnerability alias | | Vulnerability type | `Type` | cve / sys / cms / app / sca | | High priority count | `AsapCount` | Count requiring urgent fix | | Medium priority count | `LaterCount` | Count that can be fixed later | | Low priority count | `NntfCount` | Count that can be ignored for now | | Handled count | `HandledCount` | Vulnerabilities already handled | | First discovered | `GmtFirst` | 13-digit timestamp, convert to readable format | | Last discovered | `GmtLast` | 13-digit timestamp, convert to readable format | | Related CVEs | `Related` | Associated CVE identifiers | | Tags | `Tags` | e.g. "Remote Exploit", "Code Execution" | If `TotalCount` exceeds `PageSize`, notify that more results are available. #### 2b: Query Baseline Risks ```bash aliyun sas list-check-item-warning-summary \ --check-warning-status 1 \ --current-page 1 \ --page-size 20 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Risk status (--check-warning-status) options: 1=Failed, 3=Passed, 6=Whitelisted, 8=Fixed. Extract and display: | Info Item | Field | Notes | |-----------|-------|-------| | Check item | `CheckItem` | Check item description | | Risk level | `CheckLevel` | high / medium / low | | Check category | `CheckType` | Check item classification | | Affected machines | `WarningMachineCount` | Servers that failed this check | | Remediation advice | `Advice` | Check item recommendation | | Description | `Description` | Check item details | Can filter by specific level via `--check-level` parameter (e.g. high-risk only: `--check-level high`). #### 2c: Query Security Alerts ```bash aliyun sas describe-susp-events \ --dealed N \ --current-page 1 \ --page-size 20 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Optional filter parameters: - `--levels`: Alert level (serious=critical, suspicious=suspicious, remind=informational) - `--parent-event-types`: Alert types (e.g. abnormal process behavior, webshell, abnormal login) - `--uuids`: Specific server UUID Extract and display: | Info Item | Field | Notes | |-----------|-------|-------| | Alert name | `AlarmEventNameDisplay` | Alert display name | | Alert type | `AlarmEventTypeDisplay` | Alert type display name | | Severity level | `Level` | serious / suspicious / remind | | Affected instance | `InstanceName` | Server name | | Public IP | `InternetIp` | Associated instance public IP | | Private IP | `IntranetIp` | Associated instance private IP | | First occurrence | `OccurrenceTime` | First occurrence time | | Last occurrence | `LastTime` | Last occurrence time | | Event status | `EventStatus` | 1=Pending, 4=Confirmed, 32=Handled | | Description | `Desc` | Alert event impact summary | ### Step 3: Trigger Security Scan (Write Operations) > **Reminder: ALL scans below are host-based and agent-dependent.** Before dispatching ANY scan task, the target server(s) MUST have `ClientStatus=online` AND `AuthVersion > 1`. If either condition is not met, do NOT dispatch the scan. The prerequisite check flows below enforce this gate. All operations below are **write operations** requiring operation details display and user confirmation before execution. **Dispatch strategy**: - **User specified target assets** (targeted scan): Use `modify-push-all-task` uniformly with the target UUID, which includes vulnerability scan, baseline check, asset fingerprint collection and other check items. Prerequisites chain (authorization + client) must be completed first. **[HARD GATE] NEVER use `modify-start-vul-scan` for targeted scans — it is a global command that scans ALL servers in the entire account, not just the target. Using it for a single-server scan is a critical error.** - **User did not specify target assets** (full scan): First run full asset prerequisite check (client online + authorization bound), then use separate scan commands (modify-start-vul-scan, exec-strategy, generate-once-task, create-virus-scan-once-task) #### 3a: Targeted Asset Scan (Fully Automated Flow) When the user specifies a particular server for security scanning, follow this prerequisite chain automatically. **Only pause for confirmation when paid authorization binding is needed; all other steps are automated**. > **[HARD GATE] Command selection**: In this entire 3a flow, use ONLY `modify-push-all-task` for vulnerability/baseline/fingerprint scanning. Do NOT call `modify-start-vul-scan` under any circumstances — it is a global full-scan command reserved exclusively for flow 3b. ##### Prerequisite Chain Flow ``` Query asset -> Check auth version -> [Need binding? -> Show cost -> User confirms] -> Check client -> [Need install? -> Auto install -> Wait online] -> Dispatch scan ``` ##### Check 1: Query Asset Info ```bash aliyun sas describe-cloud-center-instances \ --criteria '[{"name":"instanceName","value":""}]' \ --page-size 20 --current-page 1 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Extract key fields: `Uuid`, `InstanceId`, `AuthVersion`, `ClientStatus`, `ClientSubStatus`, `Os`, `Cores`, `RegionId` > **[MUST] Region field distinction**: The SAS response contains both `Region` (e.g. `cn-hangzhou-dg-a01`, physical availability zone) and `RegionId` (e.g. `cn-hangzhou`, standard API region). When calling ECS APIs later (describe-cloud-assistant-status, run-command, describe-invocation-results), always use the `RegionId` field. Using `Region` causes `InvalidInstance.NotFound` or `RegionId.ApiNotSupported` errors because dedicated sub-zones are not recognized by standard ECS API endpoints. The ECS API parameter name is `--biz-region-id` (NOT `--RegionId` or `--region-id`). **Additionally, when the target region differs from the CLI's default configured region, you MUST also add `--region ` to route the request to the correct ECS endpoint** — `--biz-region-id` only sets the request body parameter, not the endpoint routing. ##### Check 2: Authorization Version Check Based on `AuthVersion`: - **AuthVersion > 1** (paid version bound) -> Skip, proceed to Check 3 - **AuthVersion = 1 or 0** (free/unauthorized) -> Paid version binding required before scan dispatch; enter binding flow **Binding flow (requires user confirmation)**: 1. Query account version info to confirm available billing modes: ```bash aliyun sas describe-version-config --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` 2. Based on billing mode, display binding options and costs: **a) Subscription mode** (`IsPaidUser=true` or `InstanceId` has value): First query remaining quota: ```bash aliyun sas get-auth-summary --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Display confirmation: ``` Target server is currently on free version; a paid version binding is required to dispatch security scan. Current subscription authorization: - Version: - Remaining quota: cores / servers - Expiration: Will bind authorization for: - Server: () - Target version: (AuthVersion=) - Constraint: Cannot unbind within 30 days Confirm binding? (yes/no) ``` After confirmation, auto-execute: ```bash aliyun sas bind-auth-to-machine --auth-version --bind "" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **b) Pay-as-you-go mode** (`IsPostpay=true` with no subscription): Display protection levels and costs for user selection: | Protection Level | Billing Dimension | Estimated Cost (this asset) | |-----------------|-------------------|-----------------------------| | Virus Protection | Per core | cores x /core/month | | Advanced (legacy) | Per server | 1 server x /server/month | | Host Comprehensive | Per server | 1 server x /server/month | | Host & Container Comprehensive | Per server + per core | 1 server x /server/month + cores x /core/month | > Advanced is a legacy version; only display when `PostPayHostVersion` corresponds to Advanced, otherwise hide. > Prices are dynamically fetched from billing documentation (see "Cost Estimation Methods" below). ``` Target server is currently on free version; a pay-as-you-go version binding is required for security scan. Select a protection level (see table above) to bind for: - Server: () - Estimates based on current asset data; actual fees subject to Alibaba Cloud bill Confirm protection level and binding? ``` After confirmation, auto-execute: ```bash aliyun sas update-post-paid-bind-rel \ --bind-action '[{"Version": "", "UuidList": [""]}]' \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **c) Both billing modes exist**: Display both options for user selection, then follow the corresponding flow. **d) No paid version available**: Inform the user they must first activate a paid Security Center version (subscription purchase or enable pay-as-you-go); provide the console link and terminate the flow. ##### Check 3: Client Status Check Based on `ClientStatus`: - **`ClientStatus` = `online`** -> Skip, proceed to scan dispatch - **`ClientStatus` = `offline` and `ClientSubStatus` = `uninstalled`** -> Agent not installed; enter auto-install flow - **`ClientStatus` = `offline` and `ClientSubStatus` is not `uninstalled`** -> Agent installed but offline; prompt user to check server status and terminate scan flow **Auto-install flow** (no user confirmation needed, executes automatically): 1. Get install code: ```bash aliyun sas describe-install-codes --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Match criteria: Os matches target server, VendorName=ALIYUN, OnlyImage=false 2. Check cloud assistant status: ```bash aliyun ecs describe-cloud-assistant-status --region --biz-region-id --instance-id "" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` 3a. **Cloud assistant online** -> Dispatch install command via cloud assistant: ```bash aliyun ecs run-command \ --region \ --biz-region-id \ --type RunShellScript \ --command-content "" \ --instance-id "" \ --content-encoding Base64 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Install command (Linux internal): ``` wget "https://update2.aegis.aliyun.com/download/install/2.0/linux/AliAqsInstall.sh" && chmod +x AliAqsInstall.sh && ./AliAqsInstall.sh -k= ``` Windows internal (RunPowerShellScript): ``` (New-Object Net.WebClient).DownloadFile('https://update2.aegis.aliyun.com/download/install/2.0/windows/AliAqsInstall.exe', $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath('.\AliAqsInstall.exe')); ./AliAqsInstall.exe -k= ``` > Installation takes time; intermediate error messages can be ignored; success is determined by the final output. 4. Wait for installation to complete, query execution results: ```bash aliyun ecs describe-invocation-results --region --biz-region-id --invoke-id "" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Poll until `InvocationStatus` is no longer `Running` (recommended 30-second interval); confirm final status is `Success`. 5. After successful installation, wait approximately 10 seconds for the agent to come online, then re-query client status to confirm `ClientStatus=online`. 3b. **Cloud assistant not online** -> Cannot auto-install; display install command for user to execute manually and terminate the automated flow: ``` Cloud assistant is not online; cannot auto-install the agent. Please log into the server and manually execute: Initiate scanning again after installation completes. ``` ##### Checks Passed -> Dispatch Scan After all prerequisite checks pass (confirmed: `ClientStatus=online` AND `AuthVersion > 1`), automatically dispatch scan tasks (no additional confirmation needed, because the user explicitly requested scanning initially): > **Final gate**: Do NOT reach this point unless Check 2 (authorization) and Check 3 (client online) have both passed. If the client is still offline or unauthorized, go back and resolve those issues first. > **[HARD GATE] Targeted scan command restriction**: In this targeted scan flow, use ONLY `modify-push-all-task` (with the target UUID) for vulnerability/baseline/fingerprint scanning. NEVER call `modify-start-vul-scan` — it is a global full-scan command that scans ALL servers account-wide, not just the target. `modify-start-vul-scan` is reserved exclusively for the full-scan flow (3b). **a) Security check (modify-push-all-task)**: **Baseline detection prerequisite**: Before dispatching the security check, evaluate whether to include baseline detection (`HEALTH_CHECK`) based on `describe-version-config` data from Check 2: - **Either condition met** -> Tasks **include** `HEALTH_CHECK`: - Pre-paid host protection version: `Version > 1` (i.e. Advanced/Enterprise/Anti-virus/Ultimate purchased) - Cloud Security Posture Management enabled: `PostPayModuleSwitch` JSON has `CSPM` value `1` - **Neither met** -> **Remove** `HEALTH_CHECK` from Tasks, and explain: "Pre-paid host protection version not activated and CSPM not enabled; skipping baseline detection" Tasks with baseline detection: ```bash aliyun sas modify-push-all-task \ --uuids "" \ --tasks "OVAL_ENTITY,CMS,SYSVUL,SCA,HEALTH_CHECK,WEBSHELL,PROC_SNAPSHOT,PORT_SNAPSHOT,ACCOUNT_SNAPSHOT,SOFTWARE_SNAPSHOT,SCA_SNAPSHOT" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Tasks without baseline detection: ```bash aliyun sas modify-push-all-task \ --uuids "" \ --tasks "OVAL_ENTITY,CMS,SYSVUL,SCA,WEBSHELL,PROC_SNAPSHOT,PORT_SNAPSHOT,ACCOUNT_SNAPSHOT,SOFTWARE_SNAPSHOT,SCA_SNAPSHOT" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **b) Virus scan (create-virus-scan-once-task)**: > **[MUST] Parameter format**: The `--business-type` parameter must be the exact string `"VIRUS_SCAN_ONCE_TASK"`. Do NOT use numeric codes (1, 3, 4, etc.) — they will return 400 `illegal businessType`. Execute the following 4 steps in sequence: 1. Create asset selection configuration: ```bash aliyun sas create-asset-selection-config \ --business-type "VIRUS_SCAN_ONCE_TASK" \ --target-type "instance" \ --platform "all" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Record the returned `SelectionKey`. 2. Add target asset to selection configuration: ```bash aliyun sas add-asset-selection-criteria \ --selection-key "" \ --target-operation-list Target="" Operation=add \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` > Multiple servers can be added by repeating `--target-operation-list Target= Operation=add`. 3. Associate selection configuration to virus scan business: ```bash aliyun sas update-selection-key-by-type \ --business-type "VIRUS_SCAN_ONCE_TASK" \ --selection-key "" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` 4. Create virus scan task: ```bash aliyun sas create-virus-scan-once-task \ --scan-type "system" \ --selection-key "" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` > --scan-type values: `system` (system scan, scans all critical paths), `user` (custom scan, requires additional --scan-path). Default is `system`. ##### Full Flow Output Example The agent should display progress to the user in real-time during execution: ``` [1/6] Querying asset info... Done. Found shucang-test (i-bp1xxx) [2/6] Checking auth version... Done. Ultimate bound (AuthVersion=7) (or: Warning: Currently free version, paid binding needed -> Show confirmation) [3/6] Checking client status... Done. Client online (or: Warning: Client not installed, auto-installing...) [4/6] Installing agent... Done. (Install success) [5/6] Dispatching security check... Done. Vulnerability scan/baseline check/fingerprint tasks dispatched (or: Done. Vulnerability scan/fingerprint tasks dispatched (pre-paid version/CSPM not enabled, baseline detection skipped)) [6/6] Dispatching virus scan... Done. Virus scan task dispatched Scan results will be available in approximately 5 minutes; you can then query vulnerability/baseline/alert/virus scan data. ``` #### Full Scan Prerequisite Check (shared by 3b-3e) > **[HARD GATE]** Full scans are also host-based and agent-dependent. Only servers with `ClientStatus=online` AND `AuthVersion > 1` can be scanned. Servers that do not meet BOTH conditions MUST be excluded from scan dispatch. If NO servers meet the conditions, terminate the scan flow entirely. Before full scan, query all asset client and authorization statuses to show the user asset readiness. **Step one: Query all asset statuses** ```bash aliyun sas describe-cloud-center-instances \ --page-size 20 --current-page 1 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` > If `TotalCount` exceeds `PageSize`, paginate until all assets are retrieved. **Step two: Asset classification statistics** Classify each asset by `ClientStatus` and `AuthVersion`: | Category | Condition | Scannable | |----------|-----------|-----------| | Ready | `ClientStatus=online` and `AuthVersion > 1` | Yes | | Unauthorized | `ClientStatus=online` but `AuthVersion <= 1` | No (bind authorization first) | | Client offline | `ClientStatus=offline` | No (bring client online first) | | Client not installed | `ClientStatus=offline` and `ClientSubStatus=uninstalled` | No (install client first) | **Step three: Display asset readiness** Show the user a summary and list of non-scannable assets: ``` Full scan asset readiness check: - Total assets: X servers - Scannable: Y servers (client online + authorization bound) - Not scannable: Z servers - Unauthorized (client online but no paid version): A servers - Client offline/not installed: B servers Non-scannable asset list: | Server Name | Instance ID | Client Status | Auth Version | Reason | |-------------|-------------|---------------|--------------|--------| | ... | ... | ... | ... | Unauthorized/Offline/Not installed | ``` **Step four: Confirm whether to continue** - **All ready** (Z=0): Display confirmation then execute scan - **Partially ready** (Y>0 and Z>0): Inform the user that scanning will only cover the Y ready servers; the Z non-scannable servers need handling first (bind authorization/install client). Ask whether to continue - **None scannable** (Y=0): Inform the user there are no scannable servers; authorization binding and client installation must be completed first. Terminate scan flow > After user confirmation, execute scan tasks 3b-3e in sequence. --- #### 3b: Full Vulnerability Scan (modify-start-vul-scan) Scan all ready servers for vulnerabilities: ```bash aliyun sas modify-start-vul-scan \ --types "cve,sys,cms,app,sca" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` > Omitting --types scans all vulnerability types. #### 3c: Full Baseline Check (exec-strategy) Used when no specific assets are targeted. **Prerequisites**: Baseline detection requires the user to meet either condition; otherwise skip this step and inform the user why: - Pre-paid host protection version: `describe-version-config` returns `Version > 1` (i.e. Advanced/Enterprise/Anti-virus/Ultimate purchased) - Cloud Security Posture Management enabled: `describe-version-config` returns `PostPayModuleSwitch` JSON with `CSPM` value `1` > If neither is met, inform the user: "Pre-paid host protection version not activated and Cloud Security Posture Management (CSPM) not enabled; baseline check cannot be executed. To use baseline detection, purchase a paid Security Center version or enable the pay-as-you-go CSPM module." First query baseline strategy list for user selection. **Step one: Query baseline strategy list** ```bash aliyun sas describe-strategy --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Display strategy list in table format: | Info Item | Field | Notes | |-----------|-------|-------| | Strategy ID | `Id` | StrategyId needed for baseline check execution | | Strategy name | `Name` | Strategy display name | | Strategy type | `CustomType` | common=Standard / custom=Custom | | Check cycle | `CycleDays` | Cycle in days | | Execution window | `StartTime` ~ `EndTime` | Check execution time window | | Associated servers | `EcsCount` | Servers covered by this strategy | | Risk item count | `RiskCount` | Currently detected risk items | | Pass rate | `PassRate` | Baseline check pass rate (%) | > If there is only one strategy, display its info and ask the user whether to use it. **Step two: Execute baseline check after user selection** After the user selects a strategy, execute (write operation, requires confirmation): ```bash aliyun sas exec-strategy \ --strategy-id \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` #### 3d: Full Asset Fingerprint Collection (generate-once-task) Collect asset fingerprints from all ready servers: ```bash aliyun sas generate-once-task \ --task-type "ASSETS_COLLECTION" \ --task-name "ASSETS_COLLECTION" \ --param '{"items":"ACCOUNT_SNAPSHOT,PORT_SNAPSHOT,PROC_SNAPSHOT,SOFTWARE_SNAPSHOT,CROND_SNAPSHOT,SCA_SNAPSHOT,LKM_SNAPSHOT,AUTORUN_SNAPSHOT,SCA_PROXY_SNAPSHOT"}' \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Collection items: - `ACCOUNT_SNAPSHOT`: Account snapshot - `PORT_SNAPSHOT`: Port snapshot - `PROC_SNAPSHOT`: Process snapshot - `SOFTWARE_SNAPSHOT`: Software snapshot - `CROND_SNAPSHOT`: Scheduled task snapshot - `SCA_SNAPSHOT`: Middleware snapshot - `LKM_SNAPSHOT`: Kernel module snapshot - `AUTORUN_SNAPSHOT`: Auto-start item snapshot - `SCA_PROXY_SNAPSHOT`: Proxy middleware snapshot #### 3e: Full Virus Scan (create-virus-scan-once-task) Scan all ready servers for viruses: Execute the following 2 steps in sequence: 1. Create full asset selection configuration: ```bash aliyun sas create-asset-selection-config \ --business-type "VIRUS_SCAN_ONCE_TASK" \ --target-type "all_instance" \ --platform "all" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Record the returned `SelectionKey`. > When `target-type=all_instance`, the selection configuration is automatically associated to the business type. No need to call `update-selection-key-by-type` — that step is only required for targeted single-server scans (`target-type=instance`). 2. Create virus scan task: ```bash aliyun sas create-virus-scan-once-task \ --scan-type "system" \ --selection-key "" \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` #### Virus Scan Result Query Query the latest virus scan task progress: ```bash aliyun sas get-virus-scan-latest-task-statistic --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Key return fields: | Field | Notes | |-------|-------| | `Status` | Task status (10=In progress, 20=Completed) | | `Progress` | Progress percentage | | `ScanMachine` | Machines being scanned | | `CompleteMachine` | Machines completed | | `UnCompleteMachine` | Machines not completed | | `SafeMachine` | Clean machines | | `SuspiciousMachine` | Machines with viruses found | | `SuspiciousCount` | Total viruses found | | `TaskId` | Task ID | Query machines where viruses were found: ```bash aliyun sas list-virus-scan-machine --current-page 1 --page-size 20 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Query virus event details for a specific machine: ```bash aliyun sas list-virus-scan-machine-event \ --uuid "" \ --current-page 1 \ --page-size 20 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` ### Step 4: Poll Task Progress and Query Results After scan tasks are dispatched, **do not use fixed waits**; instead poll the corresponding interfaces for each task's execution status. Recommended polling interval: **30 seconds**. If not completed after **10 minutes**, prompt the user to query manually later. #### 4a: Vulnerability Scan Progress (describe-once-task) ```bash aliyun sas describe-once-task \ --task-type "VUL_CHECK_TASK" \ --current-page 1 \ --page-size 1 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Check the latest task (first item): - `TaskStatusText = "PROCESSING"`: In progress, display `Progress` to user, continue polling - `TaskStatusText != "PROCESSING"`: Completed, proceed to result query #### 4b: Baseline Check Progress (describe-strategy) Only poll if baseline check (exec-strategy) was triggered: ```bash aliyun sas describe-strategy --strategy-ids "" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Check the corresponding strategy's status: - `ExecStatus = 2`: Executing, display `Percent` progress to user, continue polling - `ExecStatus = 1`: Completed, proceed to result query #### 4c: Virus Scan Progress (get-virus-scan-latest-task-statistic) ```bash aliyun sas get-virus-scan-latest-task-statistic --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` Check status: - `Status = 10`: In progress, display `CompleteMachine`/`ScanMachine` progress, continue polling - `Status = 20`: Completed, proceed to result query #### Polling Output Example The agent should display progress to the user in real-time during polling: ``` Scan tasks dispatched, polling progress... [Vulnerability Scan] In progress... 40% (3/5 servers completed) [Virus Scan] In progress... 66% (2/3 servers completed) --- 30 seconds later --- [Vulnerability Scan] Completed [Virus Scan] In progress... 66% (2/3 servers completed) --- 30 seconds later --- [Vulnerability Scan] Completed [Virus Scan] Completed (3/3 servers, 3 clean, 0 viruses found) All scans completed, querying risk results... ``` #### 4d: Query Final Results After all tasks complete, automatically query risk results (the queries from Step 2), presenting a complete security risk report to the user. --- ## General Reference: Version Number Mapping | Version Name | Version Number | |-------------|----------------| | Free | 1 | | Enterprise | 3 | | Advanced | 5 | | Anti-virus | 6 | | Ultimate | 7 | | Value-added Service | 10 | ## General Reference: Pay-As-You-Go Module Codes | Module Code | Name | |-------------|------| | POST_HOST | Host & Container Security | | VUL | Vulnerability Fix | | CSPM | Cloud Security Posture Management | | AGENTLESS | Agentless Detection | | SERVERLESS | Serverless Security | | CTDR | Agent SOC | | SDK | Malicious File Detection SDK | | RASP | Application Protection | | CTDR_STORAGE | Log Management | | ANTI_RANSOMWARE | Anti-Ransomware Management | | AI_DIGITAL | Agent SOC - Security Operations Agent | | WEB_LOCK | Web Tamper Protection | | IMAGE_SCAN | Image Scanning | > BASIC_SERVICE is an internal base service module; do not display to the user. ## General Reference: Cost Estimation Methods ### Module Three-Way Classification | Category | Module Codes | Estimation Method | |----------|-------------|-------------------| | Estimable monthly cost (server/core billing) | POST_HOST, SERVERLESS | Use get-auth-summary core/server counts x unit price to calculate monthly cost | | Usage-based billing | VUL, CSPM, AGENTLESS, SDK, RASP, CTDR, CTDR_STORAGE, ANTI_RANSOMWARE, AI_DIGITAL | Display unit price and billing unit, note "cost depends on actual usage" | | Subscription only | WEB_LOCK, IMAGE_SCAN | Indicate "pay-as-you-go not supported, purchase subscription via console" | ### POST_HOST Protection Levels POST_HOST has different billing dimensions and unit prices per protection level; confirm the level before enabling: | Protection Level | Billing Dimension | Estimation Formula | |-----------------|-------------------|--------------------| | Virus Protection | Per core | Bound cores (`Machine.PostPaidBindCoreCount`) x unit price/core/month | | Advanced (legacy) | Per server | Bound servers (`Machine.PostPaidBindEcsCount`) x unit price/server/month | | Host Comprehensive | Per server | Bound servers (`Machine.PostPaidBindEcsCount`) x unit price/server/month | | Host & Container Comprehensive | Per server + per core | Bound servers x unit price/server/month + Bound cores (`Machine.PostPaidBindCoreCount`) x unit price/core/month | > **Advanced Edition check**: Use `PostPayHostVersion` from `describe-version-config`; only show the Advanced option in the protection level list when this value corresponds to Advanced. If the user does not hold pay-as-you-go Advanced, hide this option because the version is no longer available for new activation. > If the user has already specified a level in conversation (e.g. "enable Ultimate pay-as-you-go"), use the corresponding level directly without asking again. ### Base Service Fee When any pay-as-you-go module is enabled, an additional base service fee applies: ~0.05 CNY/hour (approx. 36 CNY/month), settled daily. If other modules are already enabled, the base service fee is already being charged; no additional reminder needed. ### Price Retrieval Method The agent fetches current unit prices from the billing documentation page on the first pricing need per session: - Billing documentation URL: https://help.aliyun.com/zh/security-center/product-overview/billing-overview - Cache and reuse within the session, because prices do not change within a single session - If unable to access or parse content, inform the user that real-time prices could not be retrieved and provide the billing page link - In degraded scenarios, still display module classification info (estimable/usage-based/subscription-only), because classification does not depend on specific prices ### Disclaimer Cost estimates are based on current asset counts and real-time unit prices; actual fees are subject to the Alibaba Cloud bill. Tiered billing modules (CSPM, CTDR, SERVERLESS) display tier-specific unit prices for reference. FILE:references/ram-policies.md # RAM Permission Manifest RAM permissions required by this skill: > **[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 this file (`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 ## Security Center (SAS) - `yundun-sas:DescribeCloudCenterInstances` -- Query server client status - `yundun-sas:DescribeInstallCodes` -- Query existing install code list - `yundun-sas:AddInstallCode` -- Create new install code - `yundun-sas:RefreshAssets` -- Sync asset list - `yundun-sas:CreateOrUpdateAssetGroup` -- Create or update asset group - `yundun-sas:GetAuthSummary` -- Query authorization quota statistics - `yundun-sas:DescribeVersionConfig` -- Query version and instance details - `yundun-sas:GetServerlessAuthSummary` -- Query Serverless authorization status - `yundun-sas:ModifyPostPayModuleSwitch` -- Modify pay-as-you-go module switches - `yundun-sas:BindAuthToMachine` -- Bind/unbind server authorization - `yundun-sas:UpdatePostPaidBindRel` -- Change pay-as-you-go version binding - `yundun-sas:DescribePropertyScaDetail` -- Query asset fingerprint software - `yundun-sas:AddUninstallClientsByUuids` -- Uninstall agent from specified servers - `yundun-sas:ModifyPushAllTask` -- Dispatch security check tasks - `yundun-sas:ModifyStartVulScan` -- Trigger one-click vulnerability scan - `yundun-sas:DescribeGroupedVul` -- Query grouped vulnerability info - `yundun-sas:ExecStrategy` -- Execute baseline check strategy - `yundun-sas:DescribeStrategy` -- Query baseline check strategy list - `yundun-sas:ListCheckItemWarningSummary` -- Query baseline check risk statistics - `yundun-sas:DescribeSuspEvents` -- Query security alert events - `yundun-sas:GenerateOnceTask` -- Trigger asset fingerprint collection task - `yundun-sas:CreateAssetSelectionConfig` -- Create asset selection configuration - `yundun-sas:AddAssetSelectionCriteria` -- Add assets to selection configuration - `yundun-sas:UpdateSelectionKeyByType` -- Associate asset selection to business - `yundun-sas:CreateVirusScanOnceTask` -- Create virus scan task - `yundun-sas:GetVirusScanLatestTaskStatistic` -- Query virus scan progress - `yundun-sas:ListVirusScanMachine` -- Query virus scan machine list - `yundun-sas:ListVirusScanMachineEvent` -- Query machine virus events - `yundun-sas:DescribeOnceTask` -- Query scan task execution status ## Elastic Compute Service (ECS) - `ecs:DescribeInstances` -- Query ECS instance basic info - `ecs:DescribeCloudAssistantStatus` -- Query cloud assistant online status - `ecs:RunCommand` -- Execute commands remotely via cloud assistant - `ecs:InvokeCommand` -- Trigger an existing command on ECS instances - `ecs:DescribeInvocationResults` -- Query cloud assistant command execution results FILE:references/related-commands.md # CLI Command Reference Complete list of all CLI commands used by this skill. All commands use plugin mode (kebab-case) and MUST include `--user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent`. ## SAS (Security Center) Commands | Command | Type | Purpose | |---------|------|---------| | `aliyun sas describe-cloud-center-instances` | Read | Query server client status by instance ID/IP | | `aliyun sas refresh-assets` | Read | Sync latest asset data | | `aliyun sas describe-install-codes` | Read | Get existing install code list | | `aliyun sas add-install-code` | Write | Generate new install code | | `aliyun sas create-or-update-asset-group` | Write | Create or update asset group | | `aliyun sas get-auth-summary` | Read | Get authorization quota and usage per version | | `aliyun sas describe-version-config` | Read | Get version, feature modules, expiration | | `aliyun sas get-serverless-auth-summary` | Read | Get pay-as-you-go serverless status | | `aliyun sas modify-post-pay-module-switch` | Write | Toggle pay-as-you-go module switches | | `aliyun sas bind-auth-to-machine` | Write | Bind/unbind authorization version | | `aliyun sas update-post-paid-bind-rel` | Write | Change pay-as-you-go version binding | | `aliyun sas describe-property-sca-detail` | Read | Query software info on servers | | `aliyun sas add-uninstall-clients-by-uuids` | Write | Uninstall agent from specified servers | | `aliyun sas modify-push-all-task` | Write | Dispatch security check tasks to servers | | `aliyun sas modify-start-vul-scan` | Write | Trigger one-click vulnerability scan | | `aliyun sas describe-grouped-vul` | Read | Query grouped vulnerability statistics | | `aliyun sas exec-strategy` | Write | Execute baseline check strategy | | `aliyun sas describe-strategy` | Read | Query baseline check strategy list | | `aliyun sas list-check-item-warning-summary` | Read | Get baseline check risk statistics | | `aliyun sas describe-susp-events` | Read | Query security alert events | | `aliyun sas generate-once-task` | Write | Trigger full asset fingerprint collection | | `aliyun sas create-asset-selection-config` | Write | Create virus scan asset selection | | `aliyun sas add-asset-selection-criteria` | Write | Add assets to selection config | | `aliyun sas update-selection-key-by-type` | Write | Associate selection to virus scan | | `aliyun sas create-virus-scan-once-task` | Write | Create one-time virus scan task | | `aliyun sas get-virus-scan-latest-task-statistic` | Read | Query latest virus scan task stats | | `aliyun sas list-virus-scan-machine` | Read | Query machines involved in virus scan | | `aliyun sas list-virus-scan-machine-event` | Read | Query virus events on a specific machine | | `aliyun sas describe-once-task` | Read | Poll vulnerability scan task progress | ## ECS (Elastic Compute Service) Commands | Command | Type | Purpose | |---------|------|---------| | `aliyun ecs describe-instances` | Read | Query ECS instance info and running status | | `aliyun ecs describe-cloud-assistant-status` | Read | Check if cloud assistant is online | | `aliyun ecs run-command` | Write | Remote install command execution | | `aliyun ecs invoke-command` | Write | Execute existing command on instances | | `aliyun ecs describe-invocation-results` | Read | Query command execution results | ## Execution Rules - **Read** commands execute directly with brief intent statement - **Write** commands require: display operation details -> user confirmation -> execute -> report result - All commands MUST include `--user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent` - Limit to 8 CLI tool calls per scenario (proxy scenarios may extend moderately) FILE:references/verification-method.md # Success Verification Methods Verification methods for each scenario to confirm successful completion. ## Installation Scenarios ### Scenario 1: ECS Onboarding ```bash aliyun sas describe-cloud-center-instances \ --criteria '[{"name":"instanceId","value":""}]' \ --machine-types ecs \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Success criteria**: `ClientStatus` = `online` ### Scenario 2: IDC Direct Connection ```bash aliyun sas describe-cloud-center-instances \ --criteria '[{"name":"internetIp","value":""}]' \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Success criteria**: Server found in asset list with `ClientStatus` = `online` If not found, sync assets first: ```bash aliyun sas refresh-assets --asset-type ecs --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` ### Scenario 3: Image-Based Installation After new instance boots from image, wait ~5 minutes: ```bash aliyun sas describe-cloud-center-instances \ --criteria '[{"name":"instanceId","value":""}]' \ --machine-types ecs \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Success criteria**: New instance appears with `ClientStatus` = `online` and unique UUID ## Management Scenarios ### Scenario 5: Version Query **Success criteria**: Version info, authorization quota, and module switches displayed in readable format. Timestamps converted from 13-digit to YYYY-MM-DD HH:mm:ss. ### Scenario 6: Authorization Change ```bash aliyun sas describe-cloud-center-instances \ --criteria '[{"name":"instanceId","value":""}]' \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Success criteria**: `AuthVersion` matches the target version number ### Scenario 7: Software Query **Success criteria**: `describe-property-sca-detail` returns matching software entries with server details ### Scenario 8: Agent Uninstall ```bash aliyun sas describe-cloud-center-instances \ --criteria '[{"name":"uuid","value":""}]' \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Success criteria**: `ClientStatus` changed to `offline` or asset no longer in list ### Scenario 9: Security Risk Detection **Vulnerability scan completion**: ```bash aliyun sas describe-once-task --task-type "VUL_CHECK_TASK" --current-page 1 --page-size 1 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Success criteria**: Latest task `TaskStatusText` != `PROCESSING` **Baseline check completion**: ```bash aliyun sas describe-strategy --strategy-ids "" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Success criteria**: `ExecStatus` = 1 (completed) **Virus scan completion**: ```bash aliyun sas get-virus-scan-latest-task-statistic --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent ``` **Success criteria**: `Status` = 20 (completed) ## Local Server Verification ### Linux ```bash ps -ef | grep -E 'AliYunDun|YunDunMonitor|YunDunUpdate' systemctl status aegis ``` ### Windows (PowerShell) ```powershell Get-Process | Where-Object {$_.Name -match '^(AliYunDun|AliYunDunMonitor|AliYunDunUpdate)$'} Get-Service | Where-Object {$_.Name -match 'Aegis|AliYunDun'} ``` ### Network Connectivity ```bash telnet jsrv.aegis.aliyun.com 80 telnet update.aegis.aliyun.com 443 ```

Alibabacloud Sas Install Agent

Comments (0)