Alibabacloud Csas User Device Ops

Pre-checks

Aliyun CLI >= 3.3.3 required

aliyun version

If not installed or version too low, see references/cli-installation-guide.md.

Plugin setup (MUST run before first use)

aliyun configure set --auto-plugin-install true
aliyun plugin update

AI-Mode Lifecycle (MUST follow)

At the START of workflow (before any CLI invocation):

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-csas-user-device-ops"

At EVERY exit point (success, failure, error, cancellation, including after every write operation completes):

aliyun configure ai-mode disable

[MUST] Run ai-mode disable even when the operation succeeds. It is part of the success path, not just the error path.

Credential Verification

Security Rules:

• NEVER read, echo, or print AK/SK values
• NEVER ask users to input AK/SK in conversation
• ONLY use aliyun configure list to check credential status

aliyun configure list

If no valid profile exists, STOP. Guide user to configure credentials outside this session.

RAM Policy & Permission Handling

Required permissions are listed in references/ram-policies.md.

[MUST] Permission Failure Handling: When any command fails due to permission errors (HTTP 403, "AccessDenied", "Forbidden", "no permission", or similar):

1. STOP execution immediately. Do NOT retry blindly.
2. Identify the failing API from the error message (e.g. csas:ListUserDevices, csas:UpdateUserDevicesStatus).
3. Tell the user the exact RAM Action that failed and offer two paths:
   • Quick path: Attach the system policy AliyunCSASFullAccess to the RAM user/role (covers all CSAS operations).
   • Minimal path: Add only the specific failing Action(s) to a custom policy. See references/ram-policies.md for the minimal policy template.
4. Pause and wait until the user confirms permissions have been granted.
5. After confirmation, retry the failed operation.

Permission error message template:

"Permission denied calling csas:\x3CApiName>. Please grant either AliyunCSASFullAccess (system policy, covers all) or add csas:\x3CApiName> to a custom RAM policy. See references/ram-policies.md for details. Reply 'done' after granting and I will retry."

Operation Routing

Match user intent to the execution path:

Example query translations:

• "Show devices in QA dept running macOS with DLP disabled" → aliyun csas list-user-devices --department QA --device-types macOS --dlp-statuses Disabled --pager
• "Which devices are personal and long-term offline" → aliyun csas list-user-devices --device-belong Personal --device-statuses LongTermOffline --pager
• "What internal apps is a user authorized to access" → aliyun csas list-user-applications --sase-user-id \x3CID> --current-page 1 --page-size 100
• "How many Windows devices are online" → aliyun csas list-user-devices --device-types Windows --device-statuses Online --current-page 1 --page-size 1 (check TotalNum)

Direct CLI Commands

All queries use aliyun csas plugin mode directly. Use --pager to auto-paginate full results. Full parameter details: see references/api-reference.md.

Parameter Validation Rules

[MUST] Validate parameters before calling API to avoid InvalidParameter errors:

Source: aliyun csas \x3Ccommand> --help

All enum values are case-sensitive. List parameters use space-separated values (NOT comma).

[MUST] When user provides a SaseUserId or DeviceTag that looks wrong:

Do NOT blindly call the API. Offer to look up the correct value:

• SaseUserId: use aliyun csas list-users --fuzzy-username \x3Cname> to find real ID
• DeviceTag: use aliyun csas list-user-devices --username \x3Cname> to find real tag

list-user-devices

Query devices with any combination of 20+ filters:

aliyun csas list-user-devices --current-page 1 --page-size 100 [OPTIONS] [--pager]

Key filters: --department, --device-types (list), --device-statuses (list), --dlp-statuses, --pa-statuses, --ia-statuses, --nac-statuses, --username, --device-belong, --hostname, --sort-by.

List params use space-separated values: --device-types Windows macOS

Enum values:

• DeviceStatuses: Online Offline LongTermOffline Locked Lost Unbound
• DeviceTypes: Windows macOS Linux Android iOS Windows_Wuying
• DlpStatuses: Enabled Disabled Unprovisioned Unauthorized
• PaStatuses/IaStatuses/NacStatuses: Enabled Disabled Unprovisioned

list-users

aliyun csas list-users --current-page 1 --page-size 100 [OPTIONS] [--pager]

