返回技能市场
开发运维 安全

云安全中心客户端接入与管理

@aliyun/alibabacloud-sas-install-agent

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

云Skills门户 热度 61v0.0.1

云安全中心 Agent 接入与管理

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

架构：Security Center (SAS) + ECS + Cloud Assistant + Proxy Cluster (optional)

执行模式：读操作直接执行（ReAct），写操作显示详细信息，并要求用户确认后再执行（命令）。分析应简洁 -- 为每项操作输出简要的推理说明。

前置检查：必须使用阿里云 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
```
检查输出中是否存在有效的配置文件（AK、STS 或 OAuth 身份）。
如果不存在有效的配置文件，请在此处停止。
1. 从阿里云控制台获取凭证
2. 在此会话之外配置凭证（通过终端中的 aliyun configure 或命令解释器配置文件中的环境变量）
3. 待 aliyun configure list 显示有效配置文件后，返回并重新运行

安全准则

  • 禁止在输出中暴露敏感信息（AccessKey、密码），因为凭证泄露可能危及账号安全
  • 禁止调用任何删除类 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

---

工具清单

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

| CLI 命令 | 用途 | |-------------|---------| | aliyun sas describe-cloud-center-instances | 按实例 ID/IP 查询服务器客户端状态 | | aliyun ecs describe-instances | 查询 ECS 实例信息和运行状态 | | aliyun ecs describe-cloud-assistant-status | 检查云助手是否在线 | | aliyun ecs run-command | 远程执行安装命令（写操作） | | aliyun ecs invoke-command | 在实例上触发现有命令（写操作） | | aliyun ecs describe-invocation-results | 查询命令执行结果 | | aliyun sas refresh-assets | 同步最新资产数据 | | aliyun sas describe-install-codes | 获取现有安装码列表 | | aliyun sas add-install-code | 生成新的安装码（写操作） | | aliyun sas create-or-update-asset-group | 创建或更新资产分组（写操作） | | aliyun sas get-auth-summary | 获取各版本的授权配额和使用量 | | aliyun sas describe-version-config | 获取版本、功能模块和到期时间 | | aliyun sas get-serverless-auth-summary | 获取无服务器按量付费状态 | | aliyun sas modify-post-pay-module-switch | 切换按量付费模块开关（写操作） | | aliyun sas bind-auth-to-machine | 绑定/解绑授权版本（写操作） | | aliyun sas update-post-paid-bind-rel | 更改按量付费版本绑定或降级为免费版（写操作） | | aliyun sas describe-property-sca-detail | 查询服务器上的软件信息 | | aliyun sas add-uninstall-clients-by-uuids | 从指定服务器卸载 agent（写操作） | | aliyun sas modify-push-all-task | 向服务器下发安全检查任务（写操作）— 用于对单台服务器进行定向扫描 | | aliyun sas modify-start-vul-scan | 触发对所有服务器的全局全量扫描（写操作）— 禁止用于单台服务器的定向扫描 | | aliyun sas describe-grouped-vul | 查询分组漏洞统计信息 | | aliyun sas exec-strategy | 执行基线检查策略（写操作） | | aliyun sas describe-strategy | 查询基线检查策略列表 | | aliyun sas list-check-item-warning-summary | 获取基线检查风险统计信息 | | aliyun sas describe-susp-events | 查询安全告警事件 | | aliyun sas generate-once-task | 触发完整资产指纹采集（写操作） | | aliyun sas create-asset-selection-config | 创建病毒扫描资产选择配置（写操作） | | aliyun sas add-asset-selection-criteria | 将资产添加到选择配置（写操作） | | aliyun sas update-selection-key-by-type | 将选择配置关联到病毒扫描（写操作） | | aliyun sas create-virus-scan-once-task | 创建一次性病毒扫描任务（写操作） | | aliyun sas get-virus-scan-latest-task-statistic | 查询最新病毒扫描任务统计信息 | | aliyun sas list-virus-scan-machine | 查询参与病毒扫描的机器 | | aliyun sas list-virus-scan-machine-event | 查询特定机器上的病毒事件 | | aliyun sas describe-once-task | 轮询漏洞扫描任务进度 |

详细的 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

以表格形式显示：安装码、OS、厂商、分组、镜像标志、到期时间。

步骤 2：请用户选择

用户可以选择一个现有的、匹配且未过期的安装码，也可以请求新建一个。

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

| 配置 | 参数 | 备注 | |--------|-----------|-------| | OS | --os | linux 或 windows | | 厂商 | --vendor-name | 由网络接入方式决定（见下文） | | 资产分组 | --group-id | 目标分组；如有需要，通过 create-or-update-asset-group 创建 | | 到期时间 | --expired-date | 13 位时间戳；省略时使用默认值 | | 镜像安装 | --only-image | 是否用于创建镜像模板 |

VendorName 与网络接入方式的映射：

厂商参数决定安装命令使用的连接域名。值不正确会导致 agent 无法连接到服务器：

| 网络接入方式 | VendorName | 原因 | |---------------|-----------|--------| | 直连（专线） | ALIYUN | 使用内网域名 jsrv2.aegis.aliyun.com | | 公网（阿里云 ECS） | ALIYUN | ECS 使用内网 | | 公网（第三方云/IDC） | OTHER | 使用公网域名 jsrv.aegis.aliyun.com |

当场景已确定网络接入方式时，自动填充 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. 可选择查询无服务器状态（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 集群资产仅支持旗舰版，因为其他版本不涵盖容器运行时防护
详细步骤：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. 触发新扫描，分为两种不同模式：
  • 定向扫描（特定服务器）：对所有扫描类型（漏洞 + 基线 + 指纹）使用 modify-push-all-task 并传入目标 UUID。定向扫描严禁使用 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 会触发针对整个账号中所有服务器的全局全量扫描，而不只是扫描目标服务器。扫描特定服务器（定向扫描）时，必须使用 modify-push-all-task 并指定该服务器的 UUID——这是执行定向漏洞扫描唯一正确的命令。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. 每个场景的 CLI 工具调用次数上限为 8 次（代理场景可适当增加）
  3. 未确认服务器信息时，不得调用 APIs，因为错误参数会返回无意义的结果
  4. 不得跳过步骤，因为每一步的输出都是下一步的输入
  5. 不得捏造 API 返回结果，因为这会误导用户作出错误决定

成本估算规则

  • 展示按量付费模块状态时，提供每个模块的计费方式和单价参考信息
  • 在用户启用按量付费模块前，在确认详情中包含成本估算
  • 从官方计费文档页面获取价格信息：https://help.aliyun.com/zh/security-center/product-overview/billing-overview
  • 每个会话首次需要价格信息时获取一次，随后复用
  • 如无法获取，则提供计费页面链接供用户查看
  • 基础服务费：启用任一按量付费模块后，将收取基础服务费（约 0.05 CNY/小时，每月约 36 CNY）
  • 如果当前未启用任何模块，则在首次启用时提醒用户注意此费用
模块分类、估算公式和展示格式：参见 references/manage-scenarios.md 的成本估算章节。

---

终止与总结

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

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

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

---

最佳实践

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

---

参考资料

此 skill 引用以下文档，并按需加载：

| 参考文档 | 说明 | |-----------|-------------| | references/install-scenarios.md | 安装场景（1、2、3、4）的详细执行步骤 | | references/manage-scenarios.md | 管理/查询场景（5、6、7、8、9）的详细执行步骤 | | references/agent-install-guide.md | Agent 安装命令和验证方法 | | references/api-reference.md | 所有 API 参数详情和 CLI 示例 | | references/ram-policies.md | RAM 权限清单 | | references/cli-installation-guide.md | 阿里云 CLI 安装指南 | | references/related-commands.md | 完整的 CLI 命令参考表 | | references/verification-method.md | 各场景的成功验证方法 | | references/acceptance-criteria.md | Skill 验收标准和测试模式 |

qianwen skills install @aliyun/alibabacloud-sas-install-agent