alibabacloud-sas-install-agent：通过 aliyun CLI 完成云安全中心客户端的全生命周期管理，涵盖多种网络环境下的 Agent 安装接入（ECS/IDC/镜像）、版本与授权管理、客户端卸载，以及初步的安全风险检测。

云安全中心 Agent 接入与管理

通过 aliyun CLI 管理阿里云云安全中心 Agent 安装、版本授权、资产查询和安全风险检测。

架构：云安全中心（SAS） + ECS + 云助手 + 代理集群（可选）

执行模型：读操作直接执行（ReAct），写操作展示详情并要求用户确认后执行（Command）。保持分析简洁——为每个动作输出简短推理。

预检查：需要 Aliyun CLI >= 3.3.3
运行 aliyun version 验证 >= 3.3.3。如果未安装或版本过低，
运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 安装/更新，
或参阅 references/cli-installation-guide.md 获取安装说明。
然后 [必须] 运行 aliyun configure set --auto-plugin-install true 启用插件自动安装。
然后 [必须] 运行 aliyun plugin update 确保本地现有插件始终为最新版本。

预检查：需要阿里云凭证
安全规则：
- 绝不读取、回显或打印 AK/SK 值（例如 echo $ALIBABA_CLOUD_ACCESS_KEY_ID 是禁止的）
- 绝不要求用户在对话或命令行中直接输入 AK/SK
- 绝不使用带有明文凭证值的 aliyun configure set
- 只能使用 aliyun configure list 检查凭证状态
```bash
aliyun configure list
```
检查输出中是否存在有效 profile（AK、STS 或 OAuth 身份）。
如果不存在有效 profile，请在此停止。
1. 从 阿里云控制台 获取凭证
2. 在本会话之外配置凭证（通过终端中的 aliyun configure 或 shell profile 中的环境变量）
3. 在 aliyun configure list 显示有效 profile 后返回并重新运行

安全准则

• 绝不在输出中暴露敏感信息（AccessKey、密码），因为泄露凭证可能危及账号
• 绝不调用任何 Delete 类 API，因为删除操作不可逆且可能中断防护
• 写操作（创建安装码、创建集群、安装代理、通过云助手运行命令、绑定授权、修改开关）必须展示操作详情并等待用户确认后执行，因为这些操作会修改线上资源
• 通过云助手派发命令前显示完整命令内容，因为生产服务器上执行任意命令风险高

RAM 策略

本 Skill 所需的详细权限：references/ram-policies.md

[必须] 权限失败处理： 当任何命令或 API 调用在执行过程中因权限错误失败时，遵循以下流程：
1. 阅读 references/ram-policies.md 获取本 SKILL 所需的完整权限列表
2. 使用 ram-permission-diagnose skill 引导用户申请必要权限
3. 暂停并等待用户确认所需权限已授予

重要：参数确认 —— 在执行任何命令或 API 调用之前，
所有用户可自定义参数（例如 RegionId、实例名、CIDR 块、
密码、域名、资源规格等）都必须与用户确认。
未经用户明确批准，不要假设或使用默认值。

在核心工作流开始时（任何 CLI 调用之前）：

[必须] 启用 AI-Mode —— Agent Skill 执行需要 AI-mode。

在任何 CLI 调用之前运行以下命令：

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

[必须] 在每一个退出点禁用 AI-Mode —— 在交付最终响应之前（无论何种原因），必须先禁用 AI-mode。这适用于所有退出路径：工作流成功、工作流失败、错误/异常、用户取消、会话结束，或任何不再执行 CLI 命令的场景。

AI-mode 仅用于 Agent Skill 调用场景，Skill 停止运行后绝不能保持启用状态。

aliyun configure ai-mode disable

工具清单

所有 API 通过 aliyun CLI 调用。每条 aliyun 命令都必须包含 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent。

详细 API 参数：references/api-reference.md。RAM 权限：references/ram-policies.md。完整命令列表：references/related-commands.md。

通用流程：获取或创建安装码

当任何安装场景需要安装码时，遵循此统一流程。

步骤 1：查询现有安装码

