Alicloud Actiontrail Ops

> This skill follows the Agent Skill OpenSpec.

Alibaba Cloud ActionTrail Operations Skill

Overview

Alibaba Cloud ActionTrail (操作审计) monitors and records API calls and user activities across Alibaba Cloud services, including operations performed via the console, OpenAPI, and developer tools. This skill is an operational runbook for agents: explicit scope, credential rules, pre-flight checks, dual-path execution (official aliyun CLI as primary path, JIT Go SDK as fallback), response validation, and failure recovery.

Runtime Rules

| Area | Rule | Reference | | --- | --- | --- | | CLI path | MANDATORY: Prefer ./scripts/actiontrail-harness-wrapper.sh for all ActionTrail CLI operations; legacy ./scripts/actiontrail-skillopt-wrapper.sh shim supported. Fallback to native aliyun actiontrail only when wrapper missing. | [CLI](references/cli-usage.md), [SkillOpt](references/skillopt-integration.md) |

CLI applicability (repository policy)

• cli_applicability: dual-path: Official aliyun supports ActionTrail. You

MUST use references/cli-usage.md and, in each execution flow below, document both the SDK step and the aliyun step for every operation the CLI exposes. If the CLI covers only part of the API, add a coverage gap table (SDK-only operations) in references/cli-usage.md.

Five Core Standards (Quality Gates)

| # | Standard | How This Skill Fulfills It | |---|----------|---------------------------| | 1 | Clear Boundaries | SHOULD/SHOULD NOT Use conditions with precise triggers and delegation rules | | 2 | Structured I/O | Placeholder conventions ({{env.*}}, {{user.*}}, {{output.*}}) with type and source documented | | 3 | Explicit Actionable Steps | Every operation: Pre-flight → Execute → Validate → Recover, with numbered imperative steps | | 4 | Complete Failure Strategies | Error taxonomy table with 10+ product-specific codes; HALT vs retry per error type | | 5 | Absolute Single Responsibility | One product (ActionTrail), one primary resource model (Trail); cross-product delegation to other skills |

Trigger & Scope (Agent-Readable)

SHOULD Use This Skill When

• User mentions "ActionTrail" OR "操作审计" OR "actiontrail" OR "trail" OR "跟踪"
• User mentions "审计日志" OR "操作日志" OR "事件查询" OR "审计事件"
• Task involves trail lifecycle (create, describe, update, delete, enable/disable logging)
• Task involves event lookup/query (search historical events, filter by time/user/resource)
• Task involves delivery configuration (OSS/SLS/MaxCompute delivery setup)
• Task involves AccessKey audit (last used info, events, IPs, products, resources)
• Task involves data event selectors (configure data-level event collection)
• Task involves insight events (enable/disable/query insight analysis)
• Task involves advanced query (scenes, templates, SQL-based event search)
• Task involves data replenishment (backfill historical events to delivery destinations)
• Task keywords: 操作审计, actiontrail, trail, 跟踪, 审计, audit, 事件, event, 日志, log,

LookupEvents, CreateTrail, StartLogging, StopLogging, AccessKey审计

• User asks to audit, trace, or investigate API calls, resource changes, or user activities

via API, SDK, CLI, or automation

SHOULD NOT Use This Skill When

• Task is purely billing / account management → delegate to: alicloud-billing-ops (when present)
• Task is RAM / permission model only → delegate to: alicloud-ram-ops (when present)
• Task is about SLS (Log Service) log analysis or dashboard creation → delegate to:

alicloud-sls-ops (when present)

• Task is about OSS bucket configuration or data management → delegate to:

alicloud-oss-ops (when present)

• Task is about MaxCompute project management → delegate to:

alicloud-maxcompute-ops (when present)

• User insists on console-only flows with no API → state limitation; do not invent

undocumented HTTP steps

Delegation Rules

| 能力 | 委托目标 | 说明 | |------|----------|------| | GCL 质量门禁 | alicloud-gcl-runner-ops | Optional GCL (max_iter=5); cross-checker role via gcl_actiontrail_crosscheck.py; rubric at [references/rubric.md](references/rubric.md) |