Key filters: --fuzzy-username, --precise-username, --department, --status (Enabled/Disabled), --sase-user-ids (list).

list-user-applications

Query private access applications authorized to a user:

aliyun csas list-user-applications --sase-user-id \x3CID> --current-page 1 --page-size 100

Required: --sase-user-id. Optional: --name, --address.

get-user-device

Get full detail for a single device:

aliyun csas get-user-device --device-tag \x3CTAG>

get-active-idp-config

Get the active Identity Provider configuration:

aliyun csas get-active-idp-config

list-user-groups

aliyun csas list-user-groups --current-page 1 --page-size 100 [OPTIONS] [--pager]

Key filters: --name, --attribute-value, --user-group-ids (list), --pa-policy-id.

Output Formatting

When presenting query results to users, follow these rules to avoid overwhelming output:

Result count thresholds:

• ≤10 items: show all
• 11–50 items: show top 20 + total count
• >50 items: show top 20 + total count + suggest narrowing filters

Table format: Use markdown table with key columns only (not full JSON). Example columns for devices: #, user, hostname, device type, relevant status, department.

Use --cli-query to extract fields at API level:

aliyun csas list-user-devices --dlp-statuses Disabled --current-page 1 --page-size 100 \
  --cli-query "{total: TotalNum, devices: Devices[].{user: Username, host: Hostname, type: DeviceType, dlp: DlpStatus, dept: Department}}"

Always state the total before showing partial results, e.g. "Total 844 devices with DLP disabled, showing top 20:"

Script-Based Operations

Inactive Analysis (read-only)

Identifies inactive devices based on UpdateTime threshold:

bash scripts/inactive-analysis.sh --days 30 [--max-days 180]

Options: --days N (>=1, default 30), --max-days M (optional, upper bound), --department, --device-type, --page-size

Parameter semantics:

• --days N alone: select all devices with UpdateTime \x3C today-N (inactive ≥ N days)
• --days N --max-days M: select devices with today-M ≤ UpdateTime \x3C today-N (inactive N~M days)

Common patterns:

[MUST] When user's time range is ambiguous, ask to clarify before executing:

"Does 'inactive for 90 days' mean all devices ≥90 days, or only the 90~180 day window?"

Output: JSON with inactive device list and summary statistics. No write operations.

Note: User activity analysis is NOT supported. Reason: the list-users API does not return a last-active timestamp, and device binding changes when another user logs in (each device only retains the most recent user). Therefore user activity status cannot be determined accurately. For user-level analysis, refer to the SASE console audit logs.

When users ask about dormant accounts or stale devices, this is the starting point.

Cleanup Inactive Devices (destructive, reversible)

Lock devices inactive for N days. Follows Write Operation Rules below.

Step 1 — Preview:

bash scripts/cleanup-inactive.sh --days 90 --dry-run

Present dry-run output to user:

• Total devices scanned, inactive count, device list with details
• Follow Output Formatting rules above (≤10 show all, >10 show top 20 + total)
• Ask user for explicit confirmation before Step 2

Step 2 — Execute (only after user confirms):

bash scripts/cleanup-inactive.sh --days 90 --yes

Locks all inactive devices in batches (≤100 per API call). Lock is idempotent and reversible.

Step 3 — Verify and report:

After execution:

1. Post-action verification — call aliyun csas get-user-device --device-tag \x3CTAG> for each locked device (or sample if many) to confirm DeviceStatus == "Locked". This forms the operation closure: pre-state (dry-run) → execute → post-state (verify).
2. Format the result for the user — do NOT dump the raw script JSON. Convert into a markdown summary:
   • One-line conclusion, e.g. "Lock complete: 3 scanned, 1 locked, 0 failed."
   • Markdown table of locked devices (DeviceTag, Username, Hostname, DeviceType, new status)
   • Recovery hint: aliyun csas update-user-devices-status --device-action Unlocked --device-tags \x3CTAGS> to revert.
3. If failures exist — list failed DeviceTags and advise retry on those tags only.

Write Operation Rules

[MUST] All write operations require user confirmation:

1. Present what will be done (target devices/users, action, count)
2. Ask user to confirm and wait for explicit yes
3. Only execute after user confirms — NEVER auto-execute

[MUST] Cancellation handling: When user cancels (replies "no", "cancel", "stop", or anything other than explicit confirmation):

