volcengine-cloud-trail · diff

v1.0.0 to v1.0.0

34 added, 131 removed. Audit A to A.

---

name: volcengine-cloud-trail

description: >-

- Use when the user asks to query Volcengine CloudTrail audit logs, investigate

- login or resource operations, or manage CloudTrail trails and backfill delivery

- tasks. Trigger on 操作审计, 审计日志, CloudTrail, cloud_trail, trail, 跟踪,

- 历史补投, or backfill in a Volcengine context. Audit queries are read-only;

- trail and backfill mutations require an explicit preview and confirmation.

+ 当用户需要查询火山引擎 CloudTrail 审计日志、调查登录或资源操作、分析或导出已投递到 TLS 的审计日志、导出已投递到 TOS 的审计日志、管理检索模板，或开通、调整、排查审计日志投递及管理历史补投任务时使用。

+ 在火山引擎语境下，出现“操作审计、审计日志、日志检索、CloudTrail、cloud_trail、trail、跟踪、审计日志投递、历史补投、backfill”等词时触发。

license: MIT

- version: 1.0.0

- user-invocable: true

allowed-tools: Bash, Read

metadata:

+ version: 1.0.0

openclaw:

requires:

bins:

- ve

- python3

install:

- kind: node

package: "@volcengine/cli"

bins: [ve]

envVars:

- name: VOLCENGINE_ACCESS_KEY

required: false

description: AccessKey for AK/SK auth path (alternative to ve login)

- name: VOLCENGINE_SECRET_KEY

required: false

description: SecretKey for AK/SK auth path

- name: VOLCENGINE_SESSION_TOKEN

required: false

description: Optional STS session token for temporary credentials

- name: VOLCENGINE_REGION

required: false

description: Default region used by ve when the profile has none

---

# 火山引擎操作审计

- 通过 `ve cloudtrail`（`Version=2021-09-01`）查询审计事件，并安全管理 Trail 与历史补投任务。

- ## 速查

- | 项目 | 说明 |

- | --- | --- |

- | 适用场景 | 操作审计日志查询、登录/资源操作溯源、Trail 管理、历史补投任务管理 |

- | 核心能力 | 审计事件查询（只读）、事件名解析（只读）、Trail 列表/创建/更新/启停/删除、补投列表/详情/创建/停止 |

- | 底层调用 | `scripts/cloud_trail.py` 封装 `ve cloudtrail <Action>`，版本固定 `2021-09-01` |

- | 写操作 | Trail 创建/更新/启停/删除、补投创建/停止，均先预览，用户确认后执行 |

- | 主要参考 | [event-query.md](references/event-query.md)、[event-trail-management.md](references/event-trail-management.md)、[backfill-delivery-tasks.md](references/backfill-delivery-tasks.md) |

- ## 能力

- | 能力 | 做什么 | 子命令 | 必读参考 |

- | --- | --- | --- | --- |

- ## 什么时候用

- - 用户要查操作审计、审计日志、CloudTrail、登录记录、资源变更记录、失败事件或 RequestID / EventID 对应事件。

- - 用户要确认某个火山资源是谁创建、删除、修改，或需要按资源 ID、用户、事件名、错误码定位审计证据。

- - 用户要创建、更新、开启、停止或删除操作审计 Trail。

- - 用户要查看、创建或停止历史补投任务，或判断补投任务与 Trail 删除之间的依赖。

- - 用户消息里出现「火山 / 火山引擎 / volcengine」且属于操作审计、跟踪、Trail、历史补投、CloudTrail 场景。

- ## 前置条件

- - `ve` CLI 与 `python3` 可用，并已通过 `ve configure` 或环境变量完成鉴权。

- - 鉴权、profile、CLI 安装或会话失败时，使用 `volcengine-cli` skill 处理登录/配置；本 skill 只处理 CloudTrail

- 业务动作。

- - 固定 profile 后，身份确认和后续 CloudTrail 调用使用同一 profile。每个会话首次签名调用、重新鉴权或