Variable Convention (Agent-Readable)

| Placeholder | Meaning | Agent Action | |-------------|---------|--------------| | {{env.ALIBABA_CLOUD_ACCESS_KEY_ID}} | From runtime environment | NEVER ask the user; fail if unset | | {{env.ALIBABA_CLOUD_ACCESS_KEY_SECRET}} | From runtime environment | NEVER ask the user; fail if unset | | {{env.ALIBABA_CLOUD_REGION_ID}} | From runtime environment | Use documented default only if skill explicitly allows | | {{user.region}} | User-supplied region | Ask once; reuse | | {{user.trail_name}} | User-supplied trail name | Ask once; reuse | | {{user.oss_bucket_name}} | User-supplied OSS bucket name | Ask once; reuse | | {{user.sls_project_arn}} | User-supplied SLS project ARN | Ask once; reuse | | {{user.access_key_id}} | User-supplied AccessKey ID to audit | Ask once; reuse | | {{user.start_time}} | Event lookup start time (ISO 8601 UTC) | Ask once; reuse | | {{user.end_time}} | Event lookup end time (ISO 8601 UTC) | Ask once; reuse | | {{user.event_type}} | Event type filter | Ask once; reuse | | {{user.service_name}} | Cloud service name filter | Ask once; reuse | | {{user.event_name}} | Event name filter | Ask once; reuse | | {{user.data_event_selector_json}} | JSON string for PutDataEventSelector EventSelector param | Ask once; reuse | | {{output.trail_name}} | From last API or CLI JSON response | Parse per OpenAPI or verified CLI path | | {{output.trail_status}} | Trail logging status (Enable/Disable) | Parse per OpenAPI or verified CLI path | | {{output.request_id}} | API request ID for tracking | Parse per OpenAPI or verified CLI path |

> {{env.*}} MUST NOT be collected from the user. {{user.*}} MUST be collected > interactively when missing.

> 凭据安全（强制）： 参考 [Credential Masking 规则](../alicloud-skill-generator/references/credential-masking.md)

API and Response Conventions (Agent-Readable)

• OpenAPI is canonical for path, query, body fields, enums, and response shapes.
• Errors: Map SDK/HTTP errors to code / status / message fields per spec.
• Timestamps: ISO 8601 with timezone when the API returns strings (e.g.

2026-04-28T10:00:00+08:00).

• Pagination: LookupEvents uses NextToken for pagination. MaxResults range: 0-50.

Example Response Field Table

| Operation | JSON Path | Type | Description | |-----------|-----------|------|-------------| | CreateTrail | $.TrailName | string | Created trail name | | DescribeTrails | $.TrailList[].TrailName | array | Trail names | | GetTrailStatus | $.IsLogging | boolean | Whether logging is enabled | | LookupEvents | $.Events[] | array | Event records | | LookupEvents | $.NextToken | string | Pagination token | | GetAccessKeyLastUsedEvents | $.Events[] | array | AK event records | | GetAccessKeyLastUsedIps | $.Ips[] | array | IP addresses used by AK | | GetAccessKeyLastUsedProducts | $.Products[] | array | Products accessed by AK | | GetAccessKeyLastUsedResources | $.Resources[] | array | Resources accessed by AK | | ListDataEventSelectors | $.DataEventSelectors[] | array | Data event selector list | | PutDataEventSelector | $.RequestId | string | Confirmation of selector configuration |

Expected State Transitions

| Operation | Initial State | Target State | Poll Interval | Max Wait | |-----------|---------------|--------------|---------------|----------| | CreateTrail | — | created (disabled) | 5s | 60s | | StartLogging | disabled | enabled | 5s | 60s | | StopLogging | enabled | disabled | 5s | 60s | | DeleteTrail | any | deleted | 5s | 60s |

Quick Start

What This Skill Does

This skill enables you to configure, query, and manage ActionTrail audit logging on Alibaba Cloud using the aliyun CLI (primary) or JIT Go SDK (fallback).

Prerequisites

