alibabacloud-csas-user-device-ops

事前確認

Aliyun CLI >= 3.3.3 が必要です

aliyun version

インストールされていない場合、またはバージョンが古い場合は、references/cli-installation-guide.md を参照してください。

プラグインのセットアップ（初回使用前に必ず実行）

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

AI モードのライフサイクル（必ず従ってください）

ワークフローの開始時（CLI を実行する前）：

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

すべての終了時点（成功、失敗、エラー、キャンセル時、および各書き込み操作の完了後を含む）：

aliyun configure ai-mode disable

［必須］ 操作が成功した場合も、ai-mode disable を実行してください。これはエラー時だけでなく、成功時の手順にも含まれます。

認証情報の確認

セキュリティルール：

• AK/SK の値を読み取ったり、エコーしたり、表示したりすることは絶対にしないでください
• 会話の中でユーザーに AK/SK の入力を絶対に求めないでください
• 認証情報の状態を確認するには、aliyun configure listのみを使用してください

aliyun configure list

有効なプロファイルが存在しない場合は、処理を停止してください。このセッション外で認証情報を設定するよう、ユーザーに案内してください。

RAM ポリシーと権限の処理

必要な権限については、references/ram-policies.md に記載されています。

［必須］権限エラーの処理： HTTP 403、「AccessDenied」、「Forbidden」、「no permission」などの権限エラーが原因でコマンドが失敗した場合：

1. ただちに実行を停止してください。むやみに再試行しないでください。
2. エラーメッセージから失敗した API を特定してください（例：csas:ListUserDevices、csas:UpdateUserDevicesStatus）。
3. 失敗した RAM Action を正確にユーザーに伝え、次の 2 つの方法を提示してください：
   • 簡単な方法： RAM ユーザー／ロールにシステムポリシー AliyunCSASFullAccess をアタッチします（すべての CSAS 操作が対象です）。
   • 最小限の方法： 失敗した特定の Action のみをカスタムポリシーに追加します。最小限のポリシーテンプレートについては、references/ram-policies.md を参照してください。
4. ユーザーが権限を付与したことを確認するまで待ってください。
5. 確認後、失敗した操作を再試行してください。

権限エラーメッセージのテンプレート：

「csas:<ApiName> の呼び出しが拒否されました。AliyunCSASFullAccess（すべての操作を対象とするシステムポリシー）を付与するか、csas:<ApiName> をカスタム RAM ポリシーに追加してください。詳細は references/ram-policies.md を参照してください。権限を付与した後に「done」と返信してください。再試行します。」

操作の振り分け

ユーザーの意図に合わせて実行方法を選択してください：

ユーザーの意図	実行方法
デバイスの検索／フィルタリング（条件の組み合わせは任意）	パラメーターを指定して aliyun csas list-user-devices を実行
ユーザー一覧の検索（部署、ステータス、名前で検索）	パラメーターを指定して aliyun csas list-users を実行
ユーザーがアクセスできるアプリの確認	aliyun csas list-user-applications
単一デバイスの詳細取得	aliyun csas get-user-device
IDP ID ソース設定の確認	aliyun csas get-active-idp-config
ユーザーグループの検索	aliyun csas list-user-groups
非アクティブなデバイスの分析	bash scripts/inactive-analysis.sh
非アクティブなデバイスのロック	bash scripts/cleanup-inactive.sh
ユーザーアカウントまたはデバイスの削除	サポート対象外 — SASE コンソールを案内

クエリの変換例：

• 「QA 部門にある、DLP が無効の macOS デバイスを表示」 → aliyun csas list-user-devices --department QA --device-types macOS --dlp-statuses Disabled --pager
• 「個人所有で、長期間オフラインになっているデバイスはどれか」 → aliyun csas list-user-devices --device-belong Personal --device-statuses LongTermOffline --pager
• 「ユーザーがアクセスを許可されている社内アプリは何か」 → aliyun csas list-user-applications --sase-user-id <ID> --current-page 1 --page-size 100
• 「オンラインの Windows デバイスは何台あるか」 → aliyun csas list-user-devices --device-types Windows --device-statuses Online --current-page 1 --page-size 1（TotalNum を確認）