- profile 改变后，先只读确认调用账号。

- - 只有用户明确指定时才传 `--profile` 或 `--region`。结论里说明账号、profile/default 解析、地域和时间范围。

- - 补投创建能力需要运营开白。账号内已有任一补投任务记录时，可视为当前账号已完成补投能力开白。

- ## agent 内部调用

- 从本 skill 目录执行：

- ```bash

- python3 scripts/cloud_trail.py --help

- python3 scripts/cloud_trail.py events lookup --signin-action login --lookback-days 3

- python3 scripts/cloud_trail.py events resolve --service vpc --keyword Delete --resource-id vpc-<id> --operation write

- python3 scripts/cloud_trail.py trails list

- python3 scripts/cloud_trail.py backfill list

- ```

- 默认输出格式就是 JSON，读操作通常直接省略 `--format json`。需要 `md` 或 `table` 时，`--format` 是全局参数，

- 放在 `events` / `trails` / `backfill` 之前，例如：

- ```bash

- python3 scripts/cloud_trail.py --format table trails list

- python3 scripts/cloud_trail.py --format md backfill list --page-number 1 --page-size 100

- ```

- ## 工作流

- 所有动作通过 `scripts/cloud_trail.py` 完成（命令相对本 skill 目录执行）。

- ### 审计事件查询（只读）

- ```text

- python3 scripts/cloud_trail.py events lookup --signin-action login --lookback-days 3

- python3 scripts/cloud_trail.py events lookup --resource-id vpc-<id> --operation write --lookback-days 7

- python3 scripts/cloud_trail.py events lookup --raw --request-id <request-id>

- ```

+ 帮助用户完成审计日志查询、溯源、分析、导出，以及检索模板、跟踪和历史补投管理。

- - 相对时间优先用 `--lookback-days <1..90>`；绝对时间支持 Unix 秒、RFC3339、`YYYY-MM-DD` 和本地时间。

- - 贴近 90 天边界时使用秒级安全余量，当前实现预留 60 秒。

- - 单次查询最多 50 条；下一页只在用户明确要求时，携带原查询指纹取一页。

- - `EventSource` / `EventName` 不确定时先运行 `events resolve`。`ambiguous` 时结合用户原话、动作语义、资源类型

- 和读写属性判断；语义仍不唯一或结果为 `unresolved` 时，已安装的 `volcengine-api` 与

- `volcengine-knowledge-search` 可作为补证。已有 ResourceID 时可去掉存疑条件宽查一次；仍无法判断时请用户补充上下文。

+ ## 执行入口

- ### Trail 管理（写操作需确认）

+ 先读取 [账号与操作规则](references/rules.md)，再按下表读取本次操作的参考；上下文中已有的有效内容可直接复用。

- ```text

- python3 scripts/cloud_trail.py trails list

- python3 scripts/cloud_trail.py trails create --trail-name <trail-name> --event-rw All --tos-bucket-region <region> --tos-bucket-name <bucket>

- python3 scripts/cloud_trail.py trails update --trail-name <trail-name> --event-rw Write

- python3 scripts/cloud_trail.py trails start --trail-name <trail-name>

- python3 scripts/cloud_trail.py trails stop --trail-name <trail-name>

- python3 scripts/cloud_trail.py trails delete --trail-name <trail-name>

- ```

+ ## 能力与选路

- - 创建 Trail 必须显式传 `EventRW=All|Read|Write`，并至少配置一个完整 TOS 或 TLS 投递目标。

- - 创建确认后默认执行 `CreateTrail -> DescribeTrails 校验 -> StartLogging -> DescribeTrails 校验`，不再二次确认开启。

- - 创建跨账号 Trail 时，agent 默认先完成目标账号 IAM 角色和 TOS/TLS 投递资源配置，再创建 Trail；缺少目标账号身份

- 或权限时请用户补齐。

- - 删除 Trail 前严格分页检查补投任务；全部任务均非 `PENDING` / `RUNNING` 后再删除。

