alibabacloud-sas-install-agent

安全中心 Agent 接入与管理

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

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

执行模式：读取操作直接执行（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 检查凭证状态

aliyun configure list

检查输出中是否存在有效配置（AK、STS 或 OAuth 身份）。

如果不存在有效配置，请在此处停止。

1. 从阿里云控制台获取凭证
2. 在本次会话之外配置凭证（在终端中运行 aliyun configure，或在 shell 配置文件中设置环境变量）
3. 返回后，重新运行 aliyun configure list，确认显示有效配置

安全指南

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

RAM 策略

此技能所需的详细权限：references/ram-policies.md

[MUST] 权限失败处理： 在执行过程中的任何时候，如果任何命令或 API 调用因权限错误而失败，请遵循以下流程：

1. 阅读 references/ram-policies.md，获取此 SKILL 所需权限的完整列表
2. 使用 ram-permission-diagnose 技能，引导用户申请所需权限
3. 暂停并等待用户确认已授予所需权限

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

在 Core Workflow 开始时（调用任何 CLI 之前）： [MUST] 启用 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"

[MUST] 在每个退出点禁用 AI-Mode — 无论出于何种原因，在发送最终回复之前，务必先禁用 AI-mode。此要求适用于所有退出路径：工作流成功、工作流失败、错误/异常、用户取消、会话结束，或其他任何不再执行 CLI 命令的情况。 AI-mode 仅用于调用 Agent Skill 的场景，技能停止运行后不得继续保持启用状态。

aliyun configure ai-mode disable

---

工具清单

所有 API 均通过 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

以表格形式显示：安装码、操作系统、厂商、分组、镜像标记、过期时间。

步骤 2：请用户选择

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

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

配置	参数	说明
操作系统	--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

2. 网络接入方式：

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

3. 镜像部署 -> 场景 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：查询版本和功能信息

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

[MUST] 路由区分：场景 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，写入操作）

[MUST] 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：卸载 Security Center Agent

触发条件：用户想从特定服务器卸载 Security Center Agent。

摘要：

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

关键限制：

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

详细步骤：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
4. 对定向资产扫描，自动执行前置流程：授权检查 -> 客户端检查 -> 自动安装 -> 下发扫描和病毒扫描
5. 下发后轮询进度：漏洞扫描（describe-once-task）、基线检查（describe-strategy.ExecStatus）、病毒扫描（get-virus-scan-latest-task-statistic）；全部完成后查询风险结果

关键限制：

• [HARD GATE] 定向扫描绝不可使用 modify-start-vul-scan：modify-start-vul-scan 会触发整个账号下所有服务器的全局全量扫描，而不只是目标服务器。扫描指定服务器（定向扫描）时，必须使用带服务器 UUID 的 modify-push-all-task——这是定向漏洞扫描唯一正确的命令。modify-start-vul-scan 仅适用于未指定具体目标的全量扫描场景。
• [HARD GATE] 所有扫描都要求客户端在线：所有扫描下发操作（modify-push-all-task、modify-start-vul-scan、exec-strategy、create-virus-scan-once-task）都基于主机，要求目标服务器的安全中心 Agent ClientStatus=online。如果未安装 Agent 或 Agent 离线，则无法下发扫描，也不会产生任何结果。此技能不支持无 Agent 扫描模式。客户端未在线时，不要下发任何扫描；应先引导用户安装 Agent 或使其上线
• [HARD GATE] 扫描需要付费授权：目标服务器必须绑定付费授权版本（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

---

回退场景

触发条件：未匹配到任何场景，或请求超出此技能的能力范围。

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

---

执行规则

只读操作（直接执行）

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 CNY/小时，约 36 CNY/月）
  • 如果当前未启用任何模块，首次启用时提醒用户此费用

模块分类、估算公式和显示格式：references/manage-scenarios.md 费用估算部分。

---

终止与总结

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

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

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

---

最佳实践

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

---

参考资料

此技能会按需加载以下文档：

参考资料	描述
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	Alibaba Cloud CLI 安装指南
references/related-commands.md	完整的 CLI 命令参考表
references/verification-method.md	各场景的成功验证方法
references/acceptance-criteria.md	技能验收标准和测试模式