CLI コマンドを直接実行

すべてのクエリは、プラグインモードで aliyun csas を直接使用します。全件を自動でページネーションするには、--pager を使用してください。 すべてのパラメーターの詳細については、references/api-reference.md を参照してください。

パラメーターの検証ルール

[MUST] InvalidParameter エラーを避けるため、API を呼び出す前にパラメーターを検証してください：

ソース：aliyun csas <command> --help

パラメーター	制約	例	ソース
--current-page	int、1～10000	1	CLI ヘルプ
--page-size	int、1～500（list-user-applications の場合は 1～100）	100	CLI ヘルプ
--device-action	enum：Locked Lost Unbound Unlocked Found	Locked	CLI ヘルプ
--device-statuses	enum リスト	Online LongTermOffline	CLI ヘルプ
--device-types	enum リスト	Windows macOS	CLI ヘルプ
--device-belong	enum：Personal Company	Company	CLI ヘルプ
--sort-by	enum：Username AppVersion UpdateTime	UpdateTime	CLI ヘルプ
--status（list-users）	enum：Enabled Disabled	Enabled	CLI ヘルプ
--dlp-statuses	enum リスト：Enabled Disabled Unprovisioned Unauthorized	Disabled Unprovisioned	CLI ヘルプ
--pa-statuses	enum リスト：Enabled Disabled Unprovisioned	Enabled	CLI ヘルプ
--ia-statuses	enum リスト：Enabled Disabled Unprovisioned	Disabled	CLI ヘルプ
--nac-statuses	enum リスト：Enabled Disabled Unprovisioned	Unprovisioned	CLI ヘルプ
--sase-user-id	API レスポンスの SaseUserId フィールドから取得	su_2e10e16a****0566abea4ce6	確認済み
--sase-user-ids	SaseUserId のリスト	su_2e10****4ce6 su_ef48****573b	確認済み
--device-tag	API レスポンスの DeviceTag フィールドから取得	480F8E02-****-5932A5FF60BC	確認済み
--device-tags	DeviceTag のリスト	480F8E02-****-60BC 24BB1571-****-86EF	確認済み
--username	文字列	test001	CLI ヘルプ
--fuzzy-username	文字列、あいまい一致	zhang	CLI ヘルプ
--precise-username	文字列、完全一致	zhangsan	CLI ヘルプ
--department	文字列	Engineering	CLI ヘルプ
--hostname	文字列	MacBook-Pro	CLI ヘルプ
--mac	文字列	3c:06:****:79:1b	CLI ヘルプ
--inner-ip	文字列	10.0.**.**	CLI ヘルプ
--user-group-ids	リスト	usergroup-51bd****a540	確認済み
--name（list-user-applications）	文字列	CRM	CLI ヘルプ
--address（list-user-applications）	文字列（IPv4/CIDR/ドメイン）	192.168.1.0/24	CLI ヘルプ

すべての enum 値は大文字と小文字を区別します。リスト型パラメーターの値はスペース区切りで指定します（カンマ区切りではありません）。

[MUST] ユーザーが誤っているように見える SaseUserId または DeviceTag を指定した場合：

API をむやみに呼び出さないでください。正しい値を検索する方法を案内してください：

• SaseUserId：aliyun csas list-users --fuzzy-username <name> を使用して実際の ID を検索します
• DeviceTag：aliyun csas list-user-devices --username <name> を使用して実際のタグを検索します

list-user-devices

20 種類以上のフィルターを任意に組み合わせてデバイスを検索します：

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

主なフィルター：--department、--device-types（リスト）、--device-statuses（リスト）、--dlp-statuses、--pa-statuses、--ia-statuses、--nac-statuses、--username、--device-belong、--hostname、--sort-by。

リスト型パラメーターの値はスペース区切りで指定します：--device-types Windows macOS