+ | 用户目标 | 执行路径 | 必读参考 |

+ | --- | --- | --- |

+ | 近 90 天的事件查询、详情或小规模结果导出，且条件组合受支持 | 基础检索；单次查询最多 50 条，基础导出最多 200 条 | [event-query.md](references/event-query.md) |

+ | 解析产品事件源、事件名或操作语义 | 事件名解析，按需结合官方资料核实 | [event-query.md](references/event-query.md) |

+ | 复杂条件或 SQL 统计，且已有覆盖目标时段的 TLS 日志 | TLS 高级检索 | [advanced-query.md](references/advanced-query.md) |

+ | 全部匹配日志或当前页导出不足 | 按筛选条件、结果数量和已有日志覆盖选择基础导出或副本下载，详见“路径选择” | [result-export.md](references/result-export.md)，缺副本需补投时读 [backfill-delivery-tasks.md](references/backfill-delivery-tasks.md) |

+ | 超过 90 天的事件查询 | 先查已有 TLS／TOS 日志及保留时间，再选择检索或下载；见“已有副本发现” | [result-export.md](references/result-export.md#已有副本发现) |

+ | 开通、调整或停止审计日志投递，排查投递异常 | 跟踪与投递管理，包含目标资源准备和日志到达验证 | [event-trail-management.md](references/event-trail-management.md) |

+ | 保存指定历史时段日志或管理补投任务 | 历史补投管理 | [backfill-delivery-tasks.md](references/backfill-delivery-tasks.md) |

+ | 查找、使用或管理检索模板 | 模板管理；仅管理模板不检查历史数据覆盖 | [search-templates.md](references/search-templates.md) |

- ### 历史补投（写操作需确认）

+ 完整导出优先级高于原查询路径，但“全部”不等于“大批量”：基础路径可以证明完整时，不为切换工具而发现副本或准备补投。仅要求保存当前页或当前已取得结果时，按用户指定范围处理，不扩大为全量任务。

- ```text

- python3 scripts/cloud_trail.py backfill list --page-number 1 --page-size 10

- python3 scripts/cloud_trail.py backfill describe --task-id bdt-<id>

- python3 scripts/cloud_trail.py backfill create --trail-name <trail-name> --start-time <recent-rfc3339-start> --end-time <recent-rfc3339-end> --enable-tos

- python3 scripts/cloud_trail.py backfill stop --task-id bdt-<id>

- ```

+ ## 工具与前置条件

- - 创建或停止补投前先只读查询补投任务。账号内已有任一补投任务记录时，可直接作为已开白依据。

- - 未发现历史补投任务记录时，预案请用户确认补投功能已开白；用户确认后，agent 加开白确认与写入确认标记执行。

- - 创建前严格分页检查账号内全部任务；存在任一 `PENDING` / `RUNNING` 活跃任务时停止创建。

- - 补投窗口满足 `EndTime < now`、`EndTime > StartTime`、`StartTime` 在近 90 天内，单任务跨度不超过 90 天。

+ - CloudTrail 业务接口仅通过 `scripts/cloud_trail.py` 的 allowlist 调用 `ve cloudtrail`，API 版本为 `2021-09-01`；STS 身份确认及公开文档查证不受此清单限制。

+ - CloudTrail 调用前检查 `ve --version`：稳定版至少 1.2.0。版本缺失、不可识别或不满足时停止业务调用，按 `volcengine-cli` 准备工具后恢复任务。版本通过不代表接口注册或鉴权通过。

+ - 脚本需要 `python3`。`--help` 不要求安装 ve；直接 TLS 操作按对应工具的版本要求执行。

+ - ve 安装、鉴权与配置按 `volcengine-cli`；TLS 操作按 `volcengine-tls`；TOS 操作按 `volcengine-tosutil`。具体命令、参数与工具要求由对应技能维护。

+ - 身份选择、账号绑定与登录恢复统一按 rules.md；需要时读取相关工具技能。遵循当前工具要求携带 Agent 调用来源标识，不记录或回显密钥和令牌。

+ - 标准输出保留结构化结果，诊断进入标准错误；成功 API envelope 保留在 `ApiResponse`。技术证据的保存与面向用户展示分开处理。

- ## agent 执行流程

+ ## 时间与条件

- 1. 判断诉求：事件查询、事件名解析、Trail 管理，还是历史补投。

- 2. 读取对应参考文档，按参考文档选择参数和校验条件。

- 3. 首次签名调用先只读确认账号、profile/default、地域；身份符合预期后继续。

- 4. 查询类请求直接执行并汇报证据。涉及完整日志时使用 `events lookup --raw`，按 JSONC 注释格式转述。

- 5. 写操作先 dry-run，向用户只展示【操作摘要 + 特殊提醒 + 下一步动作】；用户回复「确认执行」后，使用同一参数

- 加确认标记执行。

- 6. 写入成功后读取验证结果。`WriteAccepted=true` 只表示控制面受理；只有 `StateVerified=true` 才表述为已生效。

+ - 基础检索限近 90 天；TLS 实际可查范围取决于投递覆盖和保留情况；补投窗口见对应参考。

+ - 续查与导出沿用已固定的账号、时间范围和筛选条件。时间格式、时区解析、单位转换与边界处理见对应能力参考。

+ - 根据真实条件组合和预期结果选路，不先试基础检索再丢弃不受支持的条件。基础检索空结果先核对范围，不能只因空结果自动改走 TLS。

+ - 产品、事件源、事件名和读写语义不确定时先核实。“完整原始事件”指字段完整，“全部事件”指结果集合完整，分别处理。

- ## 输出规范

+ ## 调用入口

- - 查询结论先行，再列 `EventTime`、`EventName`、`EventSource`、`UserName`、`SourceIPAddress`、`Region`、

- `ErrorCode`、`RequestID`、`EventID` 和 `RelatedResources`。

- - 用户要求完整审计日志或原始审计日志时使用 `events lookup --raw`。该模式 stdout 直接渲染

- `AnnotatedEventLogs` 的 JSONC 文本，格式为 `"Field": value, // 字段含义`；顶层与嵌套对象字段都带注释。

- - 若事件包含可解析的 `EventDetail` JSON object，只展示 `EventDetail` 内部内容并加注释，省略外层

- `"EventDetail": ...` 字段本身。`SourceIPAddress` 注释为“来源 IP”。

- - 空结果表述为“账号 X 在当前地域与时间范围内无记录”。多条候选按时间倒序；证据不足时明确无法唯一确认。

- - stdout 保持结构化，诊断走 stderr；调用级请求 ID 使用 `ResponseMetadata.RequestId`，事件字段使用 `RequestID`。

+ 在本技能目录使用 `python3 scripts/cloud_trail.py --help` 查看入口；按需查看对应子命令帮助，业务示例见能力参考。

- ## 写操作边界

+ 仅实际调用 CloudTrail API 的业务路径须带已确认账号的全局 `--expected-account-id`，必要时带对应已授权身份选择。直接 TLS／TOS 调用独立核实身份。本地帮助与元数据解析不要求账号校验。

- - CloudTrail 业务 API 使用脚本 allowlist；STS 身份确认及公开 API/文档查证是明确例外。

- - Trail 与补投写操作都需要预案确认。预案面向用户保持简短，只展示操作摘要、特殊提醒和下一步动作。

- - wrapper 对每个 API 只发起一次 `ve` 调用；`ve` / SDK 内部重试由底层控制。

- - `StopLogging` 是独立写操作，单独预览和确认。`DeleteTrail` 在确认无活跃补投任务后直接删除。

- - API 响应成功后保留 `ApiResponse` envelope，并向用户保留顶层 `ResponseMetadata.RequestId`。

+ 默认输出 JSON；需要其他格式时，全局 `--format` 放在业务分组之前。