1. Do NOT execute the destructive action
2. Do NOT silently end the session — offer next-step options:

   "Operation cancelled. Other options: (a) modify scope (e.g. different time range or filters); (b) view the device list only without locking; (c) export DeviceTag list for manual review; (d) exit. Which would you like?"

3. Wait for user choice before proceeding
4. If user confirms exit, end gracefully with a summary of what was NOT done

[MUST] Idempotent execution:

• Even if target set is empty (0 devices match), still run the command and report "0 affected"
• Even if devices are already in target state (e.g. already Locked), still execute — the API is idempotent
• Never skip execution with "already done" — always run and report actual result

[MUST] Post-action verification (operation closure): Every write operation must form a closed loop: pre-check → execute → post-verify.

1. Before write: confirm the target list (dry-run preview).
2. Execute the write operation.
3. After write: re-query the affected resources (e.g. get-user-device --device-tag \x3CTAG>) and confirm the new state matches the intended action.
4. Report the verified result, not just the script's success flag.

[MUST] Final result formatting: Never dump raw script JSON to the user as the final answer. Always:

1. Lead with a one-line conclusion (e.g. "✅ Lock complete: 1/1 devices locked, 0 failed")
2. Show key details in a markdown table (key columns only)
3. Append a recovery / next-step hint when applicable
4. End with the AI-Mode disable command (see Pre-checks)

[MUST] Quiet execution: During multi-step operations, minimize narration between tool calls.

• Do NOT announce trivial steps like "Now I will enable AI mode" or "Executing the lock command"
• Do NOT echo (no output) or empty tool results
• Only speak to the user when: (a) presenting preview/results, (b) asking for confirmation, (c) reporting errors
• Internal tool chaining should be silent until a user-facing milestone is reached

Applies to:

• bash scripts/cleanup-inactive.sh --yes (batch lock)
• aliyun csas update-user-devices-status --device-action \x3CACTION> --device-tags \x3CTAGS> (direct lock/unlock)

Confirmation template:

"About to execute [Locked/Unlocked/Lost/Found] on N devices. Confirm?"

Capability Boundary

This skill does NOT perform irreversible operations:

• Delete user accounts (DeleteClientUser)
• Delete terminal devices (DeleteUserDevices)
• Freeze/unfreeze user accounts (UpdateUsersStatus)
• Analyze user activity (API limitation: no user last-active time available)

[MUST] When users request deletion of inactive users/devices, follow this flow:

1. Clarify scope — This skill only analyzes and operates on devices, not user activity:

   "Only inactive device queries and device locking are supported. User activity analysis is not available (API limitation). Want to check which devices have been inactive for N+ days?"

2. Guide to device analysis — Lead user to specify a time range for devices:

   "I can help you: query devices inactive for N+ days; query devices inactive within N~M day range; lock these devices (reversible, unlock anytime). Which time range do you need?"

3. Explain why deletion is not supported:

   "Deletion is irreversible — this skill does not perform it. Locking has the same effect (device cannot connect). You can delete via console after confirming."

4. Offer the lock alternative with specific details:

   "Lock these N devices instead? Once locked, they cannot access the network. Unlock anytime."

5. If user insists on deletion, guide to console:

   "Go to Alibaba Cloud Console → SASE → Terminal Management to delete manually. I can export the DeviceTag list for batch operations in the console."

6. If user accepts lock, proceed with Write Operation Rules (preview → confirm → execute).

Never silently refuse. Always present the alternative action path.

Error Handling

All scripts output structured JSON with success: true/false. On failure, check error and message fields.

Common errors:

• ApiCallFailed — Check network, credentials, and permissions
• ValidationError — Invalid parameter; see error message for details
• Permission denied / HTTP 403 / AccessDenied — Follow RAM Policy & Permission Handling section above. Suggest AliyunCSASFullAccess (quick) or add specific csas:\x3CApiName> Action (minimal).
• File system errors (write_file failed, output path not exist) — Check that the output directory exists and is writable. Fall back to printing the report to stdout if the path cannot be written.

All write operations are idempotent. Safe to retry on partial failure. Even if target is empty or already in desired state, execute anyway and report result.

Script Reference

Full API parameter reference: references/api-reference.md CLI command list: references/related-commands.md