SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsvolcengine-cloud-trail

volcengine-cloud-trail

General & other

View repository

Updated 10-16 08:09

About this skill

Volcengine CloudTrail

Through ve cloudtrail（Version=2021-09-01) query audit events, and securely manage Trails and historical backfill tasks.

Quick reference

Item Description
Applicable scenarios Audit log queries, login/resource operation tracing, Trail management, historical backfill task management
Core capabilities Audit event query (read-only), event name resolution (read-only), Trail list/create/update/start-stop/delete, backfill list/details/create/stop
Underlying calls scripts/cloud_trail.py wraps ve cloudtrail <Action>, version pinned to 2021-09-01
Write operations Trail create/update/start-stop/delete and backfill create/stop are all previewed first and executed after user confirmation
Main references event-query.md、event-trail-management.md、backfill-delivery-tasks.md

Capability

Capability What it does Subcommand Required reading
Audit event query Query login, resource operation, and failure events, outputting a summary or full annotated logs events lookup event-query.md
Event name resolution Determine based on service, keyword, resource, and read/write attributes EventSource / EventName candidates events resolve event-query.md
Trail management List, create, update, start-stop, and delete CloudTrail Trails trails ... event-trail-management.md
Historical backfill List, view, create, and stop historical backfill tasks backfill ... backfill-delivery-tasks.md

When to use

  • The user wants to query CloudTrail, audit logs, CloudTrail, login records, resource change records, failure events, or the event corresponding to a RequestID / EventID.
  • The user wants to confirm who created, deleted, or modified a certain Volcengine resource, or needs to locate audit evidence by resource ID, user, event name, or error code.
  • The user wants to create, update, start, stop, or delete a CloudTrail Trail.
  • The user wants to view, create, or stop historical backfill tasks, or determine the dependency between backfill tasks and Trail deletion.
  • The user message contains "Volcengine / Volcengine / volcengine" and belongs to the CloudTrail, tracking, Trail, historical backfill, or CloudTrail scenario.

Prerequisites

  • ve CLI and python3 are available, and authentication has been completed via ve configure or environment variables.
  • When authentication, profile, CLI installation, or session fails, use the volcengine-cli skill to handle login/configuration; this skill only handles CloudTrail business actions.
  • After fixing the profile, identity confirmation and subsequent CloudTrail calls use the same profile. For the first signed call of each session, after re-authentication, or after the profile changes, first confirm the calling account with a read-only call.
  • Only pass --profile or --regionwhen the user explicitly specifies it. State the account, profile/default resolution, region, and time range in the conclusion.
  • The backfill creation capability requires allowlisting by operations. If the account already has any backfill task record, it can be considered that the current account has completed allowlisting for the backfill capability.

Agent internal calls

Execute from this skill directory:

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

The default output format is JSON, and read operations usually omit --format json. When md or table is needed,--format is a global parameter, placed before events / trails / backfill , for example:

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

Workflow

All actions are performed through scripts/cloud_trail.py Done (commands are executed relative to this skill directory).

Audit event query (read-only)

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>
  • Prefer relative time for --lookback-days <1..90>; absolute time supports Unix seconds, RFC3339,YYYY-MM-DD and local time.
  • When close to the 90-day boundary, use a second-level safety margin; the current implementation reserves 60 seconds.
  • A single query returns at most 50 records; only when the user explicitly requests it, fetch one page carrying the original query fingerprint.
  • EventSource / EventName When uncertain, first run events resolve。ambiguous combined with the user's original words, action semantics, resource type and read/write attributes; when the semantics are still not unique or the result is unresolved , the installed volcengine-api and volcengine-knowledge-search can serve as corroborating evidence. When a ResourceID is available, a broad query once without the doubtful conditions can be performed; if it still cannot be determined, ask the user to provide additional context.

Trail management (write operations require confirmation)

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>
  • Creating a Trail requires explicitly passing EventRW=All|Read|Write, and configuring at least one complete TOS or TLS delivery target.
  • After creation confirmation, CreateTrail -> DescribeTrails 校验 -> StartLogging -> DescribeTrails 校验is executed by default, with no second confirmation to enable it.
  • When creating a cross-account Trail, the agent by default first completes the target account's IAM role and TOS/TLS delivery resource configuration, then creates the Trail; if the target account identity or permissions are missing, ask the user to provide them.
  • Before deleting a Trail, strictly check backfill tasks with pagination; delete only after all tasks are not PENDING / RUNNING .

Historical backfill (write operations require confirmation)

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>
  • Before creating or stopping a backfill, first query backfill tasks read-only. If any backfill task record already exists in the account, it can be used directly as evidence that it has been allowlisted.
  • When no historical backfill task record is found, in the plan ask the user to confirm that the backfill feature has been allowlisted; after the user confirms, the agent adds the allowlist confirmation and write confirmation markers and executes.
  • Before creation, strictly check all tasks in the account with pagination; stop creation if any PENDING / RUNNING active task exists.
  • The backfill window satisfies EndTime < now、EndTime > StartTime、StartTime within the last 90 days, and a single task span does not exceed 90 days.

agent execution flow

  1. Determine the request: event query, event name resolution, Trail management, or historical backfill.
  2. Read the corresponding reference document, and select parameters and validation conditions according to the reference document.
  3. For the first signed call, first confirm the account, profile/default, and region read-only; continue after the identity matches expectations.
  4. Query-type requests are executed directly and evidence is reported. When complete logs are involved, use events lookup --raw, and relay them in JSONC comment format.
  5. For write operations, dry-run first, showing the user only [operation summary + special reminders + next action]; after the user replies "confirm execution", execute with the same parameters plus the confirmation marker.
  6. After a successful write, read the verification result.WriteAccepted=true only indicates that the control plane has accepted it; only StateVerified=true is described as having taken effect.

Output specification

  • State the query conclusion first, then list EventTime、EventName、EventSource、UserName、SourceIPAddress、Region、 ErrorCode、RequestID、EventID and RelatedResources。
  • When the user requests the complete audit log or raw audit log, use events lookup --raw. In this mode, stdout directly renders AnnotatedEventLogs the JSONC text, in the format "Field": value, // 字段含义; both top-level and nested object fields carry comments.
  • If the event contains a parseable EventDetail JSON object, display only the content inside EventDetail with comments, omitting the outer "EventDetail": ... field itself.SourceIPAddress The comment is "source IP".
  • Empty results are expressed as "account X has no records in the current region and time range." Multiple candidates are ordered by time descending; when evidence is insufficient, clearly state that a unique confirmation cannot be made.
  • stdout remains structured, diagnostics go to stderr; the call-level request ID uses ResponseMetadata.RequestId, and event fields use RequestID。

Write operation boundaries

  • CloudTrail business APIs use the script allowlist; STS identity confirmation and public API/documentation verification are explicit exceptions.
  • Both Trail and re-ingestion write operations require plan confirmation. The plan remains brief for the user, showing only the operation summary, special reminders, and next actions.
  • The wrapper makes only one ve call per API;ve / SDK internal retries are controlled by the underlying layer.
  • StopLogging is a separate write operation, previewed and confirmed separately.DeleteTrail is deleted directly after confirming there are no active re-ingestion tasks.
  • for the user ApiResponse envelope, and retain the top-level ResponseMetadata.RequestId。