Alibabacloud Actiontrail Diagnosis

ActionTrail Diagnosis

Absolute Rules — read before doing anything

1. Strictly READ-ONLY. Never write. Under NO circumstances execute any command or API call that mutates state (Create*, Update*, Modify*, Delete*, Disable*, Set*, Start*, Stop*, …). This skill only queries ActionTrail audit events and the caller identity; any write-API attempt is a hard failure.
2. Never output credentials. Never print, cat, or quote credential files (~/.aliyun/config.json), environment variable values, AccessKey pairs, or STS tokens. Reference credential fields by name only; do not echo secrets into the conversation or the report.
3. Ask before running when information is insufficient. If a required input (region, time range, target product/event) is missing and cannot be safely defaulted, ask the user first — do NOT guess and run wide, unfiltered queries. UID is the only input that may always be auto-derived (see Information Completeness).
4. Output must be based on real API returns. Never fabricate. Every event, count, operator, timestamp, or error in the answer must come from the script's actual output. Empty results are a valid finding — report them truthfully; never invent events, fill gaps from imagination, or claim operations happened without evidence.

Overview

This skill queries the Alibaba Cloud ActionTrail LookupEvents API in read-only mode to retrieve operation audit events for an account, with multi-region batch querying, automatic pagination, flexible time input (ISO8601 UTC or Beijing time), server-side filtering via LookupAttribute, and client-side refinement filters. The single entry script scripts/lookup_events.py handles credential routing, retries, error degradation, and result rendering.

Orchestration

Products involved: STS (caller identity) and ActionTrail (audit events). Every diagnosis follows one fixed call order, executed by scripts/lookup_events.py:

1. STS GetCallerIdentity — always called first and unconditionally, even when --uid is supplied, so the effective account is known and can be cross-checked.
2. Region resolution — --region all expands to the built-in common region list; a global-service ServiceName overrides the request and pins the query to cn-hangzhou.
3. ActionTrail LookupEvents — called once per resolved region, paginated via NextToken until exhaustion or the per-region page cap.
4. Client-side refinement — --filter-event / --filter-resource-type are applied to the merged event set after all regions return.
5. Rendering — the 12-column table plus the Friendly Summary, or the --json contract.

Decision criteria that drive the orchestration:

Quick Start

python3 scripts/lookup_events.py \
    --region cn-hangzhou \
    --start-time '2026-07-01 00:00:00' --end-time '2026-07-02 23:59:59' \
    --lookup-attribute 'ServiceName=Vpc' --lookup-attribute 'EventRW=Write'

Minimal runnable form: one region, a narrow time window, and up to two --lookup-attribute Key=Value filters. --uid is omitted here and auto-derived from the active credential. Prefer narrow time windows and precise attributes over broad scans.

User Confirmation / Information Completeness

Missing a required item → restate what is known, ask the user, and wait. Never silently expand scope beyond the confirmed region/time/product.

CLI Options

Output Specification

Default output is a Markdown table with exactly these 12 columns, in this order: Event Time (Beijing) | Event Name | Event ID | Cloud Service | Event Source | Region | Operator (Type) | Read/Write | Event Type | Source IP | Role Session | Related Resources. Failure events are marked in the Related Resources column with ❌ plus an error label (a non-empty errorCode yields that code; a non-empty errorMessage alone yields Failed). After the table (and any truncation warning), table mode always appends a Friendly Summary — plain English, plain text, at most 20 lines, computed from the actual result — with four fixed sections: ## Query Scope (account UID with provided/derived source, regions checked, human-readable Beijing-time window, plain-language translation of the filters), ## Key Findings (total events, read/write breakdown, top 3 operators, top 3 services, failed-operation count; for zero events it states that no matching events were found in this scope plus one likely reason), ## Points to Note (only when applicable: truncation, partial region failures, account mismatch, unrecognized ServiceName, global-service pinning — each explained in non-technical terms), and ## Suggested Next Steps (1–3 actionable recommendations derived from the actual result state). The Friendly Summary is written for non-technical readers and goes through the same masking as the table. With --summary, only the one-line summary is appended instead of the Friendly Summary; with --json, no Friendly Summary is emitted.

