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

volcengine-cloud-trail

Security & auditing

View repository

Updated 10-19 16:17

About this skill

Volcengine ActionTrail

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

Quick Reference

Item Description
Applicable Scenarios ActionTrail log query, 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/enable-disable/delete, backfill list/detail/create/stop
Underlying Calls scripts/cloud_trail.py Wraps ve cloudtrail <Action>, version pinned to 2021-09-01
Write Operations Trail create/update/enable-disable/delete, backfill create/stop, all previewed first and executed after user confirmation
Main References event-query.md、event-trail-management.md、backfill-delivery-tasks.md

Capabilities

Capability What It Does Subcommand Required Reading Reference
Audit Event Query Query login, resource operation, and failure events, output summary or complete annotated logs events lookup event-query.md
Event Name Resolution Determine EventSource / EventName candidates based on service, keywords, resources, and read/write attributes events resolve event-query.md
Trail Management List, create, update, enable-disable, and delete ActionTrail 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 ActionTrail, audit logs, CloudTrail, login records, resource change records, failure events, or events 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, enable, stop, or delete an ActionTrail 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" and falls under ActionTrail, tracking, Trail, historical backfill, or CloudTrail scenarios.

Prerequisites

  • ve CLI and python3 are available, and authentication has been completed via ve configure or environment variables.
  • If 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. On the first signed call of each session, after re-authentication, or after a profile change, first confirm the calling account with a read-only call.
  • Only pass --profile or --regionwhen explicitly specified by the user. In the conclusion, state the account, profile/default resolution, region, and time range.
  • 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; for read operations, usually omit --format json. When md or table is needed,--format is a global parameter and is 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 go 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 with --lookback-days <1..90>; absolute time supports Unix seconds, RFC3339,YYYY-MM-DD and local time.
  • Use a seconds-level safety margin near the 90-day boundary; the current implementation reserves 60 seconds.
  • A single query returns at most 50 records; for the next page, only when the user explicitly requests it, carry the original query fingerprint to fetch one page.
  • EventSource / EventName When uncertain, first run events resolve。ambiguous , judge based on the user's original wording, action semantics, resource type and read/write attribute; 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 already available, remove the doubtful conditions and run a broad query once; if it still cannot be determined, ask the user for 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 is confirmed, execute CreateTrail -> DescribeTrails 校验 -> StartLogging -> DescribeTrails 校验by default, without a 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 paginate through the backfill tasks; only after all tasks are not in PENDING / RUNNING should you delete it.

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 the feature is whitelisted.
  • If no historical backfill task record is found, in the plan ask the user to confirm that the backfill feature has been whitelisted; after the user confirms, the agent adds the whitelist confirmation and write confirmation markers and executes.
  • Before creation, strictly paginate through all tasks in the account; if any task is in PENDING / RUNNING active state, stop creation.
  • The backfill window must satisfy: EndTime < now、EndTime > StartTime、StartTime within the last 90 days, and a single task's span must 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 once the identity matches expectations.
  4. Execute query-type requests directly and report the evidence. When complete logs are involved, use events lookup --raw, and relay them in JSONC comment format.
  5. For write operations, dry-run first, and show 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 should be described as effective.

Output specification

  • State the query conclusion first, then list EventTime、EventName、EventSource、UserName、SourceIPAddress、Region、 ErrorCode、RequestID、EventID and RelatedResources。
  • When the user requests complete audit logs or raw audit logs, use events lookup --raw. In this mode, stdout directly renders the AnnotatedEventLogs JSONC text, in the format "Field": value, // 字段含义; both top-level and nested object fields carry comments.
  • If the event contains a parsable 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 sorted in reverse chronological order; when evidence is insufficient, explicitly state that a unique confirmation cannot be made.
  • stdout remains structured, diagnostics go to stderr; call-level request IDs use ResponseMetadata.RequestId, event fields use RequestID。

Write operation boundaries

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