aliyun sas describe-install-codes --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-install-agent

以表格展示：安装码、操作系统、供应商、分组、镜像标志、到期时间。

步骤 2：请用户选择

用户可选择现有的匹配且未过期安装码，或请求新安装码。

步骤 3：确认新安装码配置（仅创建时）

VendorName 与网络接入方式映射：

供应商参数决定安装命令使用的连接域名。使用错误值会导致 Agent 无法连接到服务器：

当场景已识别网络接入方式时，自动填充 VendorName，无需询问用户。

确认后执行创建（仅传用户指定的参数）。这是写操作，需要确认。

步骤 4：获取安装命令

创建后，重新查询安装码列表以获取新 CaptchaCode 用于构建安装命令。

场景路由

场景 0：初步咨询

触发：用户模糊地说“接入云安全中心”、“安装安全 Agent”、“部署云安全”。

策略：不调用任何工具。通过提问收集信息，然后路由：

1. 服务器类型：

• 阿里云 ECS -> 场景 1
• 第三方云 / 本地 IDC -> 继续问题 2

1. 网络接入方式：

• 公网或专线直连 -> 场景 2

1. 镜像部署 -> 场景 3

场景 1：阿里云 ECS 接入

触发：用户确认服务器是阿里云 ECS 实例。

概要：

1. 获取 ECS 信息，查询实例和客户端状态
2. 基于 ClientStatus + ClientSubStatus：在线 = 无需操作，未安装 = 安装，离线 = 排查
3. 获取或创建安装码（通用流程）
4. 如果云助手在线，远程派发；否则提供手动安装命令
5. 验证接入

详细步骤和 CLI 命令：references/install-scenarios.md#scenario-1-alibaba-cloud-ecs-onboarding

场景 2：本地 IDC 直连（公网/专线）

触发：本地 IDC 或第三方云服务器，具有公网或专线连通性。

概要：

1. 获取或创建安装码（通用流程，VendorName 由网络类型自动确定）
2. 根据网络情况（公网/专线/海外）选择安装命令，参阅 references/agent-install-guide.md
3. 验证接入

详细步骤：references/install-scenarios.md#scenario-2-on-premises-idc-direct-connection

场景 3：基于镜像的批量安装

触发：用户提到镜像部署、批量创建预装 Agent 的服务器、模板创建。

概要：

1. 确认模板服务器信息，提醒干净环境要求
2. 获取或创建镜像专用安装码（OnlyImage=true）
3. 提供安装命令；强调：执行后只允许关机——重启会激活 Agent 并占用 UUID
4. 警告 UUID 冲突风险：每次镜像创建都需要重复此流程
5. 验证新实例接入

详细步骤和注意事项：references/install-scenarios.md#scenario-3-image-based-batch-installation

场景 4：网络排查

触发：用户报告安装失败、Agent 离线或连接问题。

策略：不调用工具；直接提供排查指导：

• 确认所需域名和端口（公网：jsrv.aegis.aliyun.com:80，专线：jsrv2.aegis.aliyun.com:80）
• 提供网络连通性测试命令
• 常见原因分析（防火墙、DNS、无公网）

详细排查步骤：references/install-scenarios.md#scenario-4-network-troubleshooting

场景 5：查询版本和功能信息

触发：用户想了解账号级版本、授权配额、已启用功能或按量付费状态。

[必须] 路由区分：场景 5 用于账号级查询（“我们的版本是什么”、“配额还剩多少”、“过期时间”）。当用户询问特定服务器（“哪些服务器未授权”、“哪些机器是免费版”、“未绑定付费版本的服务器”）时，路由到带 AuthVersion 过滤器的 describe-cloud-center-instances——这是资产查询，不是版本查询。

概要：

1. 查询版本详情（describe-version-config）
2. 查询授权使用情况（get-auth-summary）
3. 可选查询 Serverless 状态（get-serverless-auth-summary）
4. 可选修改按量付费模块开关（modify-post-pay-module-switch，写操作）

