Alibabacloud Csas User Device Ops

Pre-checks#

Aliyun CLI >= 3.3.3 required

bash

aliyun version

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

Plugin setup (MUST run before first use)

bash

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

AI-Mode Lifecycle (MUST follow)

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

bash

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):

bash

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

bash

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:<ApiName>. Please grant either AliyunCSASFullAccess (system policy, covers all) or add csas:<ApiName> 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:

User IntentExecutionQuery/filter devices (any condition combo)aliyun csas list-user-devices with paramsQuery user list (by department, status, name)aliyun csas list-users with paramsCheck what apps a user can accessaliyun csas list-user-applicationsGet single device detailaliyun csas get-user-deviceCheck IDP identity source configaliyun csas get-active-idp-configQuery user groupsaliyun csas list-user-groupsAnalyze inactive devicesbash scripts/inactive-analysis.shLock inactive devicesbash scripts/cleanup-inactive.shDelete user accounts or devicesNOT supported — guide to SASE console

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 <ID> --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 <command> --help

ParameterConstraintExampleSource--current-pageint, 1~100001CLI help--page-sizeint, 1500 (list-user-applications: 1100)100CLI help--device-actionenum: Locked Lost Unbound Unlocked Found``LockedCLI help--device-statusesenum listOnline LongTermOfflineCLI help--device-typesenum listWindows macOSCLI help--device-belongenum: Personal Company``CompanyCLI help--sort-byenum: Username AppVersion UpdateTime``UpdateTimeCLI help--status (list-users)enum: Enabled Disabled``EnabledCLI help--dlp-statusesenum list: Enabled Disabled Unprovisioned Unauthorized``Disabled UnprovisionedCLI help--pa-statusesenum list: Enabled Disabled Unprovisioned``EnabledCLI help--ia-statusesenum list: Enabled Disabled Unprovisioned``DisabledCLI help--nac-statusesenum list: Enabled Disabled Unprovisioned``UnprovisionedCLI help--sase-user-idFrom API response SaseUserId fieldsu_2e10e16a****0566abea4ce6Observed--sase-user-idslist of SaseUserIdsu_2e10****4ce6 su_ef48****573bObserved--device-tagFrom API response DeviceTag field480F8E02-****-5932A5FF60BCObserved--device-tagslist of DeviceTag480F8E02-****-60BC 24BB1571-****-86EFObserved--usernamestringtest001CLI help--fuzzy-usernamestring, fuzzy matchzhangCLI help--precise-usernamestring, exact matchzhangsanCLI help--departmentstringEngineeringCLI help--hostnamestringMacBook-ProCLI help--macstring3c:06:****:79:1bCLI help--inner-ipstring10.0.**.**CLI help--user-group-idslistusergroup-51bd****a540Observed--name (list-user-applications)stringCRMCLI help--address (list-user-applications)string (IPv4/CIDR/domain)192.168.1.0/24CLI 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 <name> to find real ID
• DeviceTag: use aliyun csas list-user-devices --username <name> to find real tag

list-user-devices#

Query devices with any combination of 20+ filters:

bash

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#

bash

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:

bash

aliyun csas list-user-applications --sase-user-id <ID> --current-page 1 --page-size 100

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

get-user-device#

Get full detail for a single device:

bash

aliyun csas get-user-device --device-tag <TAG>

get-active-idp-config#

Get the active Identity Provider configuration:

bash

aliyun csas get-active-idp-config

list-user-groups#

bash

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:

bash

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

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 < today-N (inactive ≥ N days)
• --days N --max-days M: select devices with today-M ≤ UpdateTime < today-N (inactive N~M days)

Common patterns:

User saysParameters"Inactive for 90+ days"--days 90"Inactive 90~180 days"--days 90 --max-days 180"Inactive for 180+ days"--days 180"Inactive for over a year"--days 365"Inactive 6 months to 1 year"--days 180 --max-days 365

[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

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

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 <TAG> 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 <TAGS> 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 <TAG>) 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 <ACTION> --device-tags <TAGS> (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:<ApiName> 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#

ScriptPurposescripts/validate-cli.shCLI environment validationscripts/inactive-analysis.shRead-only inactive device analysisscripts/cleanup-inactive.shLock inactive devices (destructive, reversible)scripts/common.shShared utilities (sourced by other scripts)

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