# Alicloud Actiontrail Ops

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-buhaiqing-aliyun-skills-alicloud-actiontrail-ops`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [buhaiqing](https://agentstack.voostack.com/s/buhaiqing)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [buhaiqing](https://github.com/buhaiqing)
- **Source:** https://github.com/buhaiqing/aliyun-skills/tree/main/alicloud-actiontrail-ops

## Install

```sh
agentstack add skill-buhaiqing-aliyun-skills-alicloud-actiontrail-ops
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

> This skill follows the [Agent Skill OpenSpec](https://agentskills.io/specification).

# 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
```bash
# Check CLI and credentials
aliyun actiontrail DescribeRegions
```

### Your First Command
```bash
# 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

```bash
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)

```bash
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

```bash
# 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

```bash
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

```bash
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

```bash
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](https://github.com/buhaiqing)
- **Source:** [buhaiqing/aliyun-skills](https://github.com/buhaiqing/aliyun-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-buhaiqing-aliyun-skills-alicloud-actiontrail-ops
- Seller: https://agentstack.voostack.com/s/buhaiqing
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.