enum 値：

• 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]

主なフィルター：--fuzzy-username、--precise-username、--department、--status（Enabled/Disabled）、--sase-user-ids（リスト）。

list-user-applications

ユーザーに認可されているプライベートアクセスアプリケーションを検索します：

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

必須：--sase-user-id。任意：--name、--address。

get-user-device

単一デバイスの詳細情報を取得します：

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

get-active-idp-config

有効な ID プロバイダーの設定を取得します：

aliyun csas get-active-idp-config

list-user-groups

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

主なフィルター：--name、--attribute-value、--user-group-ids（リスト）、--pa-policy-id。

出力形式

クエリ結果をユーザーに提示するときは、出力が多くなりすぎないよう、次のルールに従ってください。

結果件数の基準：

• ≤10 件：すべて表示
• 11～50 件：上位 20 件＋合計件数を表示
• >50 件：上位 20 件＋合計件数を表示し、フィルターを絞り込むよう提案

表形式： 主要な列のみを含む Markdown 表を使用してください（JSON 全体は表示しないでください）。デバイスの例では、列は #、ユーザー、ホスト名、デバイスタイプ、関連するステータス、部門などです。

API レベルでフィールドを抽出するには --cli-query を使用してください：

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}}"

一部の結果を表示する前に、必ず合計件数を明記してください。 例：「DLP が無効なデバイスは合計 844 台です。上位 20 件を表示します。」

スクリプトベースの操作

非アクティブ状態の分析（読み取り専用）

UpdateTime のしきい値に基づいて、非アクティブなデバイスを特定します。

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

オプション：--days N（>=1、デフォルトは 30）、--max-days M（任意、上限）、--department、--device-type、--page-size

パラメーターの意味：

• --days N のみ：UpdateTime < 今日-N のデバイスをすべて選択します（非アクティブ期間が N 日以上）。
• --days N --max-days M：今日-M ≤ UpdateTime < 今日-N のデバイスを選択します（非アクティブ期間が N～M 日）。

よくあるパターン：

ユーザーの発言	パラメーター
「90 日以上非アクティブ」	--days 90
「90～180 日間非アクティブ」	--days 90 --max-days 180
「180 日以上非アクティブ」	--days 180
「1 年以上非アクティブ」	--days 365
「6 か月～1 年間非アクティブ」	--days 180 --max-days 365

［必須］ユーザーが指定した期間の範囲が曖昧な場合は、実行前に確認してください：

「『90 日間非アクティブ』とは、90 日以上のすべてのデバイスですか。それとも 90～180 日の範囲のみですか？」

出力：非アクティブなデバイスの一覧と概要統計を含む JSON。書き込み操作は行いません。

注： ユーザーのアクティビティ分析には対応していません。理由：list-users API は最終アクティブ日時を返さず、別のユーザーがログインするとデバイスの紐付けが変更されるため（各デバイスに保持されるユーザーは最新のユーザーのみです）。そのため、ユーザーのアクティビティ状態を正確に判定できません。 ユーザーレベルの分析については、SASE コンソールの監査ログを参照してください。

ユーザーから休眠アカウントや古いデバイスについて尋ねられた場合は、ここから始めてください。

非アクティブなデバイスのクリーンアップ（破壊的、元に戻せます）

N 日間非アクティブなデバイスをロックします。以下の「書き込み操作のルール」に従います。

ステップ 1 — プレビュー：

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

ドライランの出力をユーザーに提示します。

• スキャンしたデバイスの合計数、非アクティブなデバイス数、詳細を含むデバイス一覧
• 上記の出力形式のルールに従います（≤10 件はすべて表示、>10 件は上位 20 件＋合計件数を表示）
• ステップ 2 の前に、ユーザーに明示的な確認を求めてください

ステップ 2 — 実行（ユーザーが確認した場合のみ）：

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

すべての非アクティブなデバイスをバッチ処理でロックします（API 呼び出し 1 回あたり ≤100 件）。ロック操作は冪等で、元に戻せます。