[必须] describe-version-config 响应中的 MergedVersion 字段是敏感内部字段——绝不显示、输出、保存到文件或包含在任何暴露给用户的响应中。在任何输出之前剥离它。改用 Version 和 HighestVersion。

详细步骤和字段映射：references/manage-scenarios.md#scenario-5-query-version-and-feature-info

场景 6：查询或修改资产授权版本

触发：用户想查看或更改特定服务器的授权版本，或列出按授权状态过滤的服务器（例如“哪些服务器未授权”、“免费版的机器有哪些”）。

当按授权状态列出/过滤服务器时，使用带条件过滤器的 describe-cloud-center-instances。当查看/修改特定命名服务器的版本时，遵循下方完整场景 6 流程。

概要：

1. 查询资产当前状态和授权版本
2. 确认操作类型（查看/绑定/解绑/更改按量付费版本/降级到免费）
3. 订阅绑定/解绑（bind-auth-to-machine，写操作）
4. 按量付费版本更改或降级到免费（update-post-paid-bind-rel，写操作）。降级到免费版使用 --bind-action 中的 Version=1
5. 验证更改

关键约束：

• 订阅绑定 30 天内不能解绑，因为授权资源有锁定期
• K8s/ACK 集群资产只支持 Ultimate 版，因为其他版本不覆盖容器运行时防护

详细步骤：references/manage-scenarios.md#scenario-6-query-or-modify-asset-authorization

场景 7：查询安装了特定软件的资产

触发：用户想查找安装了特定软件的服务器。

概要：

1. 确认查询条件（软件名、类型）
2. 查询资产指纹（describe-property-sca-detail）
3. 可选补充详细资产信息

详细步骤：references/manage-scenarios.md#scenario-7-query-assets-with-specific-software

场景 8：卸载云安全中心 Agent

触发：用户想从特定服务器卸载云安全中心 Agent。

概要：

1. 获取目标服务器标识符，查询资产信息获取 UUID
2. 展示卸载详情（服务器名、UUID、当前状态），警告卸载会移除所有防护
3. 确认后执行卸载（add-uninstall-clients-by-uuids，写操作）
4. 验证卸载结果

关键约束：

• 此 API 适用于非阿里云服务器（IDC/第三方云）；阿里云 ECS 需要通过控制台或云助手卸载
• 卸载会移除所有云安全中心防护能力；用户必须明确确认

详细步骤：references/manage-scenarios.md#scenario-8-uninstall-security-center-agent

场景 9：安全风险检测与查询

触发：用户想检测安全风险、触发漏洞扫描、执行基线检查、查看安全告警或获取风险结果。

概要：

1. 确认检测类型（查询现有风险结果 / 触发新扫描）
2. 查询风险结果：漏洞（describe-grouped-vul）、基线（list-check-item-warning-summary）、安全告警（describe-susp-events）
3. 触发新扫描——两种不同模式：

• 定向扫描（特定服务器）：对所有扫描类型（漏洞 + 基线 + 指纹）使用带目标 UUID 的 modify-push-all-task。绝不使用 modify-start-vul-scan 做定向扫描。
• 全量扫描（所有服务器）：使用 modify-start-vul-scan（漏洞）、exec-strategy（基线）、generate-once-task（指纹）、create-virus-scan-once-task（病毒）

1. 对于定向资产扫描，自动执行前置链：授权检查 -> 客户端检查 -> 自动安装 -> 派发扫描 + 病毒扫描
2. 派发后轮询进度：漏洞扫描（describe-once-task）、基线检查（describe-strategy.ExecStatus）、病毒扫描（get-virus-scan-latest-task-statistic）；全部完成后查询风险结果

关键约束：