With --json, the top-level contract fields are: success, partial, failed_regions, truncated, events, total_count, start_time, end_time, pages, regions, per_region, uid, uid_source, lookup_attributes, direction. uid is the effective account UID and the only intentionally plaintext identifier in the JSON — UIDs embedded inside events (accountId / principalId / ARN) remain masked; uid_source is provided when --uid was passed explicitly and derived when the UID was resolved via STS GetCallerIdentity. lookup_attributes is the effective Key=Value filter list after malformed entries were dropped, and direction is the sort direction — together with uid / regions / start_time / end_time they make the JSON fully self-describing so a downstream agent can reproduce or continue the query. When --start-time / --end-time are omitted, start_time / end_time echo the effective query window reported by the LookupEvents response (ISO8601 UTC), degrading to the placeholder wording only if the API echoes no window; explicitly provided times are reported as their normalized UTC values.

Output red lines:

1. The Operator (Type) column must NEVER display accountId. The only exception is the script's own fallback for a root-account event whose principalId is missing — do not add accountId to the table yourself in any other case.
2. AccessKeyId and requestParameters are NOT displayed by default. Show them only when the user explicitly asks, and extract them verbatim from the raw --json output — never invent, guess, or paraphrase them.
3. The Friendly Summary is the user-facing narrative layer. It may be paraphrased, condensed, or made more conversational when presented to the user, but its facts must never be altered, invented, or padded into long-form analysis beyond what the result supports. --summary mode remains a single line.

When truncated is true, results are incomplete — do NOT present them as exhaustive. Guide the user through three downgrade steps, in order:

1. Narrow the time window (--start-time / --end-time).
2. Add more precise --lookup-attribute conditions (e.g. EventRW=Write, a specific EventName or ResourceName).
3. For long-term or full-volume audit needs, recommend delivering ActionTrail events to SLS (Log Service) instead of querying the event API.

_queryRegion is a private provenance field injected by the script into every event; it is not displayed by default. Render it — read from the --json output — only when the user explicitly asks to group events by the actual query region.

Reporting to Mixed Audiences

The output serves two audiences at once. For end users (often non-technical), present the Friendly Summary first — paraphrasing or further colloquializing it is encouraged — and never hand the raw 12-column table to a non-technical user as the only answer. For a downstream agent or the next diagnosis stage, pass the complete --json contract (uid, regions, start_time / end_time, lookup_attributes, direction, per_region, events) so the query can be reproduced or continued verbatim. Keep the two channels separate: human-readable narrative from the Friendly Summary, machine-readable context from --json.

References

• service-mapping.md — map user-facing product names to the exact ActionTrail ServiceName values.
• lookup-attribute.md — all supported LookupAttribute keys, valid two-condition combinations, and case-sensitivity rules.
• api-reference.md — LookupEvents request/response field semantics and event structure.
• network-events-catalog.md — catalog of common network-product event names for tracing typical operations.
• ram-policies.md — the minimum read-only RAM policy (actiontrail:LookupEvents + sts:GetCallerIdentity).

Prerequisites

Aliyun CLI 3.x installed and configured (recommended), or credentials provided via environment variables / ~/.aliyun/config.json; the script falls back to direct signed HTTPS calls when the CLI is unavailable. Python dependencies: pip install -r scripts/requirements.txt. Read-only credentials per ram-policies.md.

Error Handling

• Transient failures (throttling / 429, 5xx, network): retried automatically with backoff; do not invent manual retry paths.
• Per-region failures: a single region failing degrades to per_region.<region>.error and failed_regions; the run continues for other regions (partial=true). Report the failed regions and their errors honestly alongside the successful results.
• ACCOUNT MISMATCH WARNING: when --uid does not match the credential's account, results reflect only the credential's account and may be empty. Surface the warning verbatim to the user; empty results do NOT prove "nothing happened" in the requested account.
• Credential resolution failure: if --uid is omitted and cannot be derived, the script exits with an explicit error — ask the user for --uid or valid credentials.
• Exit codes (identical in table and --json mode): 0 = success or partial success (at least one region succeeded; partial=true / failed_regions carry the degraded parts), 1 = all queried regions failed or a fatal error, 2 = invalid arguments.

Observability

Every Alibaba Cloud API call this skill makes carries a User-Agent for server-side audit correlation:

• UA template: AlibabaCloud-Agent-Skills/{skill-name}/{session-id} — here {skill-name} is alibabacloud-actiontrail-diagnosis.
• session-id: a 32-character lowercase-hex string, generated once per process run and shared unchanged by every call in that run (both the CLI backend and the HTTP fallback), so all calls of one diagnosis correlate.
• Inheritance: set the environment variable ACTIONTRAIL_SESSION_ID to a valid 32-hex value to make a parent process and the script share one session-id; otherwise a fresh id is generated automatically. No manual configuration is required.