ステップ 3 — 検証と報告：

実行後：

1. 実行後の検証 — ロックした各デバイスに対して（件数が多い場合は一部をサンプルとして）aliyun csas get-user-device --device-tag <TAG> を呼び出し、DeviceStatus == "Locked" であることを確認します。これにより、操作の一連の流れが完了します：実行前の状態（ドライラン）→ 実行 → 実行後の状態（検証）。
2. 結果をユーザー向けに整形 — スクリプトの生の JSON をそのまま出力しないでください。Markdown の要約に変換します。
   • 1 行の結論（例：「ロック完了：3 台をスキャンし、1 台をロック、0 台が失敗しました。」）
   • ロックしたデバイスの Markdown 表（DeviceTag、Username、Hostname、DeviceType、新しいステータス）
   • 復旧方法のヒント：元に戻すには aliyun csas update-user-devices-status --device-action Unlocked --device-tags <TAGS> を使用します。
3. 失敗がある場合 — 失敗した DeviceTag を列挙し、それらのタグのみ再試行するよう案内してください。

書き込み操作のルール

[MUST] すべての書き込み操作にはユーザーの確認が必要です：

1. 実行する内容（対象のデバイス／ユーザー、操作、件数）を提示します
2. ユーザーに確認を求め、明示的な「はい」の返答を待ちます
3. ユーザーの確認後にのみ実行します — 決して自動実行しないでください

[MUST] キャンセルへの対応： ユーザーがキャンセルした場合（「いいえ」、「キャンセル」、「停止」、または明示的な確認以外の返答）：

1. 破壊的な操作を実行しないでください
2. セッションを黙って終了しないでください — 次の選択肢を提示します：

   "操作をキャンセルしました。他の選択肢： (a) 対象範囲を変更する（例：別の期間やフィルター）；(b) ロックせずにデバイスリストのみを表示する；(c) DeviceTag リストをエクスポートして手動で確認する；(d) 終了する。どれにしますか？"

3. 先に進む前に、ユーザーの選択を待ちます
4. ユーザーが終了を確認した場合は、実行しなかった内容をまとめて、適切に終了します

[MUST] 冪等な実行：

• 対象が空（該当するデバイスが 0 台）の場合でも、コマンドを実行し、「影響を受けた件数：0」と報告します
• デバイスがすでに対象の状態（例：すでに Locked）であっても、実行します — API は冪等です
• 「すでに完了」として実行をスキップしないでください — 必ず実行し、実際の結果を報告します

[MUST] 操作後の検証（操作の完了確認）： すべての書き込み操作を、事前確認 → 実行 → 実行後の検証という一連の流れで完了させます。

1. 書き込みの前に、対象リストを確認します（ドライランのプレビュー）。
2. 書き込み操作を実行します。
3. 書き込みの後に、影響を受けたリソースを再照会し（例：get-user-device --device-tag <TAG>）、新しい状態が意図した操作と一致することを確認します。
4. スクリプトの成功フラグだけでなく、検証済みの結果を報告します。

[MUST] 最終結果の書式： 最終回答として、生のスクリプト JSON をユーザーにそのまま出力しないでください。必ず次のようにします：

1. 1 行の結論から始めます（例：「✅ ロック完了：1/1 台をロック、失敗 0 件」）
2. 主要な詳細を Markdown テーブルで示します（主要な列のみ）
3. 該当する場合は、復旧方法または次の手順のヒントを追加します
4. AI-Mode の無効化コマンドで締めくくります（「事前確認」を参照）

[MUST] 静かな実行： 複数段階の操作中は、ツール呼び出しの合間の説明を最小限にします。

• 「これから AI モードを有効にします」や「ロックコマンドを実行します」など、些細な手順を告知しないでください
• (no output) や空のツール結果を繰り返さないでください
• ユーザーに話すのは、次の場合に限ります：(a) プレビュー／結果を提示するとき、(b) 確認を求めるとき、(c) エラーを報告するとき
• ユーザー向けの節目に達するまでは、内部のツール連携を黙って進めます