• [硬性门禁] 绝不使用 modify-start-vul-scan 做定向扫描：modify-start-vul-scan 触发整个账号中所有服务器的全局全量扫描，而不仅是目标。扫描特定服务器（定向扫描）时，你必须使用带该服务器 UUID 的 modify-push-all-task——这是定向漏洞扫描的唯一正确命令。modify-start-vul-scan 专用于未指定特定目标的全量扫描场景。
• [硬性门禁] 所有扫描都要求客户端在线：所有扫描派发操作（modify-push-all-task、modify-start-vul-scan、exec-strategy、create-virus-scan-once-task）都是基于主机的，要求目标服务器的云安全中心 Agent ClientStatus=online。如果 Agent 未安装或离线，扫描无法派发且不会产生结果。本 Skill 中没有无 Agent 扫描模式。客户端不在线时不要进行任何扫描派发——而是引导用户先安装或让 Agent 上线
• [硬性门禁] 扫描需要付费授权：目标服务器必须绑定付费授权版本（AuthVersion > 1）；免费版（AuthVersion <= 1）服务器无法扫描
• 查询现有风险结果（describe-grouped-vul、list-check-item-warning-summary、describe-susp-events）是读操作，查询云安全中心数据库中的历史数据——这不触发新扫描，也不要求 Agent 在线
• 全量扫描前，先查询所有资产状态，向用户展示就绪/未就绪资产明细，并在派发前确认
• 定向资产扫描通过前置链（授权 + 客户端）全自动，仅授权绑定需要用户确认
• 基线检测（HEALTH_CHECK / exec-strategy）需要预付费主机防护版本（Version > 1）或已启用云安全态势管理（CSPM）；两者都不满足时跳过基线检测
• 扫描操作是写操作；全量扫描执行前需要确认

详细步骤：references/manage-scenarios.md#scenario-9-security-risk-detection-and-query

兜底场景

触发：无场景匹配，或请求超出本 Skill 能力。

策略：如实告知用户当前不支持；建议参阅官方文档或提交工单。

执行规则

读操作（直接执行）

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

调用前简要说明意图（1-2 句）。

写操作（执行前确认）

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

流程：展示操作详情 -> 等待用户确认 -> 执行 -> 报告结果。

观察阶段

• 简要描述返回结果
• 判断是否符合预期
• 决定下一步动作

迭代原则

1. 如果 Agent 已在线，立即告知用户无需操作
2. 每个场景限制 8 次 CLI 工具调用（代理场景可适度延长）
3. 不要在未确认服务器信息的情况下调用 API，因为错误参数会返回无意义结果
4. 不要跳过步骤，因为每步输出是下一步输入
5. 不要捏造 API 返回结果，因为这会误导用户做出错误决策

成本估算规则

• 展示按量付费模块状态时，包含每个模块的计费方式和单价参考
• 在用户启用按量付费模块之前，在确认详情中包含成本估算
• 从官方计费文档页面获取定价：https://help.aliyun.com/zh/security-center/product-overview/billing-overview
• 每会话首次需要定价时获取一次，然后复用
• 如果无法获取，提供计费页面链接供用户查看
• 基础服务费：启用任何按量付费模块时，适用基础服务费（约 0.05 元/小时，约 36 元/月）
• 如果当前未启用任何模块，首次启用时提醒用户此费用

模块分类、估算公式和展示格式：references/manage-scenarios.md 成本估算章节。

终止与总结

满足以下任一条件时进入总结：

• Agent 已成功上线
• 安装命令已提供给用户
• 版本/授权/软件信息已查询并展示
• 授权绑定/解绑/更改操作已完成
• Agent 卸载操作已完成
• 安全风险检测已完成或风险结果已展示
• 问题已识别并提供解决方案
• 场景不支持并已建议提交工单

总结格式适应场景。核心要素：操作结果、关键信息（服务器/版本/状态）、后续建议。

最佳实践

1. 任何操作前始终验证 CLI 版本和凭证
2. 根据网络接入方式使用正确的 VendorName 以避免连接失败
3. 对于批量安装，优先使用基于镜像的方式以减少人工
4. 绑定新服务器前检查授权配额以避免超限
5. 排查离线 Agent 时，先验证到云安全中心 endpoint 的网络连通性
6. 对于代理场景，确保代理服务器满足要求（Linux、端口 80/443/8080）后再继续
7. 安装后始终验证 Agent 在线状态再认为任务完成

参考

本 Skill 引用以下文档，按需加载：

文档 6 / 6：alibabacloud-waf-checkresponse-intercept-query