mcpField
A
altinity-expert-clickhouse-grants

altinity-expert-clickhouse-grants

github.com/altinity数据与数据库1777 次安装6 周前更新
代码仓库

关于 altinity-expert-clickhouse-grants

用于排查 ClickHouse 操作受阻问题，并建议范围最小的授权或身份验证修复。它指导分析人员运行查询包、解读结果并整理报告。

主要功能

  1. 01检查访问与身份验证错误
  2. 02从失败查询识别缺失权限
  3. 03检查用户授权与角色
  4. 04建议最小范围的角色授权
  5. 05提供报告与后续处理指引

适用场景

  1. 01排查 ACCESS_DENIED 错误
  2. 02区分身份验证问题与权限缺失
  3. 03检查升级后的权限变化

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/altinity/altinity-skills --skill altinity-expert-clickhouse-grants

安装后在 Claude Code 中输入/altinity-expert-clickhouse-grants确认已加载。

附带文件checks.sqlreference.md

详细介绍

授权和身份验证错误

从 system.errors、system.query_log、system.grants 和 system.role_grants 中查明被阻止的操作缺少哪项权限，并计算解除阻止所需的最小授权。 如果尚未确定连接模式、集群和时间范围，请先运行 altinity-expert-clickhouse-connection。

查询包

  • checks.sql — 4 项检查：过去 24 小时内 system.errors 中的访问和身份验证错误（grants-01）、因异常代码 497 失败的查询所缺少的权限（grants-02）、受影响用户当前的授权（grants-03）、分配给受影响用户的角色（grants-04）。
  • reference.md — 背景信息（权限类别、access_control_improvements 默认值）；仅在需要解释建议时阅读。

如何运行查询包

  1. 从此技能的目录中读取每个包文件（技能加载器会输出目录路径）。
  2. 每次运行一条语句，绝不运行整个文件。语句以 ; 结尾，并以 -- @check <id> <title> 标头开头；将 id 与结果一同保留。
  3. 遵守 -- @requires：当指定的表不存在、需要 keeper 而服务器没有 Keeper/ZooKeeper，或不满足版本条件时，跳过该语句。列出跳过的 id 和原因。
  4. 如果存在集群宏，按原样保留 {cluster}；否则应用连接技能的重写规则。其他任何 {placeholder} 都是模板变量：先替换为实际值，否则跳过该语句。
  5. 出错时，记录检查 id 和错误的第一行，然后继续。仅当出现 UNKNOWN_IDENTIFIER 时，运行 DESCRIBE TABLE system.<table> 并移除缺失的列。
  6. severity 列是该行的判定结果。照录，不要重新评定。

解释规则

  • grants-02 中的 missing_privileges 是服务器自己的判断。根据这些值构建 GRANT 语句；不要根据查询文本推断权限。
  • 将每项授权限定在足以消除错误的最小对象范围内：优先使用列列表或 db.table，而非 db.*；优先使用 db.*，而非 *.*。超出所需范围的授权今天或许能消除错误，但之后会成为审计问题。
  • 如果 grants-04 显示用户已通过角色获得权限，优先通过角色授权。授予现有角色可保持模型一致；直接授予用户则会使模型分散。
  • grants-01 中的身份验证错误（AUTHENTICATION_FAILED、WRONG_PASSWORD、REQUIRED_PASSWORD）不是权限问题。不要为此建议 GRANT；应修正用户的身份验证方式或主机 ACL。
  • 这些权限涉及数据泄露、SSRF 或权限提升风险。只向角色授予所需的具体权限，绝不授予一揽子权限，也绝不授予 *.*：SOURCES 及其成员 S3、URL、FILE、REMOTE（25.7+ 还包括 READ 和 WRITE）；SYSTEM 和 INTROSPECTION，且范围限定为单个子命令。
  • 切勿为了修复常规的 ACCESS_DENIED 而授予 ACCESS MANAGEMENT、WITH GRANT OPTION、displaySecretsInShowAndSelect、NAMED COLLECTION ADMIN、ALLOW SQL SECURITY NONE 或 IMPERSONATE。这些权限都可能导致权限提升或秘密信息暴露，需要明确的理由。
  • 升级后，检查 access_control_improvements 标志 select_from_system_db_requires_grant、select_from_information_schema_requires_grant 和 on_cluster_queries_require_cluster_grant。启用这些标志后，以前可用的用户现在需要对 system.*、INFORMATION_SCHEMA.* 或 CLUSTER 进行显式授权；此时错误源于行为变更，而非授权丢失。

深入分析语句

最小授权遵循以下格式。每项缺失权限使用一条语句；采用最小对象范围，并在存在角色时使用角色。

GRANT SELECT ON system.processes TO role_analytics;

GRANT role_analytics TO user_x;

报告格式

  1. 标题：连接模式、集群或“单节点”、ClickHouse 版本、时间范围。
  2. 发现：包含 check、severity、object、evidence、recommendation 列的表格；每项发现占一行，按严重程度从 Critical 开始排列。证据引用结果行中的数字。
  3. 正常检查：用一行列出未返回问题行的检查 ID。
  4. 已跳过和失败的检查：列出 ID 和原因或第一条错误行。绝不能省略此部分。
  5. 后续步骤：接下来要加载的技能及立即采取的行动。

后续技能

  • 要确认谁拥有过多访问权限，而不是哪些访问被阻止 → 加载技能 altinity-expert-clickhouse-security
  • 需要针对版本的权限变更，并通过审计侧检查进行确认 → 加载技能 altinity-expert-clickhouse-security
  • 缺少或截断了 system.query_log，因此无法找到失败的查询 → 加载技能 altinity-expert-clickhouse-logs
  • 已设置授权，但 ON CLUSTER 语句失败或挂起 → 加载技能 altinity-expert-clickhouse-replication

评论

支持 Markdown