@clickzetta/cz-cli-darwin-x64 0.3.17 → 0.3.19

package/bin/skills/clickzetta-access-control/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: clickzetta-access-control
+description: |
+  管理 ClickZetta Lakehouse 的用户、角色和权限（RBAC），以及列级动态数据脱敏。
+  覆盖用户创建/修改/删除、自定义角色管理、GRANT/REVOKE 细粒度授权、
+  SHOW GRANTS 权限查看、动态脱敏策略创建与绑定等完整安全治理工作流。
+  当用户说"创建用户"、"添加用户"、"授权"、"GRANT"、"REVOKE"、"撤销权限"、
+  "创建角色"、"角色管理"、"RBAC"、"权限管理"、"查看权限"、"数据脱敏"、
+  "动态脱敏"、"列级安全"、"敏感数据保护"、"用户权限"、"网络策略"、
+  "IP 白名单"、"IP 黑名单"、"NETWORK POLICY"时触发。
+  Keywords: RBAC, GRANT, REVOKE, role, user, permission, masking policy, column-level security
+---
+
+# ClickZetta 访问控制与数据安全
+
+## 权限体系概览
+
+```
+账户（Account）
+└── 服务实例（Instance）
+    ├── 实例角色（instance_admin 等）
+    └── 工作空间（Workspace）
+        ├── 工作空间角色（workspace_admin / workspace_dev / workspace_analyst）
+        ├── 自定义角色（CREATE ROLE）
+        └── 用户（User）
+```
+
+**推荐做法**：优先使用角色（RBAC）管理权限，而非直接对用户逐个授权（ACL）。
+
+## ⚠️ 关键注意事项
+
+- `CREATE USER` **不是创建新账户**，而是将已有账户用户添加到当前工作空间。用户必须先在管理中心（账户管理系统）中创建，才能执行 `CREATE USER`
+- 自定义角色只能通过 SQL 创建，Web 端暂不支持
+- 动态脱敏功能当前处于受邀预览阶段，需联系技术支持开通
+
+---
+
+阅读 [references/user-management.md](references/user-management.md)
+
+```sql
+-- 将已有账户用户添加到工作空间
+CREATE USER alice DEFAULT_VCLUSTER = default_ap DEFAULT_SCHEMA = public;
+
+-- 修改用户默认集群/Schema
+ALTER USER alice SET DEFAULT_VCLUSTER = default_ap DEFAULT_SCHEMA = dw;
+
+-- 查看所有用户
+SHOW USERS;
+
+-- 从工作空间移除用户
+DROP USER IF EXISTS alice;
+```
+
+---
+
+## 步骤 2：角色管理
+
+阅读 [references/role-management.md](references/role-management.md)
+
+```sql
+-- 查看所有角色（含预置角色）
+SHOW ROLES;
+
+-- 创建自定义角色
+CREATE ROLE analyst_role COMMENT '数据分析师角色';
+
+-- 将角色授予用户
+GRANT ROLE analyst_role TO USER alice;
+
+-- 从用户撤销角色
+REVOKE ROLE analyst_role FROM USER alice;
+
+-- 删除自定义角色
+DROP ROLE IF EXISTS analyst_role;
+```
+
+系统预置角色：`instance_admin`、`workspace_admin`、`workspace_dev`、`workspace_analyst`
+
+---
+
+## 步骤 3：权限授予与撤销
+
+阅读 [references/grant-revoke.md](references/grant-revoke.md)
+
+### 常用授权场景
+
+```sql
+-- 授予表查询权限
+GRANT SELECT ON TABLE public.orders TO USER alice;
+GRANT SELECT ON TABLE public.orders TO ROLE analyst_role;
+
+-- 授予 Schema 下所有权限
+GRANT ALL ON SCHEMA public TO ROLE dev_role;
+
+-- 授予使用计算集群权限
+GRANT USE ON VCLUSTER default_ap TO USER alice;
+
+-- 授予创建表权限
+GRANT CREATE TABLE ON SCHEMA public TO USER alice;
+```
+
+### 撤销权限
+
+```sql
+REVOKE SELECT ON TABLE public.orders FROM USER alice;
+REVOKE ALL PRIVILEGES ON WORKSPACE ws_name FROM USER alice;
+```
+
+### 查看权限
+
+```sql
+-- 查看当前用户权限
+SHOW GRANTS;
+
+-- 查看指定用户权限
+SHOW GRANTS TO USER alice;
+
+-- 查看工作空间角色权限
+SHOW GRANTS TO ROLE analyst_role;
+
+-- 查看实例级角色权限
+SHOW GRANTS TO INSTANCE ROLE instance_admin;
+```
+
+---
+
+## 步骤 4：动态数据脱敏（预览功能）
+
+阅读 [references/dynamic-masking.md](references/dynamic-masking.md)
+
+> ⚠️ 当前处于受邀预览阶段，需联系技术支持开通。
+
+```sql
+-- 1. 创建脱敏函数（管理员看原文，其他人看脱敏）
+CREATE FUNCTION public.mask_phone(phone STRING)
+RETURNS STRING
+AS CASE
+    WHEN current_user() = 'admin' THEN phone
+    ELSE CONCAT(SUBSTR(phone, 1, 3), '****', SUBSTR(phone, 8, 4))
+END;
+
+-- 2. 绑定到列
+ALTER TABLE customers
+CHANGE COLUMN phone
+SET MASK public.mask_phone;
+
+-- 3. 解除脱敏
+ALTER TABLE customers
+CHANGE COLUMN phone
+UNSET MASK;
+```
+
+---
+
+## 典型场景
+
+### 场景 A：新员工入职授权
+
+```sql
+-- 1. 添加用户到工作空间
+CREATE USER new_employee DEFAULT_VCLUSTER = default_ap;
+
+-- 2. 授予分析师角色
+GRANT ROLE workspace_analyst TO USER new_employee;
+
+-- 3. 额外授予特定表的写入权限
+GRANT INSERT ON TABLE public.reports TO USER new_employee;
+```
+
+### 场景 B：创建只读角色并批量授权
+
+```sql
+-- 1. 创建只读角色
+CREATE ROLE readonly_role COMMENT '只读访问角色';
+
+-- 2. 授予 Schema 下所有表的查询权限
+GRANT SELECT ON TABLE public.orders TO ROLE readonly_role;
+GRANT SELECT ON TABLE public.customers TO ROLE readonly_role;
+GRANT USE ON VCLUSTER default_ap TO ROLE readonly_role;
+
+-- 3. 将角色授予多个用户
+GRANT ROLE readonly_role TO USER alice;
+GRANT ROLE readonly_role TO USER bob;
+```
+
+---
+
+## 常见问题
+
+| 问题 | 原因 | 解决方案 |
+|---|---|---|
+| CREATE USER 报错用户不存在 | 用户未在账户管理系统中创建 | 先在管理中心创建账户用户，再执行 CREATE USER |
+| GRANT 后用户仍无法查询 | 缺少 USE VCLUSTER 权限 | `GRANT USE ON VCLUSTER default_ap TO USER alice` |
+| 自定义角色无法在 Web 端创建 | 产品限制 | 只能通过 SQL 创建自定义角色 |
+| 脱敏函数不生效 | 功能未开通 | 联系技术支持开通动态脱敏预览功能 |
+
+---
+
+## 步骤 5：网络策略（IP 白名单/黑名单）
+
+通过网络策略控制对 Lakehouse 服务实例的 JDBC、SDK 及 Web 访问，支持白名单和黑名单模式。
+
+```sql
+-- 创建网络策略（白名单模式：仅允许指定 IP 访问）
+CREATE NETWORK POLICY office_only
+  ALLOWED_IP_LIST = ('10.0.0.0/8', '172.16.0.0/12')
+  COMMENT '仅允许办公网络访问';
+
+-- 创建网络策略（黑名单模式：阻止指定 IP）
+CREATE NETWORK POLICY block_external
+  BLOCKED_IP_LIST = ('203.0.113.0/24')
+  COMMENT '阻止外部 IP';
+
+-- 同时设置白名单和黑名单（Deny 优先）
+CREATE NETWORK POLICY mixed_policy
+  ALLOWED_IP_LIST = ('10.0.0.0/8')
+  BLOCKED_IP_LIST = ('10.0.1.100/32')
+  COMMENT '允许内网但阻止特定 IP';
+
+-- 查看网络策略
+SHOW NETWORK POLICY;
+
+-- 删除网络策略
+DROP NETWORK POLICY IF EXISTS office_only;
+```
+
+> ⚠️ 网络策略遵循 **Deny 优先** 原则：同时出现在白名单和黑名单中的 IP 会被拒绝。
+
+---
+
+## 参考文档
+
+- [访问控制概览](https://www.yunqi.tech/documents/access-control-general)
+- [角色](https://www.yunqi.tech/documents/roles)
+- [GRANT](https://www.yunqi.tech/documents/grant-user-privileges)
+- [REVOKE](https://www.yunqi.tech/documents/revoke-user-privileges)
+- [CREATE USER](https://www.yunqi.tech/documents/CREAREUSER)
+- [ALTER USER](https://www.yunqi.tech/documents/alter-user)
+- [DROP USER](https://www.yunqi.tech/documents/DROPUSER)
+- [SHOW USERS](https://www.yunqi.tech/documents/SHOWUSERS)
+- [动态脱敏](https://www.yunqi.tech/documents/dynamic-mask)
+- [系统内置角色权限列表](https://www.yunqi.tech/documents/permissions-of-built-in-workspace-level-roles)
+- [网络策略](https://www.yunqi.tech/documents/network_policy)

package/bin/skills/clickzetta-access-control/eval_cases.jsonl

@@ -0,0 +1,3 @@
+{"case_id":"002","type":"should_call","user_input":"怎么查看当前工作空间有哪些用户？","expected_skill":"clickzetta-access-control","expected_output_contains":["SHOW USERS"]}
+{"case_id":"003","type":"should_call","user_input":"当前有哪些系统预置角色？各自有什么权限？","expected_skill":"clickzetta-access-control","expected_output_contains":["workspace_admin","workspace_dev"]}
+{"case_id":"004","type":"should_call","user_input":"怎么给某个用户授予 public schema 下所有表的只读权限？","expected_skill":"clickzetta-access-control","expected_output_contains":["GRANT","SELECT"]}

package/bin/skills/clickzetta-access-control/references/dynamic-masking.md

@@ -0,0 +1,86 @@
+# 动态数据脱敏参考
+
+> 来源：https://www.yunqi.tech/documents/dynamic-mask
+> ⚠️ 本功能当前处于**受邀预览发布**阶段，如需使用请联系技术支持。
+
+## 概述
+
+列级安全（Column-level Security）通过动态脱敏（Dynamic Data Masking）提供细粒度数据保护。系统仅存储原始数据，在查询时动态执行脱敏函数，根据用户身份或角色决定显示方式。
+
+## 步骤 1：创建脱敏策略函数
+
+```sql
+CREATE FUNCTION [schema_name.]function_name (col_name column_type)
+RETURNS output_type
+AS expression_with_conditional_logic;
+```
+
+关键要素：
+- 返回类型必须与原始列类型相同
+- 使用安全上下文函数：
+  - `current_user()` — 获取当前用户名（注意大小写）
+  - `current_roles()` — 获取用户角色数组
+
+示例：手机号脱敏（管理员看全部，其他人看脱敏）
+
+```sql
+CREATE FUNCTION public.mask_phone(phone STRING)
+RETURNS STRING
+AS CASE
+    WHEN current_user() = 'admin' THEN phone
+    ELSE CONCAT(SUBSTR(phone, 1, 3), '****', SUBSTR(phone, 8, 4))
+END;
+```
+
+示例：基于角色的脱敏
+
+```sql
+CREATE FUNCTION public.mask_salary(salary DECIMAL(10,2))
+RETURNS DECIMAL(10,2)
+AS CASE
+    WHEN array_contains(current_roles(), 'hr_role') THEN salary
+    ELSE 0.0
+END;
+```
+
+## 步骤 2：绑定脱敏策略到列
+
+### 建表时指定
+
+```sql
+CREATE TABLE employees (
+    emp_id INT,
+    name STRING,
+    phone STRING MASK public.mask_phone,
+    salary DECIMAL(10,2) MASK public.mask_salary
+);
+```
+
+### 修改已有表的列
+
+```sql
+ALTER TABLE employees
+CHANGE COLUMN phone
+SET MASK public.mask_phone;
+```
+
+### 添加新列时指定脱敏
+
+```sql
+ALTER TABLE employees
+ADD COLUMN id_card STRING MASK public.mask_id_card;
+```
+
+## 步骤 3：解除脱敏策略
+
+```sql
+ALTER TABLE employees
+CHANGE COLUMN phone
+UNSET MASK;
+```
+
+## 注意事项
+
+- 脱敏函数的返回类型必须与列类型完全一致
+- `current_user()` 返回值区分大小写
+- `current_roles()` 返回角色数组，用 `array_contains()` 判断

package/bin/skills/clickzetta-access-control/references/grant-revoke.md

@@ -0,0 +1,103 @@
+# GRANT / REVOKE 权限管理参考
+
+> 来源：https://www.yunqi.tech/documents/grant-user-privileges 和 revoke-user-privileges
+
+## GRANT 语法
+
+### 授权给用户
+
+```sql
+GRANT privilege_type ON object_type object_name TO USER user_name [WITH GRANT OPTION];
+```
+
+### 授权给角色
+
+```sql
+GRANT privilege_type ON object_type object_name TO ROLE role_name;
+```
+
+## 权限类型速查
+
+### 工作空间级（ON WORKSPACE）
+
+```sql
+-- 创建对象权限
+GRANT CREATE SCHEMA ON WORKSPACE ws_name TO USER alice;
+GRANT CREATE VCLUSTER ON WORKSPACE ws_name TO USER alice;
+```
+
+### 工作空间对象级（ON SCHEMA / VCLUSTER / ROLE / FUNCTION）
+
+```sql
+-- Schema 权限
+GRANT ALTER ON SCHEMA public TO USER alice;
+GRANT DROP ON SCHEMA public TO USER alice;
+GRANT READ METADATA ON SCHEMA public TO USER alice;
+GRANT ALL PRIVILEGES ON SCHEMA public TO USER alice;
+
+-- VCluster 权限
+GRANT USE ON VCLUSTER default_ap TO USER alice;
+GRANT ALTER ON VCLUSTER default_ap TO USER alice;
+```
+
+### Schema 级（ON SCHEMA，创建对象）
+
+```sql
+GRANT CREATE TABLE ON SCHEMA public TO USER alice;
+GRANT CREATE VIEW ON SCHEMA public TO USER alice;
+GRANT CREATE MATERIALIZED VIEW ON SCHEMA public TO USER alice;
+GRANT ALL ON SCHEMA public TO USER alice;
+```
+
+### 表/视图级（ON TABLE / VIEW / MATERIALIZED VIEW）
+
+```sql
+-- 表权限
+GRANT SELECT ON TABLE public.orders TO USER alice;
+GRANT INSERT ON TABLE public.orders TO USER alice;
+GRANT ALTER ON TABLE public.orders TO USER alice;
+GRANT DROP ON TABLE public.orders TO USER alice;
+GRANT ALL ON TABLE public.orders TO USER alice;
+
+-- 授权给角色
+GRANT SELECT ON TABLE public.orders TO ROLE analyst_role;
+```
+
+## REVOKE 语法
+
+```sql
+REVOKE privilege_type ON object_type object_name FROM USER user_name;
+REVOKE privilege_type ON object_type object_name FROM ROLE role_name;
+```
+
+## REVOKE 示例
+
+```sql
+-- 撤销创建 VCluster 权限
+REVOKE CREATE VCLUSTER ON WORKSPACE ws_name FROM USER alice;
+
+-- 撤销表查询权限
+REVOKE SELECT ON TABLE public.orders FROM USER alice;
+
+-- 撤销 Schema 下所有权限
+REVOKE ALL PRIVILEGES ON WORKSPACE ws_name FROM USER alice;
+
+-- 从角色撤销权限
+REVOKE CREATE VIEW ON SCHEMA sales FROM ROLE reporting_role;
+```
+
+## SHOW GRANTS（查看权限）
+
+```sql
+-- 查看当前用户的权限
+SHOW GRANTS;
+
+-- 查看指定用户的权限
+SHOW GRANTS TO USER user_name;
+
+-- 查看工作空间角色的权限
+SHOW GRANTS TO ROLE role_name;
+
+-- 查看实例角色的权限
+SHOW GRANTS TO INSTANCE ROLE role_name;
+```

package/bin/skills/clickzetta-access-control/references/role-management.md

@@ -0,0 +1,66 @@
+# 角色管理参考
+
+> 来源：https://www.yunqi.tech/documents/roles
+
+## 角色类型
+
+| 类型 | 说明 |
+|---|---|
+| **预置角色** | 平台自动配置，不可修改权限或删除，可直接授予用户 |
+| **自定义角色** | 在工作空间范围内创建，权限可随时修改，仅支持 SQL 操作 |
+
+## 角色级别
+
+- **实例角色（Instance Role）**：用于实例级资源全局管控，或跨多工作空间授权
+- **工作空间角色（Workspace Role）**：作用于特定工作空间，以工作空间为边界互不影响
+
+## 系统预置角色
+
+| 角色名 | 级别 | 说明 |
+|---|---|---|
+| `instance_admin` | 实例 | 实例管理员，最高权限 |
+| `workspace_admin` | 工作空间 | 工作空间管理员 |
+| `workspace_dev` | 工作空间 | 开发者，可创建和管理数据对象 |
+| `workspace_analyst` | 工作空间 | 分析师，只读权限 |
+
+详细权限列表参考：https://www.yunqi.tech/documents/permissions-of-built-in-workspace-level-roles
+
+## CREATE ROLE（创建自定义角色）
+
+```sql
+-- 工作空间角色
+CREATE ROLE [IF NOT EXISTS] role_name [COMMENT 'comment'];
+
+-- 实例级角色（Instance Role，跨工作空间）
+CREATE INSTANCE ROLE [IF NOT EXISTS] role_name [COMMENT 'comment'];
+```
+
+注意：自定义角色只能通过 SQL 创建，Web 端暂不支持。
+
+## GRANT ROLE（将角色授予用户）
+
+```sql
+-- 将角色授予用户
+GRANT ROLE role_name TO USER user_name;
+
+-- 将角色授予另一个角色（角色继承）
+GRANT ROLE role_name TO ROLE target_role_name;
+```
+
+## REVOKE ROLE（从用户撤销角色）
+
+```sql
+REVOKE ROLE role_name FROM USER user_name;
+```
+
+## SHOW ROLES（列出所有角色）
+
+```sql
+SHOW ROLES;
+```
+
+## DROP ROLE（删除自定义角色）
+
+```sql
+DROP ROLE [IF EXISTS] role_name;
+```

package/bin/skills/clickzetta-access-control/references/user-management.md

@@ -0,0 +1,61 @@
+# 用户管理参考
+
+> 来源：https://www.yunqi.tech/documents/CREAREUSER、ALTER USER、DROP USER、SHOW USERS
+
+## CREATE USER（将用户添加到工作空间）
+
+> ⚠️ `CREATE USER` 不是创建新账户，而是将已在账户管理系统中存在的用户添加到当前工作空间。
+> 用户必须先在管理中心创建账户，才能执行此命令。
+
+```sql
+CREATE USER [IF NOT EXISTS] user_name
+[DEFAULT_VCLUSTER = vc_name]
+[DEFAULT_SCHEMA = schema_name]
+[COMMENT "comment"];
+```
+
+参数说明：
+- `user_name`：必须是已在账户管理系统中创建的用户名
+- `DEFAULT_VCLUSTER`：用户默认计算集群，未指定则使用全局默认
+- `DEFAULT_SCHEMA`：用户默认 Schema，未指定则登录时需手动指定
+
+示例：
+```sql
+-- 基础添加
+CREATE USER alice;
+
+-- 指定默认集群和 Schema
+CREATE USER alice DEFAULT_VCLUSTER = default_ap DEFAULT_SCHEMA = public;
+
+-- 带注释
+CREATE USER alice COMMENT "数据分析师";
+```
+
+## ALTER USER（修改用户属性）
+
+```sql
+ALTER USER user_name SET
+[DEFAULT_VCLUSTER = vc_name]
+[DEFAULT_SCHEMA = schema_name];
+```
+
+示例：
+```sql
+ALTER USER alice SET DEFAULT_VCLUSTER = default_ap DEFAULT_SCHEMA = dw;
+```
+
+## DROP USER（从工作空间移除用户）
+
+```sql
+DROP USER [IF EXISTS] user_name;
+```
+
+注意：移除后用户无法访问该工作空间的任何资源。
+
+## SHOW USERS（列出所有用户）
+
+```sql
+SHOW USERS;
+```
+
+返回当前工作空间下所有用户的用户名和权限等级。