见 [执行环境配置](../alicloud-skill-generator/references/execution-environment.md)

Verify Setup

# Check CLI and credentials
aliyun actiontrail DescribeRegions

Your First Command

# List all trails
aliyun actiontrail DescribeTrails

Next Steps

• [Core Concepts](references/core-concepts.md) — Understand ActionTrail architecture
• [Common Operations](#execution-flows) — Create, manage, and query trails and events
• [Troubleshooting](references/troubleshooting.md) — Fix common issues

Capabilities at a Glance

| Operation | Description | Complexity | Risk Level | |-----------|-------------|------------|------------| | CreateTrail | Create a new trail for event delivery | Medium | Low | | DescribeTrails | List all trails | Low | None | | GetTrailStatus | Query trail logging status | Low | None | | StartLogging | Enable trail logging | Low | Low | | StopLogging | Disable trail logging | Low | Low | | UpdateTrail | Modify trail configuration | Medium | Medium | | DeleteTrail | Remove a trail | Low | High — irreversible | | LookupEvents | Search historical events | Medium | None | | GetAccessKeyLastUsedInfo | Query AccessKey last usage summary | Low | None | | GetAccessKeyLastUsedEvents | Query specific events called by an AccessKey | Low | None | | GetAccessKeyLastUsedIps | Query source IPs used by an AccessKey | Low | None | | GetAccessKeyLastUsedProducts | Query products accessed by an AccessKey | Low | None | | GetAccessKeyLastUsedResources | Query resources accessed by an AccessKey | Low | None | | EnableInsight | Enable insight analysis | Low | Low | | DisableInsight | Disable insight analysis | Low | Low | | LookupInsightEvents | Query insight events | Medium | None | | ListDataEventSelectors | List data event selectors for a trail | Low | None | | GetDataEventSelector | Get details of a data event selector | Low | None | | PutDataEventSelector | Configure data event selectors (OSS data-plane events) | Medium | Low | | DeleteDataEventSelector | Remove a data event selector | Low | Low | | CreateDeliveryHistoryJob | Backfill historical events | Medium | Low | | CreateComplianceTrail | Create a compliance-grade trail (all regions, all events) | Medium | Low |

> EXECUTION MANDATORY RULE: 所有 control-plane CLI 执行步骤 必须 通过 SkillOpt wrapper ./scripts/actiontrail-skillopt-wrapper.sh 运行。 > 以下所有代码块中的 aliyun actiontrail ... 命令在执行时应替换为 ./scripts/actiontrail-skillopt-wrapper.sh ...。 > 仅在 wrapper 脚本不可用或 skillopt-lib.sh 缺失时，才退回到原生 aliyun actiontrail CLI 调用。 > 参考 ## Runtime Rules 中的 CLI path 规则。

Execution Flows (Agent-Readable)

Every operation: Pre-flight → Execute (SDK/API and aliyun) → Validate → Recover. Do not skip phases.

Preference hint: CLI is preferred for coverage and simplicity; Go SDK is used for operations CLI does not expose.

Operation: Create Trail

Pre-flight Checks

| Check | Method | Expected | On Failure | |-------|--------|----------|------------| | SDK / deps | Import client; version matches metadata.api_profile | No import error | Document install pin | | CLI / deps | aliyun version | Exit code 0 | Document CLI install | | Credentials | Construct credential from env | Non-empty keys | HALT; user configures env | | Region | aliyun actiontrail DescribeRegions | Region supported | Suggest valid region | | Trail name | Validate name: 6-36 chars, lowercase start, alphanumeric/hyphen/underscore | Valid name | Ask user for valid name | | Delivery target | At least one of OssBucketName, SlsProjectArn, MaxComputeProjectArn specified | At least one set | Ask user for delivery target |

CLI Execution

aliyun actiontrail CreateTrail \
  --Name {{user.trail_name}} \
  --OssBucketName {{user.oss_bucket_name}} \
  --OssKeyPrefix {{user.oss_key_prefix}} \
  --EventRW All \
  --IsOrganizationTrail false

Note: By default, the created trail is in disabled state. You must call StartLogging to enable it.

SDK Execution (JIT Go Fallback)

JIT Go SDK fallback: 参见 [API & SDK Usage](references/api-sdk-usage.md)

go run main.go {{user.trail_name}} {{user.oss_bucket_name}}

Validation

| Check | Method | Expected | |-------|--------|----------| | Trail created | aliyun actiontrail DescribeTrails | Trail appears in list | | Trail name matches | $.TrailList[0].TrailName | Matches {{user.trail_name}} | | Delivery target set | $.TrailList[0].OssBucketName | Matches {{user.oss_bucket_name}} |

Recovery

| Error | Pattern | Action | |-------|---------|--------| | Trail name exists | TrailAlreadyExistsException | HALT; suggest different name | | Invalid parameter | InvalidParameter | HALT; check parameter values | | Network error | RequestError | Retry with exponential backoff (3 attempts) |

Operation: Describe Trails

Pre-flight Checks

| Check | Method | Expected | On Failure | |-------|--------|----------|------------| | Credentials | Env vars set | Non-empty | HALT |

CLI Execution

# List all trails
aliyun actiontrail DescribeTrails

# List trails with name filter
aliyun actiontrail DescribeTrails --NameList '["{{user.trail_name}}"]'

# Include organization trails
aliyun actiontrail DescribeTrails --IncludeOrganizationTrail true

JIT Go SDK fallback: 参见 [API & SDK Usage](references/api-sdk-usage.md)

Validation

| Check | Method | Expected | |-------|--------|----------| | Response received | $.RequestId | Non-empty | | Trail list | $.TrailList | Array (may be empty) |

Recovery

| Error | Pattern | Action | |-------|---------|--------| | Network error | RequestError | Retry with backoff |

Operation: Get Trail Status

Pre-flight Checks

| Check | Method | Expected | On Failure | |-------|--------|----------|------------| | Trail exists | aliyun actiontrail DescribeTrails | Trail in list | HALT; trail not found |

CLI Execution

aliyun actiontrail GetTrailStatus --Name {{user.trail_name}}

JIT Go SDK fallback: 参见 [API & SDK Usage](references/api-sdk-usage.md)

Validation

| Check | Method | Expected | |-------|--------|----------| | Status received | $.IsLogging | Boolean value | | Latest delivery time | $.LatestDeliveryTime | ISO 8601 timestamp |

Recovery

| Error | Pattern | Action | |-------|---------|--------| | Trail not found | TrailNotFoundException | HALT; suggest listing trails first |

Operation: Start Logging

Pre-flight Checks

| Check | Method | Expected | On Failure | |-------|--------|----------|------------| | Trail exists | DescribeTrails | Trail in list | HALT | | Trail is disabled | GetTrailStatus | IsLogging: false | Already enabled; no action needed |

CLI Execution

aliyun actiontrail StartLogging --Name {{user.trail_name}}

JIT Go SDK fallback: 参见 [API & SDK Usage](references/api-sdk-usage.md)

Validation

| Check | Method | Expected | |-------|--------|----------| | Logging enabled | aliyun actiontrail GetTrailStatus --Name {{user.trail_name}} | IsLogging: true |

Recovery

| Error | Pattern | Action | |-------|---------|--------| | Trail not found | TrailNotFoundException | HALT | | Already logging | IsLogging: true | Inform user; no action needed |

Operation: Stop Logging

Pre-flight Checks

| Check | Method | Expected | On Failure | |-------|--------|----------|------------| | Trail exists | DescribeTrails | Trail in list | HALT | | Trail is enabled | GetTrailStatus | IsLogging: true | Already disabled; no action needed |

CLI Execution

aliyun actiontrail StopLogging --Name {{user.trail_name}}

JIT Go SDK fallback: 参见 [API & SDK Usage](references/api-sdk-usage.md)

Validation

| Check | Method | Expected | |-------|--------|----------| | Logging disabled | `aliyun actiontrail GetTrailStatus --Name {

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: buhaiqing
• Source: buhaiqing/aliyun-skills
• License: MIT

Install and usage instructions live in the source repository linked above.