対象：

• bash scripts/cleanup-inactive.sh --yes（一括ロック）
• aliyun csas update-user-devices-status --device-action <ACTION> --device-tags <TAGS>（直接ロック／ロック解除）

確認テンプレート：

"N 台のデバイスに [Locked/Unlocked/Lost/Found] を実行します。よろしいですか？"

機能の範囲

このスキルでは、元に戻せない操作は実行しません。

• ユーザーアカウントの削除（DeleteClientUser）
• 端末デバイスの削除（DeleteUserDevices）
• ユーザーアカウントの凍結／凍結解除（UpdateUsersStatus）
• ユーザーのアクティビティ分析（API の制限により、ユーザーの最終アクティブ時刻を取得できません）

［必須］ユーザーから非アクティブなユーザー／デバイスの削除を依頼された場合は、次の手順に従ってください。

1. 範囲を確認する — このスキルで分析・操作できるのはデバイスのみで、ユーザーのアクティビティは対象外です。

   「非アクティブなデバイスの照会とデバイスのロックのみ対応しています。ユーザーのアクティビティ分析は利用できません（API の制限）。N 日以上非アクティブなデバイスを確認しますか？」

2. デバイス分析に案内する — デバイスの期間を指定するようユーザーに案内します。

   「次の操作をお手伝いできます。N 日以上非アクティブなデバイスの照会、N〜M 日の範囲内で非アクティブなデバイスの照会、これらのデバイスのロック（元に戻せ、いつでも解除できます）です。どの期間を指定しますか？」

3. 削除に対応していない理由を説明する

   「削除は元に戻せないため、このスキルでは実行しません。ロックすれば同じ効果が得られ（デバイスは接続できなくなります）、いつでもロックを解除できます。確認後、コンソールから削除できます。」

4. ロックの代替案を具体的に提示する

   「代わりに、これら N 台のデバイスをロックしますか？ロックするとネットワークにアクセスできなくなります。ロックはいつでも解除できます。」

5. ユーザーが削除を希望する場合は、コンソールに案内する

   「Alibaba Cloud コンソール → SASE → 端末管理から手動で削除してください。コンソールで一括操作できるよう、DeviceTag リストをエクスポートできます。」

6. ユーザーがロックを承諾した場合は、書き込み操作のルールに従う（プレビュー → 確認 → 実行）。

**黙って拒否しないでください。**必ず代替の操作方法を提示してください。

エラー処理

すべてのスクリプトは、success: true/false を含む構造化 JSON を出力します。失敗した場合は、error フィールドと message フィールドを確認してください。

よくあるエラー：

• ApiCallFailed — ネットワーク、認証情報、権限を確認してください
• ValidationError — パラメーターが無効です。詳細はエラーメッセージを確認してください
• Permission denied / HTTP 403 / AccessDenied — 上記の RAM ポリシーと権限の処理に関するセクションに従ってください。AliyunCSASFullAccess（手早く設定する場合）または特定の csas:<ApiName> Action（最小限の権限にする場合）の追加を提案してください。
• ファイルシステムエラー（write_file の失敗、出力先パスが存在しない）— 出力ディレクトリが存在し、書き込み可能であることを確認してください。パスに書き込めない場合は、レポートを標準出力に表示してください。

すべての書き込み操作は冪等です。一部の処理が失敗した場合も、安全に再試行できます。対象が空またはすでに希望する状態であっても、操作を実行して結果を報告してください。

スクリプトリファレンス

スクリプト	用途
scripts/validate-cli.sh	CLI 環境の検証
scripts/inactive-analysis.sh	非アクティブなデバイスの読み取り専用分析
scripts/cleanup-inactive.sh	非アクティブなデバイスのロック（破壊的ですが、元に戻せます）
scripts/common.sh	共通ユーティリティ（他のスクリプトから読み込まれます）

API パラメーターの全リファレンス：references/api-reference.md CLI コマンド一覧：references/related-commands.md